Solicitação de referências e privilégios de nível de objeto de consumidores¶

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.

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:

SELECT * FROM reference('enrichment_table');

SELECT reference('encrypt_func')(t.c1) FROM my_table t;

CALL reference('consumer_proc')(11, 'hello world');

INSERT INTO reference('data_export')(C1, C2)
  SELECT T.C1, T.C2 FROM reference('other_table')

COPY INTO reference('the_table') ...

DESCRIBE TABLE reference('the_table')

CREATE TASK app_task
  WAREHOUSE = reference('consumer_warehouse')
  ...;

ALTER TASK app_task SET WAREHOUSE = reference('consumer_warehouse');

CREATE VIEW app_view
  AS SELECT reference('function')(T.C1) FROM reference('table') AS T;

CREATE FUNCTION app.func(x INT)
  RETURNS STRING
  AS $$ select reference('consumer_func')(x) $$;

CREATE EXTERNAL FUNCTION app.func(x INT)
  RETURNS STRING
  ...
  API_INTEGRATION = reference('app_integration');

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.