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

Cette rubrique décrit comment les fournisseurs peuvent demander l’accès à des objets de base de données existants dans le compte consommateur.

À 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 Snowflake Native App peut avoir besoin d’accéder à des tables existantes dans une base de données de consommateurs.

Dans ce cas, il ne suffit pas que le consommateur accorde uniquement l’accès à un objet à l”Snowflake Native App. L”Snowflake Native App ne peut pas déterminer les noms du schéma et des objets qui existent dans le compte consommateur. Pour plus d’informations, reportez-vous à Résolution de nom d’objet.

Pour permettre à l”Snowflake Native App de se connecter à ce type d’objets, Snowflake Native App Framework fournit des références qui permettent au client de spécifier les noms des objets et d’accorder les privilèges requis.

Workflow pour la définition de références dans le compte consommateur

Pour demander un privilège au niveau de la référence et de l’objet, le fournisseur effectue les opérations suivantes lors du développement et de la publication d’une Snowflake Native App :

  1. Déterminez les objets qui nécessitent des références et les privilèges correspondants.

  2. Définissez les références dans le fichier manifeste.

  3. Ajoutez une procédure stockée dans le script d’installation pour gérer le rappel pour chaque référence définie dans le fichier manifeste.

Après avoir installé l”Snowflake Native App, le consommateur effectue les opérations suivantes :

  1. Voir les références requises par l”Snowflake Native App.

  2. Créez la référence en appelant la fonction système SYSTEM$REFERENCE.

  3. Exécutez la procédure stockée de rappel en transmettant l’identifiant de la référence.

Une fois que le consommateur a exécuté la procédure stockée de rappel, l”Snowflake Native App peut accéder à l’objet demandé.

Ce workflow décrit le processus au cours duquel le consommateur crée la référence manuellement. Reportez-vous à Création d’une interface utilisateur pour demander des privilèges et des références pour obtenir des informations sur la création d’une interface utilisateur permettant aux consommateurs de créer des références et d’accorder des privilèges à l’aide de Snowsight.

Types d’objets et privilèges qu’une référence peut contenir

Le tableau suivant répertorie les types d’objets qu’une référence peut inclure et les privilèges autorisés pour chaque objet :

Type d’objet

Privilèges autorisés

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

Définition d’une référence dans le fichier Manifest

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

Cet exemple définit une référence nommée my_table qui requiert le privilège SELECT sur une table. La propriété register_callback spécifie une procédure stockée utilisée pour lier l’objet à l”Snowflake Native App.

Création d’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éfinition d’une référence dans le fichier Manifest :

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

Cet exemple crée une procédure stockée nommée REGISTER_SINGLE_CALLBACK 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.

Vue des 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;
Copy

Liaison d’un objet à l’application

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

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

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_callback(
 SYSTEM$REFERENCE('TABLE', 'db1.schema1.tab1', 'PERSISTENT', 'SELECT', 'INSERT'), 'ADD', null);
Copy

Une fois que le consommateur a exécuté la procédure stockée de rappel, l”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);
Copy

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.

Les références ne fonctionnent pas dans un objet APPLICATION créé en mode développement et utilisant des fichiers en zone de préparation nommée. Les références ne fonctionnent que dans un objet APPLICATION dont une version ou une Snowflake Native App d’un compte différent a été installée à partir d’une annonce.

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.

Exécution de requêtes à l’aide d’une référence

Les exemples suivants montrent comment exécuter des requêtes à l’aide de références :

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

Appel d’une procédure stockée à l’aide d’une référence

L’exemple suivant montre comment appeler une procédure stockée à l’aide d’une référence :

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

Exécution des commandes DML à l’aide d’une référence

Les exemples suivants montrent comment modifier des données d’une table à l’aide de références :

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

Exécution de la commande DESCRIBE à l’aide d’une référence

L’exemple suivant montre comment exécuter l’opération DESCRIBE à l’aide d’une référence :

DESCRIBE TABLE reference('the_table')
Copy

Utilisation de références dans une tâche

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

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

Utilisation de références dans une définition de vue

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

Utilisation de références dans le corps d’une fonction

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

Utilisation de références dans une fonction externe

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

Utilisation de références dans une politique

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

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.

Fonction système

Description

set_reference

SYSTEM$SET_REFERENCE('<reference_name>', '<reference_string>')

  • Prise en charge uniquement pour une seule référence. Si une référence a déjà été créée avec le même nom, la référence existante est remplacée.

  • Renvoie un alias unique généré par le système pour la référence.

add_reference

SYSTEM$ADD_REFERENCE('<reference_name>', '<reference_string>')

  • Prend en charge les références à valeur unique ou à plusieurs valeurs. Pour les références à valeur unique, la fonction renvoie une erreur si une référence a déjà été créée avec la même valeur que celle spécifiée par <reference_name>.

  • Renvoie un alias unique généré par le système pour la référence.

remove_reference

SYSTEM$REMOVE_REFERENCE('<reference_name>'[, '<alias>'])

  • Prend en charge les références à valeur unique ou à plusieurs valeurs. Un <alias> est nécessaire pour supprimer les références à plusieurs valeurs.

  • Supprime une association avec une référence à plusieurs valeurs.

remove_all_references

SYSTEM$REMOVE_ALL_REFERENCES('<reference_name>')

  • Supprime toutes les associations à la référence.

get_all_references

SYSTEM$GET_ALL_REFERENCES('<reference_name>')

  • Renvoie un tableau d’alias d’entités générés par le système et associés à un nom de référence :

    • Liste vide si le nom de la référence n’est pas liée à une entité

    • Toutes les associations pour les références à valeurs multiples

    • Association 1 ou 0 pour les références à valeur unique

    • La valeur renvoyée ne contient pas le nom de l’objet du consommateur

  • Utilisé pour parcourir toutes les associations d’une référence à plusieurs valeurs dans une boucle.

get_referenced_object_id_hash

SYSTEM$GET_REFERENCED_OBJECT_ID_HASH('<reference_name>'[, '<alias>'])

  • Prend l’alias généré par le système pour une référence à plusieurs valeurs.

  • Renvoie le hachage de l’identifiant de l’entité de l’objet lié. Il s’agit de l’identificateur de l’entité résolue initialement lors de la création d’une référence.

  • Cette fonction permet à l”Snowflake Native App de déterminer si l’objet lié à une référence a été modifié. L”Snowflake Native App peut enregistrer la valeur, puis comparer la valeur actuelle à la valeur précédemment connue.