Solicitação de referências e privilégios de nível de objeto de consumidores¶
Este tópico descreve como os provedores podem solicitar acesso a objetos de banco de dados existentes na conta do consumidor.
Sobre as referências¶
Em alguns contextos, um Snowflake Native App instalado precisa acessar objetos existentes na conta do consumidor que existem fora do objeto APPLICATION. Por exemplo, um Snowflake Native App pode precisar acessar tabelas existentes em um banco de dados do consumidor.
Neste caso, não basta que o consumidor apenas conceda acesso em um objeto ao Snowflake Native App. O Snowflake Native App não pode determinar os nomes do esquema e dos objetos que existem na conta do consumidor. Consulte Resolução de nomes de objetos para informações adicionais.
Para permitir que o Snowflake Native App se conecte a esses tipos de objetos, o Snowflake Native App Framework fornece referências que permitem ao cliente especificar os nomes dos objetos e conceder os privilégios necessários.
Fluxo de trabalho para definição de referências na conta do consumidor¶
Para solicitar uma referência e privilégio de nível de objeto, o provedor executa o seguinte ao desenvolver e publicar um Snowflake Native App:
Determine quais objetos exigem referências e seus privilégios correspondentes.
Adicione um procedimento armazenado no script de configuração para manipular o retorno de chamada para cada referência definida no arquivo do manifesto.
Depois de instalar o Snowflake Native App, o consumidor realiza o seguinte:
Visualiza as referências exigidas pelo Snowflake Native App.
Cria a referência chamando a função do sistema SYSTEM$REFERENCE.
Executa o procedimento armazenado de retorno de chamada passando o id da referência.
Depois que o consumidor executa o procedimento armazenado de retorno de chamada, o Snowflake Native App pode acessar o objeto solicitado.
Este fluxo de trabalho descreve o processo em que o consumidor cria a referência manualmente. Consulte Como criar uma interface de usuário para solicitar privilégios e referências para obter informações sobre como criar uma interface de usuário para permitir que os consumidores criem referências e concedam privilégios usando o Snowsight.
Tipos de objeto e privilégios que uma referência pode conter¶
A tabela a seguir lista os tipos de objeto que uma referência pode incluir e os privilégios permitidos para cada objeto:
Tipo de objeto |
Privilégios permitidos |
---|---|
TABLE |
SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES |
VIEW |
SELECT, REFERENCES |
EXTERNAL TABLE |
SELECT, REFERENCES |
FUNCTION |
USAGE |
PROCEDURE |
USAGE |
WAREHOUSE |
MODIFY, MONITOR, USAGE, OPERATE |
API INTEGRATION |
USAGE |
Definição de uma referência no arquivo de manifesto¶
O exemplo a seguir mostra como definir uma referência no arquivo manifest.yml
para uma tabela que existe fora do objeto APPLICATION:
references:
- my_table:
label: "My table"
description: "A table that exists outside the Snowflake Native App"
privileges:
- SELECT
object_type: TABLE
multi_valued: false
register_callback: config.register_reference
Este exemplo define uma referência chamada my_table
que requer o privilégio SELECT em uma tabela. A propriedade register_callback
especifica um procedimento armazenado usado para vincular o objeto ao Snowflake Native App.
Criação de um procedimento armazenado de retorno de chamada para uma referência¶
Depois de definir uma referência no arquivo manifest.yml
, um provedor deve adicionar um procedimento armazenado no script de configuração para registrar o retorno de chamada para a referência.
O exemplo a seguir mostra um procedimento armazenado usado para manipular um retorno de chamada para a referência mostrada em Definição de uma referência no arquivo de manifesto:
CREATE APPLICATION ROLE app_admin;
CREATE OR ALTER VERSIONED SCHEMA config;
GRANT USAGE ON SCHEMA config TO APPLICATION ROLE app_admin;
CREATE PROCEDURE CONFIG.REGISTER_SINGLE_CALLBACK(ref_name STRING, operation STRING, ref_or_alias STRING)
RETURNS STRING
LANGUAGE SQL
AS $$
BEGIN
CASE (operation)
WHEN 'ADD' THEN
SELECT SYSTEM$SET_REFERENCE(:ref_name, :ref_or_alias);
WHEN 'REMOVE' THEN
SELECT SYSTEM$REMOVE_REFERENCE(:ref_name);
WHEN 'CLEAR' THEN
SELECT SYSTEM$REMOVE_REFERENCE(ref_name);
ELSE
RETURN 'unknown operation: ' || operation;
END CASE;
RETURN NULL;
END;
$$;
GRANT USAGE ON PROCEDURE CONFIG.REGISTER_SINGLE_CALLBACK(STRING, STRING, STRING)
TO APPLICATION ROLE app_admin;
Este exemplo cria um procedimento armazenado chamado REGISTER_SINGLE_CALLBACK
que chama uma função do sistema para executar uma operação específica em uma referência que é passada como um argumento para o procedimento armazenado.
Visualização das referências definidas em um aplicativo¶
Quando um provedor define referências no arquivo manifest.yml
, eles são incluídos como parte do Snowflake Native App instalado.
Para visualizar as referências definidas para um Snowflake Native App, execute o comando SHOW REFERENCES como mostrado no exemplo a seguir:
SHOW REFERENCES IN APPLICATION hello_snowflake_app;
Vinculação de um objeto ao aplicativo¶
Depois de visualizar a definição de referência para um Snowflake Native App, o consumidor determina o identificador da referência executando a função do sistema SYSTEM$REFERENCE conforme mostrado no exemplo a seguir:
SELECT SYSTEM$REFERENCE('table', 'db1.schema1.tab1', 'persistent', 'select', 'insert');
Este comando retorna um identificador para a referência. O consumidor pode passar o identificador para o procedimento armazenado de retorno de chamada para a referência, conforme mostrado no exemplo a seguir:
CALL app.config.register_single_callback(
SYSTEM$REFERENCE('TABLE', 'db1.schema1.tab1', 'PERSISTENT', 'SELECT', 'INSERT'), 'ADD', null);
Depois que o consumidor executar o procedimento armazenado de retorno de chamada, o Snowflake Native App poderá acessar a tabela na conta do consumidor.
O procedimento armazenado de retorno de chamada na seção anterior chama a função do sistema SYSTEM$SET_REFERENCE conforme mostrado no exemplo a seguir:
SELECT SYSTEM$SET_REFERENCE(:ref_name, :ref_or_alias);
Consulte Funções de referência suportadas para outras funções do sistema relacionadas a referências.
Considerações ao usar referências¶
A Snowflake recomenda que você não modifique as definições de referência nas versões. Para atualizar uma definição de referência em uma nova versão, por exemplo, para alterar os privilégios para SELECT, INSERT de SELECT, você deve definir uma nova definição de referência com um nome diferente. O Snowflake Native App atualizado pode usar essa nova referência na nova versão do aplicativo.
Para incorporar uma referência em outro objeto, por exemplo, para atribuir uma referência a uma variável, a referência já deve estar vinculada a um objeto na conta do consumidor. Por exemplo, você não pode criar uma tarefa a menos que primeiro vincule a referência ao warehouse do consumidor.
As referências não funcionam em um objeto APPLICATION criado no modo de desenvolvimento usando arquivos em um estágio nomeado. As referências só funcionam em um objeto APPLICATION que tenha uma versão ou um Snowflake Native App em uma conta diferente instalado de uma listagem.
Exemplos de uso de referências inversas em um Snowflake Native App¶
As seções a seguir fornecem exemplos de uso de referências em contextos diferentes:
Execução de consultas usando uma referência¶
Os exemplos a seguir mostram como executar consultas usando referências:
SELECT * FROM reference('enrichment_table');
SELECT reference('encrypt_func')(t.c1) FROM my_table t;
Chamada de um procedimento armazenado usando uma referência¶
O exemplo a seguir mostra como chamar um procedimento armazenado usando uma referência:
CALL reference('consumer_proc')(11, 'hello world');
Execução de comandos DML usando uma referência¶
Os exemplos a seguir mostram como modificar dados em uma tabela usando referências:
INSERT INTO reference('data_export')(C1, C2)
SELECT T.C1, T.C2 FROM reference('other_table')
COPY INTO reference('the_table') ...
Execução do comando DESCRIBE usando uma referência¶
O exemplo a seguir mostra como executar a operação DESCRIBE usando uma referência:
DESCRIBE TABLE reference('the_table')
Como usar referências em uma tarefa¶
CREATE TASK app_task
WAREHOUSE = reference('consumer_warehouse')
...;
ALTER TASK app_task SET WAREHOUSE = reference('consumer_warehouse');
Como usar referências em uma definição de exibição¶
CREATE VIEW app_view
AS SELECT reference('function')(T.C1) FROM reference('table') AS T;
Como usar referências em um corpo de função¶
CREATE FUNCTION app.func(x INT)
RETURNS STRING
AS $$ select reference('consumer_func')(x) $$;
Como usar referências em uma função externa¶
CREATE EXTERNAL FUNCTION app.func(x INT)
RETURNS STRING
...
API_INTEGRATION = reference('app_integration');
Como usar referências em uma política¶
CREATE ROW ACCESS POLICY app_policy
AS (sales_region varchar) RETURNS BOOLEAN ->
'sales_executive_role' = reference('get_sales_team')
or exists (
select 1 from reference('sales_table')
where sales_manager = reference('get_sales_team')()
and region = sales_region
);
Funções de referência suportadas¶
O Snowflake Native App Framework oferece suporte às seguintes funções para executar diferentes operações relacionadas a referências.
Função do sistema |
Descrição |
---|---|
|
|
|
|
remove_reference |
|
|
|
|
|
|
|