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 Kennung 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 AWS 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 AWS 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_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 sollten.

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

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

Erforderliche Parameter

Für Amazon AWS 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.

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 AWS 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 einer anpassbaren externen Funktion auf Azure befolgt haben, dann ist dies die „AD-Anwendungs-ID der Azure-Funktionen-App“, die Sie im Arbeitsblatt in dieser Anleitung notiert haben.

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.

Optionale Parameter

Diese optionalen Parameter gelten für beide:

  • Amazon AWS API Gateway

  • Microsoft Azure API Management-Dienst

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