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>, ... ] ) ]
  [ ALLOWED_AUTHENTICATION_SECRETS = ( <secret_name_1> [, <secret_name_2>, ... ] ) ]
  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.

Pour des informations de référence sur les règles de réseau, reportez-vous à CREATE NETWORK RULE.

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, ... ] )

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 la sécurité doit être du type utilisé pour l’intégration d’API externe.

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 ... ])

Spécifie les secrets qu’une UDF ou qu’une procédure peut utiliser lorsqu’elle se réfère à cette intégration.

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 commande SQL doit avoir les privilèges suivants définis au minimum ainsi :

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¶

• 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.8
   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') |
   -------------------------------------------------------
   | 快乐星期四！                                          |
   -------------------------------------------------------