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

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 im aktuellen Schema eindeutig sein.

Anbieterinfo

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

  • aws_api_gateway: für Amazon AWS API Gateway.

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.

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.

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.

  • Unter AWS sind für externe Funktionen regionale Endpunkte erforderlich. Weitere Details dazu finden Sie unter Amazon AWS API Gateway.

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