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 aplicativo pode precisar acessar tabelas existentes em um banco de dados do consumidor.

Neste contexto, não é suficiente que o consumidor conceda acesso a um objeto ao objeto APPLICATION porque o aplicativo não pode determinar o nome do esquema e do objeto na conta do consumidor.

Para permitir que o Snowflake Native App acesse objetos existentes fora do objeto APPLICATION, o Snowflake Native App Framework fornece referências que permitem ao cliente especificar o nome e o esquema de um objeto e permitir o acesso ao objeto.

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 na conta do consumidor que existe fora do objeto APPLICATION:

references:
- consumer_table:
  label: "Consumer table"
  description: "A table in the consumer account that exists outside the APPLICATION object."
  privileges:
  - INSERT
  - SELECT
  object_type: TABLE
  multi_valued: false
  register_callback: config.register_single_reference

Este exemplo define uma referência chamada consumer_table que requer os privilégios INSERT e SELECT em uma tabela na conta do consumidor. A propriedade register_callback especifica um procedimento armazenado usado para vincular uma tabela do consumidor a esta definição de referência.

Reference definition '<REF_DEF_NAME>' cannot be found in the current version of the application '<APP_NAME>'

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_REFERENCE(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_REFERENCE(STRING, STRING, STRING)
  TO APPLICATION ROLE app_admin;

Este exemplo cria um procedimento armazenado chamado REGISTER_SINGLE_REFERENCE 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 cria uma referência executando a função do sistema SYSTEM$REFERENCE conforme mostrado no exemplo a seguir:

SELECT SYSTEM$REFERENCE('table', 'db1.schema1.table1', '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_reference(
  'consumer_table' , 'ADD', SYSTEM$REFERENCE('TABLE', 'db1.schema1.table1', 'PERSISTENT', 'SELECT', 'INSERT'));

Neste exemplo, consumer_table é o nome da referência definida no arquivo manifest.yml. Depois que o consumidor executa o procedimento armazenado que associa a referência, o Snowflake Native App pode 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('consumer_table');

SELECT reference('encrypt_func')(t.c1) FROM consumer_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.