CREATE API INTEGRATION¶

Erstellt ein neues API-Integrationsobjekt im Konto oder ersetzt eine vorhandene API-Integration.

Eine API-Integration Objekt speichert Informationen über einen HTTPS Proxyservice, einschließlich Informationen über die folgenden Punkte:

Ein Anbieter einer Cloud-Plattform (wie Amazon AWS).

Ein Git-Repository.

Die Art des Proxyservice (z. B. wenn ein Anbieter einer Cloud-Plattform mehr als eine Art von Proxyservice anbietet).

Der Bezeichner und die Anmeldeinformationen für den externen Dienst, der über ausreichende Berechtigungen zur Nutzung des Services verfügt. Unter AWS dient beispielsweise der ARN (Amazon-Ressourcenname) der Rolle als Bezeichner und Zugriffsanmeldeinformation.

Wenn diesem Cloudbenutzer die entsprechenden Berechtigungen erteilt werden, kann Snowflake mit diesem Benutzer auf Ressourcen verwenden. Dies kann zum Beispiel eine Instanz des nativen HTTPS-Proxydienstes der Cloud-Plattform sein, zum Beispiel eine Instanz eines Amazon-API-Gateway.

Ein API-Integrationsobjekt gibt auch zulässige (und optional blockierte) Endpunkte und Ressourcen für diese Proxydienste an.

Siehe auch:: ALTER API INTEGRATION, DROP INTEGRATION, SHOW INTEGRATIONS, Schreiben von externen Funktionen, CREATE EXTERNAL FUNCTION

Syntax¶

Die Syntax ist für jedes externe API unterschiedlich.

Für Amazon API Gateway¶

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
  API_PROVIDER = { aws_api_gateway | aws_private_api_gateway | aws_gov_api_gateway | aws_gov_private_api_gateway }
  API_AWS_ROLE_ARN = '<iam_role>'
  [ API_KEY = '<api_key>' ]
  API_ALLOWED_PREFIXES = ('<...>')
  [ API_BLOCKED_PREFIXES = ('<...>') ]
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
  ;

Copy

Beachten Sie, dass aws_api_gateway, aws_private_api_gateway, aws_gov_api_gateway und aws_gov_private_api_gateway nicht in Anführungszeichen stehen dürfen.

Für Azure API Management¶

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
  API_PROVIDER = azure_api_management
  AZURE_TENANT_ID = '<tenant_id>'
  AZURE_AD_APPLICATION_ID = '<azure_application_id>'
  [ API_KEY = '<api_key>' ]
  API_ALLOWED_PREFIXES = ( '<...>' )
  [ API_BLOCKED_PREFIXES = ( '<...>' ) ]
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
  ;

Copy

Beachten Sie, dass azure_api_management nicht in Anführungszeichen stehen darf.

Google Cloud API Gateway¶

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
  API_PROVIDER = google_api_gateway
  GOOGLE_AUDIENCE = '<google_audience_claim>'
  API_ALLOWED_PREFIXES = ( '<...>' )
  [ API_BLOCKED_PREFIXES = ( '<...>' ) ]
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
  ;

Copy

Beachten Sie, dass google_api_gateway nicht in Anführungszeichen stehen darf.

Für das Git-Repository¶

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
  API_PROVIDER = git_https_api
  API_ALLOWED_PREFIXES = ('<...>')
  [ API_BLOCKED_PREFIXES = ('<...>') ]
  [ ALLOWED_AUTHENTICATION_SECRETS = ( { <secret_name> [, <secret_name>, ... ] | all | none } ) ]
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
  ;

Copy

Beachten Sie, dass git_https_api nicht in Anführungszeichen stehen darf.

Erforderliche Parameter¶

Für Amazon API Gateway¶

integration_name

Gibt den Namen der API-Integration an. Dieser Name folgt den Regeln für Objektbezeichner. Der Name sollte unter den API-Integrationen in Ihrem Konto eindeutig sein.

API_PROVIDER = { aws_api_gateway | aws_private_api_gateway | aws_gov_api_gateway | aws_gov_private_api_gateway }

Gibt den Typ des HTTPS-Proxydienstes an. Gültige Werte:

aws_api_gateway: für Amazon API Gateway mit regionalen Endpunkten.

aws_private_api_gateway: für Amazon API Gateway mit privaten Endpunkten.

aws_gov_api_gateway: für Amazon API Gateway mit GovCloud-Endpunkten der US-Regierung.

aws_gov_private_api_gateway: für Amazon API Gateway mit GovCloud-Endpunkten der US-Regierung, die auch private Endpunkte sind.

API_AWS_ROLE_ARN = iam_role

Für Amazon AWS ist dies der ARN (Amazon-Ressourcenname) einer Cloudplattformrolle.

API_ALLOWED_PREFIXES = (...)

Beschränkt explizit externe Funktionen, die die Integration verwenden, um auf einen oder mehrere HTTPS-Proxydienst-Endpunkte (z. B. Amazon API Gateway) und Ressourcen innerhalb dieser Proxys zu verweisen. Unterstützt eine durch Kommas getrennte Liste von URLs, die als Präfixe behandelt werden (Details siehe unten).

Jede URL in API_ALLOWED_PREFIXES = (...) wird als Präfix behandelt. Wenn Sie beispielsweise Folgendes angeben:

https://xyz.amazonaws.com/production/

bedeutet dies, dass alle Ressourcen unter

https://xyz.amazonaws.com/production/

erlaubt sind. Beispielsweise wird Folgendes unterstützt:

https://xyz.amazonaws.com/production/ml1

Um die Sicherheit zu maximieren, sollten Sie so wenige Speicherorte wie möglich zulassen.

ENABLED = { TRUE | FALSE }

Gibt an, ob diese API-Integration aktiviert oder deaktiviert ist. Wenn die API-Integration deaktiviert ist, funktioniert keine der drauf basierenden externen Funktionen.

Der Wert unterscheidet nicht zwischen Groß- und Kleinschreibung.

Die Voreinstellung ist TRUE.

Für Microsoft Azure API Management-Dienst¶

integration_name

Gibt den Namen der API-Integration an. Dieser Name folgt den Regeln für Objektbezeichner. Der Name sollte unter den API-Integrationen in Ihrem Konto eindeutig sein.

API_PROVIDER = azure_api_management

Gibt an, dass diese Integration mit Azure API Management Services verwendet wird. Verwenden Sie keine Anführungszeichen um azure_api_management.

AZURE_TENANT_ID = tenant_id

Gibt die ID für Ihren Office 365-Mandanten an, zu dem alle Azure API Management-Instanzen gehören. Die Authentifizierung einer API-Integration kann nur für einen einzigen Mandanten erfolgen. Daher müssen sich die zulässigen und blockierten Speicherorte auf API Management-Instanzen beziehen, die alle diesem einen Mandanten gehören.

Melden Sie sich beim Azure-Portal an, und klicken Sie auf Azure Active Directory » Properties, um Ihre Mandanten-ID zu ermitteln. Die Mandanten-ID wird im Feld Tenant ID angezeigt.

AZURE_AD_APPLICATION_ID = azure_application_id

Die „Anwendungs-(Client)-ID“ der Azure AD (Active Directory)-App für Ihren Remotedienst. Wenn Sie die Anweisungen unter Erstellen externer Funktionen auf Microsoft Azure befolgt haben, dann ist dies die Azure Function App AD Application ID, die Sie auf dem Arbeitsblatt in dieser Anleitung notiert haben.

API_ALLOWED_PREFIXES = (...)

Beschränkt explizit externe Funktionen, die die Integration verwenden, um auf einen oder mehrere HTTPS-Proxydienst-Endpunkte (z. B. Azure API Management-Dienste) und Ressourcen innerhalb dieser Proxys zu verweisen. Unterstützt eine durch Kommas getrennte Liste von URLs, die als Präfixe behandelt werden (Details siehe unten).

Jede URL in API_ALLOWED_PREFIXES = (...) wird als Präfix behandelt. Wenn Sie beispielsweise Folgendes angeben:

https://my-external-function-demo.azure-api.net/my-function-app-name

bedeutet dies, dass alle Ressourcen unter

https://my-external-function-demo.azure-api.net/my-function-app-name

erlaubt sind. Beispielsweise wird Folgendes unterstützt:

https://my-external-function-demo.azure-api.net/my-function-app-name/my-http-trigger-function

Um die Sicherheit zu maximieren, sollten Sie so wenige Speicherorte wie möglich zulassen.

ENABLED = { TRUE | FALSE }

Gibt an, ob diese API-Integration aktiviert oder deaktiviert ist. Wenn die API-Integration deaktiviert ist, funktioniert keine der drauf basierenden externen Funktionen.

Der Wert unterscheidet nicht zwischen Groß- und Kleinschreibung.

Die Voreinstellung ist TRUE.

Google Cloud API Gateway¶

integration_name

Gibt den Namen der API-Integration an. Dieser Name folgt den Regeln für Objektbezeichner. Der Name sollte unter den API-Integrationen in Ihrem Konto eindeutig sein.

API_PROVIDER = google_api_gateway

Gibt an, dass diese Integration mit Google Cloud verwendet wird. Der einzig gültige Wert für diesen Zweck ist google_api_gateway. Der Wert darf nicht in Anführungszeichen stehen.

GOOGLE_AUDIENCE = google_audience

Dies wird als Zielgruppenanspruch (Audience Claim) beim Generieren des JWT (JSON Web Token) zur Authentifizierung beim Google API Gateway verwendet. Weitere Informationen zur Authentifizierung bei Google finden Sie in der Dokumentation zur Google-Dienstkonto-Authentifizierung.

API_ALLOWED_PREFIXES = (...)

Beschränkt explizit externe Funktionen, die die Integration verwenden, um auf einen oder mehrere HTTPS-Proxydienst-Endpunkte (z. B. Google Cloud API Gateways) und Ressourcen innerhalb dieser Proxys zu verweisen. Unterstützt eine durch Kommas getrennte Liste von URLs, die als Präfixe behandelt werden (Details siehe unten).

Jede URL in API_ALLOWED_PREFIXES = (...) wird als Präfix behandelt. Wenn Sie beispielsweise Folgendes angeben:

https://my-external-function-demo.uc.gateway.dev/x

bedeutet dies, dass alle Ressourcen unter

https://my-external-function-demo.uc.gateway.dev/x

erlaubt sind. Beispielsweise wird Folgendes unterstützt:

https://my-external-function-demo.uc.gateway.dev/x/y

Um die Sicherheit zu maximieren, sollten Sie so wenige Speicherorte wie möglich zulassen.

ENABLED = { TRUE | FALSE }

Gibt an, ob diese API-Integration aktiviert oder deaktiviert ist. Wenn die API-Integration deaktiviert ist, funktioniert keine der drauf basierenden externen Funktionen.

Der Wert unterscheidet nicht zwischen Groß- und Kleinschreibung.

Die Voreinstellung ist TRUE.

Für das Git-Repository¶

Ein Beispiel dazu finden Sie unter API-Integration für Interaktion mit der Repository-API erstellen.

integration_name

Gibt den Namen der API-Integration an. Dieser Name folgt den Regeln für Objektbezeichner. Der Name sollte unter den API-Integrationen in Ihrem Konto eindeutig sein.

API_PROVIDER = git_https_api

Gibt an, dass diese Integration mit CREATE GIT REPOSITORY verwendet wird, um eine Integration mit einem Git-Repository zu erstellen. Der einzig gültige Wert für diesen Zweck ist git_https_api. Der Wert darf nicht in Anführungszeichen stehen.

API_ALLOWED_PREFIXES = (...)

Beschränkt Funktionen, die die Integration verwenden, explizit auf einen oder mehrere HTTPS-Proxydienst-Endpunkte und Ressourcen innerhalb dieser Proxys. Unterstützt eine durch Kommas getrennte Liste von URLs, die als Präfixe behandelt werden.

Snowflake unterstützt die Verwendung der folgenden URLs:

Jede URL in API_ALLOWED_PREFIXES = (...) wird als Präfix behandelt. Wenn Sie beispielsweise Folgendes angeben:

https://github.com/my-account

bedeutet dies, dass alle Ressourcen unter

https://github.com/my-account

erlaubt sind. Beispielsweise wird Folgendes unterstützt:

https://github.com/my-account/myproject

Um die Sicherheit zu maximieren, sollten Sie so wenige Speicherorte wie möglich zulassen.

ENABLED = { TRUE | FALSE }

Gibt an, ob diese API-Integration aktiviert oder deaktiviert ist. Wenn die API-Integration deaktiviert ist, ist der Zugriff auf das Git-Repository nicht möglich.

Der Wert unterscheidet nicht zwischen Groß- und Kleinschreibung.

Die Voreinstellung ist TRUE.

Optionale Parameter¶

API_BLOCKED_PREFIXES = (...)

Listet die Endpunkte und Ressourcen im HTTPS-Proxydienst auf, die nicht von Snowflake aufgerufen werden dürfen.

Die möglichen Werte für Speicherorte folgen den gleichen Regeln wie für API_ALLOWED_PREFIXES oben.

Werte in API_BLOCKED_PREFIXES haben Vorrang vor Werten in API_ALLOWED_PREFIXES. Wenn ein Präfix mit beiden übereinstimmt, wird es blockiert. Mit anderen Worten, Snowflake erlaubt alle Werte, die mit API_ALLOWED_PREFIXES übereinstimmen, mit Ausnahme von Werten, die auch mit API_BLOCKED_PREFIXES übereinstimmen.

Wenn ein Wert außerhalb von API_ALLOWED_PREFIXES liegt, müssen Sie ihn nicht explizit blockieren.

API_KEY = api_key

Der API-Schlüssel (auch „Abonnementschlüssel“ genannt).

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

Gibt die Geheimnisse an, die UDF- oder Prozedur-Handler-Code beim Zugriff auf das Git-Repository unter dem Wert API_ALLOWED_PREFIXES verwenden können. Sie geben ein Geheimnis aus dieser Liste an, wenn Sie Anmeldeinformationen für Git mit dem Parameter GIT_CREDENTIALS angeben.

Der Parameter muss einen der folgenden Werte haben:

Ein oder mehrere vollständig qualifizierte Namen von Snowflake-Geheimnissen, um jedes der aufgeführten Geheimnisse zuzulassen.
(Standard) 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'

Eine Beschreibung der Integration.

Anforderungen an die Zugriffssteuerung¶

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

Berechtigung	Objekt	Anmerkungen
CREATE INTEGRATION	Konto	Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

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¶

Nur Snowflake-Rollen mit den Berechtigungen OWNERSHIP oder USAGE für die API-Integration können die API-Integration direkt verwenden (z. B. indem eine externe Funktion erstellt wird, die diese API-Integration angibt).
Ein API-Integrationsobjekt ist an ein bestimmtes Cloudplattformkonto und eine bestimmte Rolle in diesem Konto gebunden, jedoch nicht an eine bestimmte HTTPS-Proxy-URL. Sie können mehr als eine Instanz eines HTTPS-Proxydienstes in einem Cloudanbieterkonto erstellen und dieselbe API-Integration verwenden, um sich bei mehreren Proxydiensten in diesem Konto zu authentifizieren.
Ihr Snowflake-Konto kann mehrere API-Integrationsobjekte enthalten, z. B. für verschiedene Cloudplattformkonten.
Mehrere externe Funktionen können dasselbe API-Integrationsobjekt und damit denselben HTTPS-Proxydienst verwenden.
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.
CREATE OR REPLACE <Objekt>-Anweisungen sind atomar. Das heißt, wenn ein Objekt ersetzt wird, erfolgt das Löschen des alten Objekts und das Erstellen des neuen Objekts in einer einzigen Transaktion.

Beispiele¶

Amazon API Gateway¶

Das folgende Beispiel zeigt die Erstellung einer API-Integration und die Verwendung dieser API-Integration in einer nachfolgenden CREATE EXTERNAL FUNCTION-Anweisung:

CREATE OR REPLACE API INTEGRATION demonstration_external_api_integration_01
  API_PROVIDER = aws_api_gateway
  API_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/my_cloud_account_role'
  API_ALLOWED_PREFIXES = ('https://xyz.execute-api.us-west-2.amazonaws.com/production')
  ENABLED = TRUE;

CREATE OR REPLACE EXTERNAL FUNCTION local_echo(string_col VARCHAR)
  RETURNS VARIANT
  API_INTEGRATION = demonstration_external_api_integration_01
  AS 'https://xyz.execute-api.us-west-2.amazonaws.com/production/remote_echo';

Copy

Git-Repository¶

Ein Beispiel für eine API-Integration, die zur Integration eines Git-Repositorys verwendet wird, finden Sie unter API-Integration für Interaktion mit der Repository-API erstellen.