CREATE EXTERNAL ACCESS INTEGRATION¶

Syntaxe¶

CREATE [ OR REPLACE ] EXTERNAL ACCESS INTEGRATION <name>
  ALLOWED_NETWORK_RULES = ( <rule_name_1> [, <rule_name_2>, ... ] )
  [ ALLOWED_API_AUTHENTICATION_INTEGRATIONS = ( { <integration_name_1> [, <integration_name_2>, ... ] | none } ) ]
  [ ALLOWED_AUTHENTICATION_SECRETS = ( { <secret_name_1> [, <secret_name_2>, ... ] | all | none } ) ]
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]

Paramètres requis¶

name

Identificateur de l’intégration de l’accès externe.

La valeur de l’identificateur doit commencer par un caractère alphabétique et ne peut pas contenir d’espaces ou de caractères spéciaux à moins que toute la chaîne d’identificateur soit délimitée par des guillemets doubles (p. ex. "My object"). Les identificateurs entre guillemets doubles sont sensibles à la casse.

Pour plus de détails, voir Exigences relatives à l’identificateur.

ALLOWED_NETWORK_RULES = (rule_name [ , rule_name ... ])

Spécifie les règles de réseau autorisées. Seules les règles de sortie peuvent être spécifiées.

ENABLED = { TRUE | FALSE }

Spécifie si cette intégration est activée ou désactivée. Si l’intégration est désactivée, tout code de gestionnaire qui s’appuie sur elle sera incapable d’atteindre l’emplacement réseau externe.

La valeur est insensible à la casse.

La valeur par défaut est TRUE.

Paramètres facultatifs¶

ALLOWED_API_AUTHENTICATION_INTEGRATIONS = ( integration_name_1 [, integration_name_2, ... ] | none )

Spécifie les intégrations de sécurité dont le serveur d’autorisation OAuth a délivré le secret utilisé par l’UDF ou la procédure. L’intégration de sécurité doit être le type utilisé pour l’intégration d’API externe.

La valeur de ce paramètre doit être l’une des suivantes :

• Un ou plusieurs noms d’intégration de sécurité Snowflake pour autoriser l’une des intégrations de la liste.

• none pour n’autoriser aucune intégration.

Les intégrations de sécurité spécifiées par ce paramètre – ainsi que les secrets spécifiés par le paramètre ALLOWED_AUTHENTICATION_SECRETS – sont des moyens d’autoriser l’utilisation de secrets dans une UDF ou une procédure qui utilise cette intégration d’accès externe. Pour plus d’informations, voir Notes sur l’utilisation.

Pour plus d’informations de référence sur les intégrations de sécurité, reportez-vous à CREATE SECURITY INTEGRATION (authentification API externe).

ALLOWED_AUTHENTICATION_SECRETS = ( secret_name [, secret_name ... ] | all | none )

Spécifie les secrets que l’UDF ou le code de gestionnaire de procédure peut utiliser lors de l’accès aux emplacements réseau externes référencés dans les règles de réseau autorisées.

La valeur de ce paramètre doit être l’une des suivantes :

• Un ou plusieurs noms de secret Snowflake pour autoriser n’importe lequel des secrets de la liste.

• all pour autoriser tout secret.

• none pour n’autoriser aucun secret.

Le paramètre ALLOWED_API_AUTHENTICATION_INTEGRATIONS peut également spécifier des secrets autorisés. Pour plus d’informations, voir Notes sur l’utilisation.

Pour des informations de référence sur les secrets, voir CREATE SECRET.

COMMENT = 'string_literal'

Spécifie un commentaire pour l’intégration de l’accès externe.

Par défaut : aucune valeur

Exigences en matière de contrôle d’accès¶

Un rôle utilisé pour exécuter cette opération doit au minimum disposer des privilèges suivants :

Pour obtenir des instructions sur la création d’un rôle personnalisé avec un ensemble spécifique de privilèges, voir Création de rôles personnalisés.

Pour des informations générales sur les rôles et les privilèges accordés pour effectuer des actions SQL sur des objets sécurisables, voir Aperçu du contrôle d’accès.

Notes sur l’utilisation¶

• Vous pouvez autoriser l’utilisation de secrets par une UDF ou une procédure en utilisant deux paramètres d’intégration d’accès externe, comme décrit ci-dessous.

  • Avec le paramètre ALLOWED_AUTHENTICATION_SECRETS. Vous pouvez spécifier des secrets comme valeurs de paramètre ou définir la valeur du paramètre sur all, ce qui permet au code de gestionnaire (handler) d’utiliser n’importe quel secret.

  • Avec le paramètre ALLOWED_API_AUTHENTICATION_INTEGRATIONS. L’utilisation d’un secret est autorisée lorsque le secret lui-même spécifie une intégration de sécurité dont le nom est également spécifié par ce paramètre. Le secret spécifie l’intégration de sécurité avec son paramètre API_AUTHENTICATION. En d’autres termes, lorsque le secret et l’intégration d’accès externe spécifient tous les deux l’intégration de sécurité, l’utilisation du secret est autorisée dans les fonctions et procédures qui spécifient l’intégration d’accès externe.

  Notez que ces deux alternatives fonctionnent indépendamment l’une de l’autre. Un secret est autorisé si l’un des paramètres (ou les deux) l’autorise, quelle que soit la valeur spécifiée pour l’autre paramètre. Par exemple, le fait de définir l’un des paramètres sur none n’empêche pas l’utilisation d’un secret spécifié par l’autre paramètre dans le code de gestionnaire (handler).

• Bien que vous puissiez spécifier des règles réseau à l’aide d’un nom d’hôte, Snowflake applique les règles au niveau IP de granularité. Snowflake n’inspectera pas le trafic de votre application, il est donc de votre responsabilité de vous assurer que l’hôte de l’emplacement externe dispose du service authentique et qu’il n’est pas possible de se connecter à d’autres services sur le même hôte. Dans la mesure du possible, vous devez utiliser des protocoles sécurisés tels que HTTPS et TLS lors de la communication avec des points de terminaison Internet.

• Concernant les métadonnées :

  Attention

  Les clients doivent s’assurer qu’aucune donnée personnelle (autre que pour un objet utilisateur), donnée sensible, donnée à exportation contrôlée ou autre donnée réglementée n’est saisie comme métadonnée lors de l’utilisation du service Snowflake. Pour plus d’informations, voir Champs de métadonnées dans Snowflake.

Exemples¶

Créez une intégration d’accès externe qui donne accès à l’API de traduction Google.

Pour un exemple plus complet, reportez-vous à Création et utilisation d’une intégration d’accès externe.

1. Créez un secret représentant les identifiants de connexion.

   Pour créer un secret, vous devez vous être vu attribuer un rôle avec le privilège CREATE SECRET sur le schéma actuel. Pour les autres types de secret pris en charge par cette commande, reportez-vous à CREATE SECRET. Dans cet exemple, google_translate_oauth fait référence à une intégration de sécurité. Pour plus d’informations, reportez-vous à CREATE SECURITY INTEGRATION (authentification API externe).

   CREATE OR REPLACE SECRET oauth_token
     TYPE = OAUTH2
     API_AUTHENTICATION = google_translate_oauth
     OAUTH_REFRESH_TOKEN = 'my-refresh-token';
   

   Copy

2. Accordez au rôle developer les privilèges READ sur le secret afin que les développeurs d’UDF puissent l’utiliser.

   Créez le rôle qui sera requis pour les développeurs ayant besoin d’utiliser le secret.

   USE ROLE USERADMIN;
   CREATE OR REPLACE ROLE developer;
   

   Copy

   Accordez le privilège READ au rôle developer.

   USE ROLE SECURITYADMIN;
   GRANT READ ON SECRET oauth_token TO ROLE developer;
   

   Copy

3. Créez une règle de réseau représentant l’emplacement réseau externe. Utilisez un rôle doté des privilèges décrits dans CREATE NETWORK RULE.

   USE ROLE SYSADMIN;
   CREATE OR REPLACE NETWORK RULE google_apis_network_rule
     MODE = EGRESS
     TYPE = HOST_PORT
     VALUE_LIST = ('translation.googleapis.com');
   

   Copy

4. Créez une intégration d’accès externe à l’aide du secret et de la règle de réseau.

   USE ROLE ACCOUNTADMIN;
   CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION google_apis_access_integration
     ALLOWED_NETWORK_RULES = (google_apis_network_rule)
     ALLOWED_AUTHENTICATION_SECRETS = (oauth_token)
     ENABLED = true;
   

   Copy

5. Accordez au rôle developer les privilèges USAGE sur le l’intégration afin que les développeurs d’UDF puissent l’utiliser.

   GRANT USAGE ON INTEGRATION google_apis_access_integration TO ROLE developer;
   

   Copy

6. Créez une UDF google_translate_python qui traduit le texte spécifié en une phrase dans la langue spécifiée. Pour plus d’informations, reportez-vous à Utilisation de l’intégration de l’accès externe dans une fonction ou une procédure.

   USE ROLE developer;
   
   CREATE OR REPLACE FUNCTION google_translate_python(sentence STRING, language STRING)
   RETURNS STRING
   LANGUAGE PYTHON
   RUNTIME_VERSION = 3.10
   HANDLER = 'get_translation'
   EXTERNAL_ACCESS_INTEGRATIONS = (google_apis_access_integration)
   PACKAGES = ('snowflake-snowpark-python','requests')
   SECRETS = ('cred' = oauth_token )
   AS
   $$
   import _snowflake
   import requests
   import json
   session = requests.Session()
   def get_translation(sentence, language):
     token = _snowflake.get_oauth_access_token('cred')
     url = "https://translation.googleapis.com/language/translate/v2"
     data = {'q': sentence,'target': language}
     response = session.post(url, json = data, headers = {"Authorization": "Bearer " + token})
     return response.json()['data']['translations'][0]['translatedText']
   $$;
   

   Copy

7. Accordez le privilège USAGE sur la fonction google_translate_python afin que les personnes titulaires du rôle d’utilisateur puissent l’appeler.

   GRANT USAGE ON FUNCTION google_translate_python(string, string) TO ROLE user;
   

   Copy

8. Exécutez la fonction google_translate_python pour traduire une phrase.

   USE ROLE user;
   SELECT google_translate_python('Happy Thursday!', 'zh-CN');
   

   Copy

   Cette opération génère la sortie suivante.

   -------------------------------------------------------
   | GOOGLE_TRANSLATE_PYTHON('HAPPY THURSDAY!', 'ZH-CN') |
   -------------------------------------------------------
   | 快乐星期四！                                          |
   -------------------------------------------------------