App-Spezifikationen zur Anforderung externer Endpunkte von Verbrauchern verwenden¶

Auf externe Services von einer Snowflake Native App aus zugreifen¶

Einige Snowflake Native Apps müssen eine Verbindung zu Ressourcen herstellen, die außerhalb von Snowflake existieren. Je nach Art der erforderlichen externen Verbindung stellt Snowflake unterschiedliche Objekte bereit.

Bei Verwendung von Automatisiertes Gewähren von Berechtigungen verfügt eine App über die erforderlichen Berechtigungen, um diese Objekte beim Ausführen des Setup-Skripts zu erstellen. Da diese Objekte jedoch Verbindungen außerhalb von Snowflake zulassen, müssen Verbraucher diese Verbindungen bei der Konfiguration der App genehmigen.

Mit App-Spezifikationen kann ein Anbieter angeben, welche Verbindungsinformationen die App anfordert. Wenn der Verbraucher die App installiert, überprüft er die App-Spezifikation und genehmigt sie je nach Bedarf.

Workflow für App-Spezifikationen¶

Der allgemeine Workflow für die Konfiguration und Verwendung einer App-Spezifikation ist wie folgt:

1. Anbieter konfigurieren Automatisiertes Gewähren von Berechtigungen für die App. Damit können Verbraucher einer App die Berechtigung erteilen, die Integration für den externen Zugriff zu erstellen.

   Bemerkung

   App-Spezifikationen erfordern, dass manifest_version = 2 in der Manifest-Datei festgelegt wird.

2. Anbieter fügen die Berechtigung CREATE EXTERNAL ACCESS INTEGRATION zur Manifest-Datei hinzu.

3. Anbieter fügen dem Setup-Skript SQL-Anweisungen hinzu, um die folgenden Objekte nach Bedarf zu erstellen:

   • Netzwerkregel

   • Integration für den externen Zugriff

   • Sicherheitsintegration

   • App-Spezifikation

   Das Setup-Skript erstellt die App-Spezifikation und andere Objekte, wenn die App installiert oder aktualisiert wird, oder zur Laufzeit.

4. Bei der Konfiguration der App genehmigen Verbraucher die Host-Ports und andere externe Services. Weitere Informationen dazu finden Sie unter Verbindungen zu externen Ressourcen mit App-Spezifikationen genehmigen.

Die Berechtigung CREATE EXTERNAL ACCESS INTEGRATION zur Manifest-Datei hinzufügen¶

Um eine App so zu konfigurieren, dass sie die Berechtigung CREATE EXTERNAL ACCESS INTEGRATION anfordert, fügen Sie den folgenden Code in den Abschnitt privileges der Manifest-Datei ein:

manifest_version: 2
...
privileges:
  - CREATE EXTERNAL ACCESS INTEGRATION:
      description: "Allows the app to create an external access integration to connect to an external service."
...

Dieser Eintrag im Abschnitt privileges der Manifest-Datei gibt an, dass die App eine Integration für den externen Zugriff verwendet. Damit die App das automatisierte Gewähren von Berechtigungen nutzen kann, muss in der Manifest-Datei auch manifest_version: 2 festgelegt werden.

Dem Setup-Skript eine Netzwerkregel und eine Integration für den externen Zugriff hinzufügen¶

Integrationen für den externen Zugriff sind die Snowflake-Objekte, die den Zugriff auf bestimmte externe Netzwerkstandorte ermöglichen. Integrationen für den externen Zugriff enthalten eine Liste von Netzwerkregeln, die die externen Standorte festlegen, auf die eine App zugreifen darf.

Um eine Netzwerkregel für eine App zu erstellen, fügen Sie dem Setup-Skript den Befehl CREATE NETWORK RULE hinzu, wie im folgenden Beispiel gezeigt:

CREATE OR REPLACE NETWORK RULE setup.my_network_rule
 TYPE = HOST_PORT
 VALUE_LIST = ( 'example.com' )
 MODE = EGRESS;

Die Eigenschaften HOST_PORT und VALUE_LIST zeigen an, dass die Netzwerkregel auf eine gültige Domäne, einen gültigen Port oder einen gültigen Portbereich verweisen muss. Wenn eine App installiert oder aktualisiert wird, gewährt ein Verbraucher die Berechtigung, dass die App diese Domänen oder Ports verwenden darf.

Um eine Integration für den externen Zugriff für eine App zu erstellen, fügen Sie dem Setup-Skript den Befehl CREATE EXTERNAL ACCESS INTEGRATION hinzu, wie im folgenden Beispiel gezeigt:

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION my_app_prefix_eai_rule
  ALLOWED_NETWORK_RULES = (setup.my_network_rule)
  ENABLED = TRUE;

Dieser Befehl erstellt eine Integration für den externen Zugriff namens my_app_prefix_eai_rule, die es der App ermöglicht, auf externe Ressourcen oder Endpunkte zuzugreifen. Sie verwendet die setup.my_network_rule-Netzwerkregel.

Dem Setup-Skript eine Sicherheitsintegration hinzufügen¶

Durch Sicherheitsintegrationen kann sich eine App mit einem Authentifizierungsservice eines Drittanbieters wie OAuth verbinden. Um eine Sicherheitsintegration für eine App zu erstellen, verwenden Sie den Befehl CREATE SECURITY INTEGRATION (Externe API-Authentifizierung), wie im folgenden Beispiel gezeigt:

CREATE SECURITY INTEGRATION external_oauth_provider
  TYPE = API_AUTHENTICATION
  AUTH_TYPE = OAUTH2
  OAUTH_CLIENT_AUTH_METHOD = CLIENT_SECRET_POST
  OAUTH_CLIENT_ID = 'YOUR_CLIENT_ID'
  OAUTH_CLIENT_SECRET = 'YOUR_CLIENT_SECRET'
  OAUTH_GRANT = 'CLIENT_CREDENTIALS'
  OAUTH_TOKEN_ENDPOINT = 'https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token'
  OAUTH_ALLOWED_SCOPES = ('https://graph.microsoft.com/.default')
  ENABLED = TRUE;

Dieses Beispiel zeigt, wie Sie eine Sicherheitsintegration erstellen, um sich über OAuth mit Client-Anmeldeinformationen mit Microsoft Sharepoint zu verbinden. Weitere unterstützte Methoden zum Verbinden mit einem OAuth-Anbieter finden Sie unter CREATE SECURITY INTEGRATION (Externe API-Authentifizierung).

Eine App-Spezifikation im Setup-Skript erstellen¶

Um die App-Spezifikation zu erstellen, fügen Anbieter dem Setup-Skript den Befehl ALTER APPLICATION SET SPECIFICATIONS hinzu.

ALTER APPLICATION SET SPECIFICATION eai_app_spec
        TYPE = EXTERNAL_ACCESS
        LABEL = 'Connection to an external API'
        DESCRIPTION = 'Access an API that exists outside Snowflake'

ALTER APPLICATION SET SPECIFICATION oauth_app_spec
  TYPE = SECURITY_INTEGRATION
  LABEL = 'Connection to an external OAuth provider'
  DESCRIPTION = 'Integrates an external identity provider in the app'
  OAUTH_TYPE = 'CLIENT_CREDENTIALS'
  OAUTH_TOKEN_ENDPOINT = 'https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token'
  OAUTH_ALLOWED_SCOPES = ('https://graph.microsoft.com/.default');

Best Practices bei der Verwendung von App-Spezifikationen¶

Automatisiertes Gewähren von Berechtigungen stellt sicher, dass die App über die erforderlichen Berechtigungen verfügt, um Integrationen für den externen Zugriff zu erstellen. Dennoch können Verbraucher die App-Spezifikation, die die Verbindung zu den externen Endpunkten aktiviert, ablehnen. Bei der Entwicklung einer App müssen Anbieter Situationen berücksichtigen, in denen App-Spezifikationen möglicherweise nicht genehmigt werden.

Beispielsweise könnte eine App die Verwendung mehrerer Netzwerkports für eine Integration für den externen Zugriff anfordern, der Verbraucher jedoch nur einen zulassen. Die App sollte Logik zur Behandlung von Fehlern enthalten, die auftreten, wenn ein Netzwerkport nicht verfügbar ist. Außerdem ist es Best Practice, alle möglicherweise auftretenden HTTP-Ausnahmen zu erfassen.

Callback-Funktionen mit App-Spezifikationen verwenden¶

In manchen Fällen muss eine App möglicherweise wissen, wann der Verbraucher eine App-Spezifikation genehmigt oder abgelehnt hat. Beispielsweise muss die App möglicherweise warten, bis eine App-Spezifikation genehmigt wurde, bevor sie ein Objekt erstellt.

Für diese Situation bietet Snowflake Native App Framework einen Mechanismus, mit dem Anbieter eine gespeicherte Callback-Prozedur definieren können, die ausgeführt wird, wenn der Verbraucher eine App-Spezifikation genehmigt oder ablehnt.

Anbieter können der Manifest-Datei eine gespeicherte Prozedur hinzufügen, wie im folgenden Beispiel gezeigt:

lifecycle_callbacks:
  specification_action: callbacks.on_spec_update

Dieses Beispiel zeigt, wie eine gespeicherte Prozedur namens callbacks.on_spec_update in die Manifest-Datei aufgenommen wird. Anbieter können im Setup-Skript eine gespeicherte Prozedur hinzufügen, wie im folgenden Beispiel gezeigt:

CREATE OR REPLACE PROCEDURE callbacks.on_spec_update (
  name STRING,
  status STRING,
  payload STRING)
  ...

Dieses Beispiel zeigt die Signatur einer gespeicherten Prozedur namens callbacks.on_spec_update. Im Text dieser Prozedur fügen Anbieter den erforderlichen Code ein, um den Status der App-Spezifikation zu überprüfen, Objekte zu erstellen und bei Bedarf Aktionen auszuführen.