Demander des références et des privilèges au niveau de l’objet des consommateurs¶

À propos des références¶

Dans certains contextes, une Snowflake Native App installée doit accéder à des objets existants dans le compte consommateur qui existent en dehors de l’objet APPLICATION. Par exemple, une application peut avoir besoin d’accéder à des tables existantes dans une base de données de consommateurs.

Dans ce contexte, il ne suffit pas que le consommateur accorde l’accès à un objet à l’objet APPLICATION, car l’application ne peut pas déterminer le nom du schéma et de l’objet dans le compte du consommateur.

Pour permettre à la Snowflake Native App d’accéder à des objets existants en dehors de l’objet APPLICATION, le Snowflake Native App Framework fournit des références qui permettent au client de spécifier le nom et le schéma d’un objet et d’activer l’accès à l’objet.

Définir une référence dans le fichier manifeste¶

L’exemple suivant montre comment définir une référence dans le fichier manifest.yml pour une table dans le compte de consommateur qui existe en dehors de l’objet 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

Cet exemple définit une référence nommée consumer_table qui requiert les privilèges INSERT et SELECT sur une table du compte de consommateur. La propriété register_callback spécifie une procédure stockée utilisée pour lier une table de consommateurs à cette définition de référence.

Utilisez multi_valued pour lier plusieurs objets consommateurs à la même référence. Lorsque cette propriété est spécifiée, les mêmes opérations sont effectuées sur les objets avec une seule référence de valeur. La propriété peut également être utilisée avec des objets avec des références à valeurs multiples. Voir Fonctions de référence prises en charge pour en savoir plus sur les opérations de référence de Snowflake Native App Framework.

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

Créer une procédure stockée de rappel pour une référence¶

Après avoir défini une référence dans le fichier manifest.yml, un fournisseur doit ajouter une procédure stockée dans le script d’installation pour enregistrer le rappel de la référence.

L’exemple suivant montre une procédure stockée utilisée pour gérer un rappel pour que la référence apparaisse dans Définir une référence dans le fichier manifeste :

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;

Cet exemple crée une procédure stockée nommée REGISTER_SINGLE_REFERENCE qui appelle une fonction système pour effectuer une opération spécifique sur une référence transmise en tant qu’argument à la procédure stockée.

Créer une procédure stockée de rappel pour demander la configuration d’un objet¶

Pour certains types d’objets, un fournisseur doit ajouter une procédure stockée au script d’installation afin de fournir une configuration supplémentaire. Ce rappel est utilisé lorsque les consommateurs autorisent les références à l’aide de Snowsight.

L’exemple suivant montre comment définir une procédure stockée de rappel de configuration pour la référence indiquée dans Définir une référence dans le fichier manifeste :

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;

Cet exemple crée une procédure stockée nommée GET_CONFIGURATION_FOR_REFERENCE qui renvoie une configuration formatée JSON utilisée pour construire une référence de type EXTERNAL ACCESS INTEGRATION ou SECRET. Les entrées de l’instruction de commutation doivent mapper les noms de référence dans le fichier manifest.yml.

Afficher les références définies dans une application¶

Lorsqu’un fournisseur définit des références dans le fichier manifest.yml, celles-ci sont incluses dans l”Snowflake Native App installée.

Pour voir les références définies pour une Snowflake Native App, exécutez la commande SHOW REFERENCES comme indiqué dans l’exemple suivant :

SHOW REFERENCES IN APPLICATION hello_snowflake_app;

Lier un objet à l’application¶

Après avoir consulté la définition de la référence pour une Snowflake Native App, le consommateur crée une référence en exécutant la fonction système SYSTEM$REFERENCE, comme le montre l’exemple suivant :

SELECT SYSTEM$REFERENCE('table', 'db1.schema1.table1', 'persistent', 'select', 'insert');

Cette commande renvoie un identificateur pour la référence. Le consommateur peut transmettre l’identificateur à la procédure stockée de rappel pour la référence, comme le montre l’exemple suivant :

CALL app.config.register_single_reference(
  'consumer_table' , 'ADD', SYSTEM$REFERENCE('TABLE', 'db1.schema1.table1', 'PERSISTENT', 'SELECT', 'INSERT'));

Dans cet exemple, consumer_table est le nom de la référence définie dans le fichier manifest.yml. Une fois que le consommateur a exécuté la procédure stockée qui associe la référence, la Snowflake Native App peut accéder à la table dans le compte consommateur.

La procédure stockée de rappel de la section précédente appelle la fonction système SYSTEM$SET_REFERENCE comme le montre l’exemple suivant :

SELECT SYSTEM$SET_REFERENCE(:ref_name, :ref_or_alias);

Reportez-vous à Fonctions de référence prises en charge pour connaître les autres fonctions système liées aux références.

Points à prendre en considération lors de l’utilisation de références¶

Snowflake vous recommande de ne pas modifier les définitions de référence d’une version à l’autre. Pour mettre à jour une définition de référence vers une nouvelle version, par exemple pour remplacer les privilèges de SELECT, INSERT de SELECT, vous devez définir une nouvelle définition de référence avec un nom différent. L”Snowflake Native App mise à jour peut utiliser cette nouvelle référence dans la nouvelle version de l’application.

Pour intégrer une référence dans un autre objet, par exemple pour affecter une référence à une variable, la référence doit déjà être liée à un objet dans le compte consommateur. Par exemple, vous ne pouvez pas créer une tâche si vous ne liez pas d’abord la référence à l’entrepôt du consommateur.

Exemple d’utilisation de références dans une Snowflake Native App¶

Les sections suivantes fournissent des exemples d’utilisation de références dans différents contextes.

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

Format JSON de la réponse du rappel de configuration¶

La fonction de rappel de configuration renvoie une réponse au format JSON. Le format JSON renvoyé est différent pour l’intégration de l’accès externe et les références de secrets.

{
  "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 ..."
  }
}

Fonctions de référence prises en charge¶

Le Snowflake Native App Framework prend en charge les fonctions suivantes pour effectuer différentes opérations liées aux références.