Création et utilisation d’une intégration d’accès externe¶

Création d’une règle de réseau pour représenter l’emplacement réseau externe¶

Vous pouvez utiliser la commande CREATE NETWORK RULE pour créer une règle de réseau qui représente l’emplacement réseau externe et les restrictions d’accès. Par exemple, une règle de réseau spécifie des identificateurs de réseau tels qu’un nom d’hôte et la direction de la communication avec le réseau (entrée ou sortie).

Pour prendre en charge l’accès à un réseau externe, un administrateur inclura la règle lors de la création d’une intégration d’accès externe. Chaque règle incluse dans l’intégration spécifie un emplacement réseau externe auquel la fonction ou la procédure est autorisée à accéder.

Lors de la création d’une règle de réseau à utiliser dans le cadre d’une intégration d’accès externe, vous devez spécifier les éléments suivants :

• EGRESS comme valeur du paramètre MODE.

• HOST_PORT comme valeur du paramètre TYPE.

• Le point de terminaison de l’emplacement externe dans le paramètre VALUE_LIST.

• (Facultatif) Un numéro de port avec le nom du point de terminaison de l’emplacement externe. Si vous omettez un numéro de port, Snowflake utilisera le numéro de port par défaut pour l’accès externe, 443.

  Par exemple, si le point de terminaison requiert le port 80, le paramètre VALUE_LIST peut être le suivant :

  VALUE_LIST = ('example.com:80')
  

  Copy

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

Création d’un secret pour représenter les identifiants de connexion¶

Vous pouvez utiliser CREATE SECRET pour créer un secret qui représente les identifiants de connexion requis pour s’authentifier auprès de l’emplacement réseau externe. Par exemple, le secret peut contenir des identifiants de connexion tels qu’un nom d’utilisateur et un mot de passe.

Pour l’accès à un réseau externe qui prend en charge OAuth, la meilleure pratique consiste à faire en sorte que votre secret contienne une référence à une intégration de sécurité qui contient les valeurs nécessaires au flux OAuth, telles qu’un ID client, un secret client, un point de terminaison de jeton, etc.

Le secret sera utilisé de la manière suivante :

• Par un administrateur lors de la création de l’intégration de l’accès externe.

  Lors de la création de l’intégration, l’administrateur spécifie les secrets que les développeurs peuvent utiliser dans le code du gestionnaire lorsqu’ils créent une fonction ou une procédure qui utilise l’intégration.

• Par un développeur lors de la création d’une UDF ou d’un gestionnaire de procédure.

  Le développeur spécifiera le secret autorisé qui contient les identifiants de connexion que le code du gestionnaire peut utiliser pour s’authentifier lors d’une requête envoyée à l’emplacement externe. Lors de l’écriture d’un gestionnaire, un développeur peut utiliser une API Snowflake pour récupérer les identifiants de connexion contenus dans le secret plutôt que d’inclure les identifiants de connexion en tant que valeurs littérales dans le code du gestionnaire.

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

CREATE OR REPLACE SECRET bp_maps_api
  TYPE = GENERIC_STRING
  SECRET_STRING = 'replace-with-your-api-key';

Création d’une intégration d’accès externe¶

Vous pouvez utiliser la commande CREATE EXTERNAL ACCESS INTEGRATION pour créer une intégration d’accès externe qui regroupe les règles de réseau autorisées (représentant les emplacements de réseau externes) et les secrets autorisés (représentant les identifiants de connexion pour l’authentification) à utiliser avec des UDFs et des procédures.

En particulier, l’intégration de l’accès externe spécifie les règles de réseau et les secrets que les UDFs et les procédures faisant référence à l’intégration peuvent utiliser.

L’intégration de l’accès externe sera utilisée par un administrateur pour gérer l’accès aux emplacements réseau externes à partir d’UDFs et de procédures. L’intégration ne spécifie que les emplacements et les identifiants de connexion dont l’utilisation est autorisée par des UDFs et des procédures qui font référence à l’intégration. Un administrateur peut également activer ou désactiver l’intégration pour gérer l’accès à des emplacements externes.

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

Utilisation de l’intégration de l’accès externe dans une fonction ou une procédure¶

Lorsque vous utilisez la commande CREATE FUNCTION ou CREATE PROCEDURE pour créer une UDF ou une procédure, vous pouvez activer l’accès à des emplacements de réseau externes de la manière suivante :

• Inclure le paramètre EXTERNAL_ACCESS_INTEGRATIONS, en fixant sa valeur à une ou plusieurs intégrations.

  Chaque intégration spécifiée autorise l’accès aux emplacements de réseau externes et aux secrets spécifiés par l’intégration.

• Incluez le paramètre SECRETS, en lui attribuant une valeur correspondant à un ou plusieurs secrets et aux noms que vous utiliserez pour y accéder à partir du code du gestionnaire.

  Les secrets que vous spécifiez comme valeurs doivent également être spécifiés dans l’intégration de l’accès externe.

• Dans le code du gestionnaire, accédez au secret pour récupérer les identifiants de connexion permettant de s’authentifier auprès de l’emplacement réseau externe.

Snowflake limite le nombre total de connexions qui peuvent être établies à partir d’une UDF spécifique. Pour éviter les problèmes d’épuisement des ressources, réutilisez les connexions autant que possible. Vous pouvez y parvenir en créant le client ou la session TCP une fois pendant l’initialisation de l’UDF, puis en l’utilisant dans le gestionnaire d’UDF pour le reste de la requête.

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']
$$;