CREATE API INTEGRATION¶

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

Ein API-Integrationsobjekt speichert Informationen zu einem HTTPS-Proxydienst, einschließlich Informationen zu:

Cloudplattformanbieter (z. B. Amazon AWS)

Typ des Proxydienstes (falls der Cloudplattformanbieter mehr als einen Typ von Proxydienst anbietet)

Bezeichner und Zugriffsanmeldeinformationen einer Cloudplattformrolle, die über ausreichende Berechtigungen zur Verwendung des Proxydienstes 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 des Proxydienstes zugreifen (eine Instanz des nativen HTTPS-Proxydienstes der Cloudplattform, z. B. 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 jede Cloudplattform 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.

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.

provider_info

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.

iam_role

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

api_key

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

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.

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.

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.

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_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_key

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

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.

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.

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.

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.

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.

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.

Optionale Parameter¶

Diese optionale Parameter gelten für:

Amazon API Gateway
Microsoft Azure API Management-Dienst
Google Cloud API Gateway

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.

COMMENT = '<string_literal>'

Eine Beschreibung der externen Funktion.

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¶

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