Demande des références et de 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 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.

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

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;

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;

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

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

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

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.

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

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.