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 :
Déterminez les objets qui nécessitent des références et les privilèges correspondants.
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 :
Voir les références requises par l”Snowflake Native App.
Créez la référence en appelant la fonction système SYSTEM$REFERENCE.
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
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.
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');
SELECT reference('encrypt_func')(t.c1) FROM my_table t;
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');
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 INTO reference('the_table') ...
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')
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');
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;
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) $$;
Utilisation de références dans une fonction externe¶
CREATE EXTERNAL FUNCTION app.func(x INT)
RETURNS STRING
...
API_INTEGRATION = reference('app_integration');
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
);
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 |
---|---|
|
|
|
|
remove_reference |
|
|
|
|
|
|
|