CREATE EXTERNAL ACCESS INTEGRATION¶

Syntax¶

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

Erforderliche Parameter¶

name

Bezeichner der Integration für den externen Zugriff.

Der Bezeichnerwert muss mit einem alphabetischen Zeichen beginnen und darf keine Leer- oder Sonderzeichen enthalten, es sei denn, die gesamte Bezeichnerzeichenfolge wird in doppelte Anführungszeichen gesetzt (z. B. "My object"). Bei Bezeichnern, die in doppelte Anführungszeichen eingeschlossen sind, ist die Groß-/Kleinschreibung zu beachten.

Weitere Details dazu finden Sie unter Anforderungen an Bezeichner.

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

Gibt die zulässigen Netzwerkregeln an. Es können nur Ausgangsregeln angegeben werden.

ENABLED = { TRUE | FALSE }

Gibt an, ob diese Integration aktiviert oder deaktiviert ist. Wenn die Integration deaktiviert ist, kann jeder Handler-Code, der darauf angewiesen ist, den externen Netzwerkstandort nicht erreichen.

Der Wert unterscheidet nicht zwischen Groß- und Kleinschreibung.

Die Voreinstellung ist TRUE.

Optionale Parameter¶

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

Gibt die Sicherheitsintegrationen an, deren OAuth-Autorisierungsserver das von der UDF oder Prozedur verwendete Geheimnis ausgegeben hat. Die Sicherheitsintegration muss der Typ sein, der für die externe API-Integration verwendet wird.

Der Parameter muss einen der folgenden Werte haben:

• Einen oder mehrere Namen von Snowflake-Sicherheitsintegrationen, um eine der aufgeführten Integrationen zuzulassen.

• none, um keine Integrationen zuzulassen.

Sicherheitsintegrationen, die durch diesen Parameter angegeben werden – sowie Geheimnisse, die durch den Parameter ALLOWED_AUTHENTICATION_SECRETS angegeben werden – sind Möglichkeiten, um Geheimnisse für die Verwendung in einer UDF oder Prozedur zuzulassen, die diese Integration für den externen Zugriff verwendet. Weitere Informationen dazu finden Sie unter Nutzungshinweise.

Weitere Informationen zu Sicherheitsintegrationen finden Sie unter CREATE SECURITY INTEGRATION (Externe API-Authentifizierung).

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

Gibt die Geheimnisse an, die UDF- oder Prozedur-Handler-Code beim Zugriff auf die externen Netzwerkstandorte verwenden kann, auf die in den Regeln für zulässige Netzwerke verwiesen wird.

Der Parameter muss einen der folgenden Werte haben:

• Ein oder mehrere Namen von Snowflake-Geheimnissen, um eines der aufgeführten Geheimnisse zuzulassen.

• all um jedes Geheimnis zuzulassen.

• none um keine Geheimnisse zuzulassen.

Der Parameter ALLOWED_API_AUTHENTICATION_INTEGRATIONS kann auch zulässige Geheimnisse angeben. Weitere Informationen dazu finden Sie unter Nutzungshinweise.

Weitere Informationen zu Geheimnissen finden Sie unter CREATE SECRET.

COMMENT = 'string_literal'

Gibt einen Kommentar für die Integration des externen Zugangs an.

Standard: Kein Wert

Anforderungen an die Zugriffssteuerung¶

Eine Rolle, die zur Ausführung dieses SQL-Befehls verwendet wird, muss mindestens die folgenden Berechtigungen haben:

Eine Anleitung zum Erstellen einer kundenspezifischen Rolle mit einer bestimmten Gruppe von Berechtigungen finden Sie unter Erstellen von kundenspezifischen Rollen.

Allgemeine Informationen zu Rollen und Berechtigungen zur Durchführung von SQL-Aktionen auf sicherungsfähigen Objekten finden Sie unter Übersicht zur Zugriffssteuerung.

Nutzungshinweise¶

• Sie können Geheimnisse für die Verwendung durch eine UDF oder Prozedur zulassen, indem Sie zwei Parameter für die Integration für den externen Zugriff verwenden, wie unten beschrieben.

  • Mit dem Parameter ALLOWED_AUTHENTICATION_SECRETS. Sie können Geheimnisse als Parameterwerte angeben oder den Wert des Parameters auf all setzen, sodass der Handler-Code jedes Geheimnis verwenden darf.

  • Mit dem Parameter ALLOWED_API_AUTHENTICATION_INTEGRATIONS. Ein Geheimnis kann verwendet werden, wenn das Geheimnis selbst eine Sicherheitsintegration angibt, deren Name ebenfalls durch diesen Parameter angegeben wird. Das Geheimnis spezifiziert die Sicherheitsintegration mit seinem Parameter API_AUTHENTICATION. Mit anderen Worten: Wenn sowohl das Geheimnis als auch die Integration des externen Zugriffs die Sicherheitsintegration spezifizieren, ist das Verwenden des Geheimnisses in Funktionen und Prozeduren zulässig, die die Integration des externen Zugriffs spezifizieren.

  Beachten Sie, dass diese beiden Alternativen unabhängig voneinander funktionieren. Ein Geheimnis ist zulässig, wenn einer der Parameter (oder beide) es zulassen, unabhängig von dem Wert, der für den anderen Parameter angegeben wurde. Wenn Sie zum Beispiel einen der Parameter auf none setzen, verhindert dies nicht, dass ein durch den anderen Parameter angegebenes Geheimnis im Handler-Code verwendet wird.

• Sie können Netzwerkregeln zwar mithilfe eines Hostnamens angeben, Snowflake setzt die Regeln jedoch auf der IP-Ebene durch. Snowflake überprüft den Datenverkehr Ihrer Anwendung nicht. Es liegt also in Ihrer Verantwortung, sicherzustellen, dass der Host des externen Speicherorts über den authentifizierten Dienst verfügt und dass keine Verbindung zu anderen Diensten auf demselben Host möglich ist. Wann immer möglich, sollten Sie sichere Protokolle wie HTTPS und TLS verwenden, wenn Sie mit Internet-Endpunken kommunizieren.

• Metadaten:

  Achtung

  Kunden müssen sicherstellen, dass bei der Nutzung des Snowflake-Dienstes keine personenbezogenen Daten (außer für ein Objekt „Benutzer“), sensible Daten, exportkontrollierte Daten oder andere regulierte Daten als Metadaten eingegeben werden. Weitere Informationen dazu finden Sie unter Metadatenfelder in Snowflake.

Beispiele¶

Erstellen Sie eine Integration für den externen Zugriff, die Zugriff auf die API Google Translation ermöglicht.

Ein ausführlicheres Beispiel finden Sie unter Erstellen und Verwenden einer Integration für den externen Zugriff.

1. Erstellen Sie ein Geheimnis für die Anmeldeinformationen.

   Um ein Geheimnis zu erstellen, muss Ihnen eine Rolle mit der Berechtigung CREATE SECRET für das aktuelle Schema zugewiesen worden sein. Für andere Arten von Geheimnissen, die von diesem Befehl unterstützt werden, siehe CREATE SECRET. In diesem Beispiel bezieht sich google_translate_oauth auf eine Sicherheitsintegration. Weitere Informationen dazu finden Sie unter CREATE SECURITY INTEGRATION (Externe API-Authentifizierung).

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

   Copy

2. Erteilen Sie der developer-Rolle die READ-Berechtigung für das Geheimnis, damit UDF-Entwickler es verwenden können.

   Erstellen Sie die Rolle, die für Entwickler erforderlich ist, die das Geheimnis verwenden müssen.

   USE ROLE USERADMIN;
   CREATE OR REPLACE ROLE developer;
   

   Copy

   Erteilen Sie die READ-Berechtigung an die developer-Rolle.

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

   Copy

3. Erstellen Sie eine Netzwerkregel, die den Standort des externen Netzwerks repräsentiert. Verwenden Sie eine Rolle mit den unter CREATE NETWORK RULE beschriebenen Berechtigungen.

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

   Copy

4. Erstellen Sie eine Integration für den externen Zugriff unter Verwendung des Geheimnisses und der Netzwerkregel.

   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. Erteilen Sie der developer-Rolle die USAGE-Berechtigung für die Integration, damit UDF-Entwickler sie verwenden können.

   GRANT USAGE ON INTEGRATION google_apis_access_integration TO ROLE developer;
   

   Copy

6. Erstellen Sie einer UDF google_translate_python, die den angegebenen Text in einen Ausdruck in der angegebenen Sprache übersetzt. Weitere Informationen dazu finden Sie unter Verwendung der Integration für den externen Zugriff in einer Funktion oder Prozedur.

   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. Erteilen Sie die USAGE-Berechtigung für die Funktion google_translate_python, damit Personen mit der Benutzerrolle diese Funktion aufrufen können.

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

   Copy

8. Führen Sie die Funktion google_translate_python aus, um einen Ausdruck zu übersetzen.

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

   Copy

   Dies erzeugt die folgende Ausgabe.

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