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.

Use multi_valued para vincular vários objetos de consumidor à mesma referência. Quando essa propriedade é especificada, as mesmas operações são executadas em objetos com uma única referência de valor. A propriedade também pode ser usada com objetos com referências de vários valores. Consulte Funções de referência compatíveis para saber mais sobre operações de referência do Snowflake Native App Framework.

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, :ref_or_alias);
        WHEN 'CLEAR' THEN
          SELECT SYSTEM$REMOVE_ALL_REFERENCES(: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.

Criação de um procedimento armazenado de retorno de chamada para solicitar a configuração do objeto¶

Para alguns tipos de objeto, um provedor deve adicionar um procedimento armazenado ao script de configuração para fornecer configuração adicional. Este retorno de chamada é usado quando os consumidores permitem referências usando Snowsight.

O exemplo a seguir mostra como definir um procedimento armazenado de retorno de chamada de configuração para a referência mostrada em Definição de uma referência no arquivo de manifesto:

CREATE OR REPLACE CONFIG.GET_CONFIGURATION_FOR_REFERENCE(ref_name STRING)
  RETURNS STRING
  LANGUAGE SQL
  AS
  $$
  BEGIN
    CASE (ref_name)
      WHEN 'CONSUMER_EXTERNAL_ACCESS' THEN
        RETURN '{
          "type": "CONFIGURATION",
          "payload":{
            "host_ports":["google.com"],
            "allowed_secrets" : "LIST",
            "secret_references":["CONSUMER_SECRET"]}}';
      WHEN 'CONSUMER_SECRET' THEN
        RETURN '{
          "type": "CONFIGURATION",
          "payload":{
            "type" : "OAUTH2",
            "security_integration": {
              "oauth_scopes": ["https://www.googleapis.com/auth/analytics.readonly"],
              "oauth_token_endpoint": "https://oauth2.googleapis.com/token",
              "oauth_authorization_endpoint":
                "https://accounts.google.com/o/oauth2/auth"}}}';
     END CASE;
     RETURN '';
   END;
   $$;

GRANT USAGE ON PROCEDURE CONFIG.GET_CONFIGURATION_FOR_REFERENCE(STRING)
  TO APPLICATION ROLE app_admin;

Este exemplo cria um procedimento armazenado denominado GET_CONFIGURATION_FOR_REFERENCE que retorna uma configuração com formação de JSON que é usada para construir uma referência do tipo EXTERNAL ACCESS INTEGRATION ou SECRET. As entradas na instrução de mudança devem mapear os nomes de referência no arquivo manifest.yml.

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.

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 FUNCTION app.func(x INT)
  RETURNS STRING
  ...
  EXTERNAL_ACCESS_INTEGRATIONS = (reference('consumer_external_access_integration'), ...);
  SECRETS = ('cred1' = reference('consumer_secret'), ...);

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
      );

Formato JSON para a resposta de retorno de chamada de configuração¶

A função de retorno de chamada de configuração retorna uma resposta em formato JSON. O formato JSON retornado é diferente para integração de acesso externo e referências secretas.

{
  "type": "CONFIGURATION",
  "payload": {
    "host_ports": ["host_port_1", ...],
    "allowed_secrets": "NONE|ALL|LIST",
    "secret_references": ["ref_name_1", ...]
  }
}

{
  "type": "CONFIGURATION",
    "payload": {
            "type": "OAUTH2",
            "security_integration": {
                    "oauth_scopes": ["scope_1", "scope_2"],
                    "oauth_token_endpoint" : "token_endpoint",
                    "oauth_authorization_endpoint" : "auth_endpoint"
            }
    }
}

 {
   "type": "ERROR",
   "payload":{
     "message": "The reference is not available for configuration ..."
  }
}

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.