Integrationen für den externen Zugriff (EAIs) mit App-Spezifikationen anfordern¶

Zugriff auf externe Endpunkte von einer App aus¶

Um auf einen externen Endpunkt zugreifen zu können, muss eine App eine Netzwerkregel und eine Integration für den externen Zugriff erstellen. Eine Integration für den externen Zugriff verwendet Netzwerkregeln, um den Zugriff auf bestimmte externe Netzwerkstandorte zu beschränken. Netzwerkregeln definieren die externen Endpunkte, auf die eine App zugreifen kann.

So konfigurieren Sie eine App für die Verwendung der Integration für den externen Zugriff:

• Verwenden Sie Automatisiertes Gewähren von Berechtigungen, um Berechtigungen vom Verbraucher anzufordern, um eine Integration für den externen Zugriff zu erstellen.

• Fügen Sie eine Integration für den externen Zugriff zu einer App hinzu.

• Verwenden Sie Anwendungsspezifikationen, um beim Verbraucher die Berechtigung anzufordern, eine Verbindung zu einem externen Endpunkt herzustellen.

Workflow für die App-Spezifikation bei Integrationen für den externen Zugriff¶

Der allgemeine Workflow für die Konfiguration einer App für die Verwendung einer Integration für den externen Zugriff lautet 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. Anbietende 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

   • 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 darüber, wie Verbrauchende App-Spezifikationen anzeigen und genehmigen, finden Sie unter Verbindungen zu externen Ressourcen mit App-Spezifikationen genehmigen.

Definition von App-Spezifikationen für Integrationen für den externen Zugriff¶

Für eine Integration für den externen Zugriff enthält die Definition der App-Spezifikationen die folgenden Einträge:

• HOST_PORTS: Eine Liste der in der Netzwerkregel definierten Host-Ports, die die App benötigt.

• PRIVATE_HOST_PORTS: Eine Liste von privaten Host-Ports, die private Konnektivität zu Ressourcen außerhalb von Snowflake ermöglichen.

Die Version der Manifest-Datei festlegen¶

Um das automatisierte Gewähren von Berechtigungen für eine App zu aktivieren, legen Sie die Version am Anfang der Manifest-Datei fest, wie im folgenden Beispiel gezeigt:

manifest_version: 2

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

Mit der Berechtigung CREATE EXTERNAL ACCESS INTEGRATION kann die App während der Installation oder eines Upgrades eine Integration für den externen Zugriff erstellen. 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."
...

Beim Verwenden von manifest_version: 2, wenn die App installiert oder aktualisiert wird, gewährt Snowflake automatisch die Berechtigung CREATE EXTERNAL ACCESS INTEGRATION für die App.

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.

Erstellen Sie eine Integration für den externen Zugriff¶

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;

Eine benutzerdefinierte Funktion für den Zugriff auf den externen Endpunkt erstellen¶

Nach dem Erstellen der Integration für den externen Zugriff kann das Setup-Skript benutzerdefinierte Funktionen und gespeicherte Prozeduren erstellen, die damit eine Verbindung zu den in der Netzwerkregel definierten Endpunkten herstellen.

Das folgende Beispiel zeigt eine benutzerdefinierte Funktion, die die Integration für den externen Zugriff my_app_prefix_eai_rule verwendet.

CREATE OR REPLACE FUNCTION setup.EXTERNAL_ACCESS_UDF(hostname STRING)
  RETURNS STRING
  LANGUAGE JAVA
  HANDLER='TestHostNameLookup.compute'
  EXTERNAL_ACCESS_INTEGRATIONS = (my_app_prefix_eai_rule)
  AS
  '
      import java.net.InetAddress;
      import java.net.UnknownHostException;
      class TestHostNameLookup {{
          public static String compute(String hostname) throws Exception {{
              InetAddress addr = null;
              try {
                  addr = InetAddress.getByName(hostname);
              } catch(UnknownHostException ex) {
                  return "Hostname lookup failed";
              }
              return "Hostname lookup successful";
          }
      }
';
GRANT USAGE ON FUNCTION setup.EXTERNAL_ACCESS_UDF(STRING)
  TO APPLICATION ROLE app_public;

Diese Funktion setzt den Wert von EXTERNAL_ACCESS_INTEGRATIONS auf die zuvor erstellte Integration für den externen Zugriff.

Diese Funktion verwendet das InetAddress-Java-Paket, um den an die Prozedur gegebenen Hostnamen zu ermitteln. Der angegebene Hostname muss mit einem der Werte übereinstimmen, die in der Eigenschaft VALUE_LIST der Netzwerkregeln angegeben sind, die von der Integration für den externen Zugriff verwendet werden.

Eine App-Spezifikation für eine Integration für den externen Zugriff erstellen¶

Das folgende Beispiel zeigt, wie Sie eine App-Spezifikation für eine Integration für den externen Zugriff erstellen:

ALTER APPLICATION SET SPECIFICATION eai_app_spec
        TYPE = EXTERNAL_ACCESS
        LABEL = 'Connection to an external API'
        DESCRIPTION = 'Access an API that exists outside Snowflake'
  HOST_PORTS = ('example.com')

Dieser Befehl erstellt eine App-Spezifikation namens eai_app_spec.

App-Spezifikation im Konto des Verbrauchenden genehmigen¶

Nachdem der Anbietende die App so konfiguriert hat, dass sie die Netzwerkregel, die Integration für den externen Zugriff und die App-Spezifikation erstellt, können die Verbrauchenden die App-Spezifikation anzeigen und sie bei der Konfiguration der App je nach Bedarf genehmigen oder ablehnen. Weitere Informationen dazu finden Sie unter Verbindungen zu externen Ressourcen mit App-Spezifikationen genehmigen.