Kategorien:

DDL für Benutzer und Sicherheit (Integrationen von Drittanbieterdiensten)

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, Externe Funktionen, CREATE EXTERNAL FUNCTION

Unter diesem Thema:

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 }
    API_AWS_ROLE_ARN = '<iam_role>'
    [ API_KEY = '<api_key>' ]
    API_ALLOWED_PREFIXES = ('<...>')
    [ API_BLOCKED_PREFIXES = ('<...>') ]
    ENABLED = { TRUE | FALSE }
    [ COMMENT = '<string_literal>' ]
    ;

Beachten Sie, dass aws_api_gateway und aws_private_api_gateway nicht in Anführungszeichen stehen darf.

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

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

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

Erforderliche Parameter

Für Amazon API Gateway

Integrationsname

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.

Anbieterinfo

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.

IAM-Rolle

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

api_key

The API key (also called a „subscription key“).

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

Integrationsname

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.

Mandanten-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 Directory ID angezeigt.

Azure-Anwendungs-ID

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

api_key

The API key (also called a „subscription key“).

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

Integrationsname

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-Zielgruppe

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.

Nutzungshinweise

  • Nur Snowflake-Benutzer, die die Rolle ACCOUNTADMIN haben oder eine Rolle mit der globalen Berechtigung CREATE INTEGRATION, können CREATE API INTEGRATION ausführen.

  • 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.

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