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

Zugriff auf externe Endpunkte von einer App aus¶

Um auf einen externen Endpunkt zuzugreifen, muss eine App eine Netzwerkregel und eine EAI erstellen, die Netzwerkregeln verwendet, um den Zugriff auf bestimmte externe Netzwerkstandorte einzuschränken. Netzwerkregeln definieren die externen Endpunkte, auf die eine App zugreifen kann.

Führen Sie die folgenden Schritte aus, um eine App für die Verwendung einer EAI zu konfigurieren:

• Um Berechtigungen vom Verbrauchenden anzufordern, um eine EAI zu erstellen, verwenden Sie die automatisierte Erteilung von Berechtigungen.

• Fügen Sie eine EAI zu einer App hinzu.

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

Workflow für App-Spezifikationen für eine EAI¶

1. Anbieter konfigurieren Automatisiertes Gewähren von Berechtigungen für die App. Damit können Verbrauchende einer App die Berechtigung erteilen, die EAI zu erstellen.

   Bemerkung

   App specifications require that manifest_version: 2 be set in the manifest file.

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

3. Anbietende fügen dem Setup-Skript SQL-Anweisungen hinzu, um die folgenden Objekte 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. When configuring the app, consumers review and approve the host ports and external services. For more information on how consumers view and approve app specifications, see Approve app specifications.

Definition von App-Spezifikationen für eine EAI¶

Die Definition der App-Spezifikation für eine EAI enthält 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¶

To enable automated granting of privileges for an app, set the version at the beginning of the manifest file as shown in the following example:

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 EAI to connect to an external service."
  ...
  

  Copy

Wenn Sie die manifest_version auf 2 in der Manifest-Datei einstellen, weist Snowflake automatisch die Berechtigung CREATE EXTERNAL ACCESS INTEGRATION für die App während der Installation oder des Upgrades zu.

Eine Netzwerkregel und eine EAI zum Setup-Skript hinzufügen¶

EAIs sind die Snowflake-Objekte, die den Zugriff auf bestimmte externe Netzwerkstandorte ermöglichen und eine Liste von Netzwerkregeln enthalten, die die externen Standorte angeben, auf die eine App zugreifen kann.

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

  Copy

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ähren Verbrauchende die Berechtigung, dass die App diese Domänen oder Ports verwenden darf.

Eine EAI erstellen¶

• Um eine EAI 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;
  

  Copy

Erstellen einer benutzerdefinierten Funktion für den Zugriff auf den externen Endpunkt¶

Nach dem Erstellen der EAI 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 my_app_prefix_eai_rule EAI 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 EAI.

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 EAI verwendet werden.

Erstellen einer App-Spezifikation für eine EAI¶

Im folgenden Beispiel wird die Erstellung einer App-Spezifikation für eine EAI gezeigt:

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 konfiguriert hat, um die Netzwerkregel, die EAI und die App-Spezifikation zu erstellen, können die Verbrauchenden die App-Spezifikation anzeigen und sie bei Bedarf während der Konfiguration der App genehmigen oder ablehnen. Weitere Informationen dazu finden Sie unter Approve app specifications.