Beispiel – Konfigurieren des externen Zugriffs für Dienste in einer App mit Containern¶

Fügen Sie der Manifest-Datei eine Referenz auf die Integration für den externen Zugriff hinzu¶

Das folgende Beispiel zeigt, wie ein Anbieter eine Integration für den externen Zugrifff in der Manifest-Datei definiert:

references:
  ...
  - my_external_access:
      label: "Default External Access Integration"
      description: "This EAI is required to access xyz.com"
      privileges:
        - USAGE
      object_type: EXTERNAL ACCESS INTEGRATION
      required_at_setup: true
      register_callback: config.REGISTER_EAI_CALLBACK
      configuration_callback: config.get_config_for_ref

In diesem Beispiel werden unter references unter anderem die folgenden Eigenschaften angegeben:

• my_external_access: Gibt den Namen der externen Referenz an.

  • privileges: Listet die Berechtigungen auf, die für die Integrationen für den externen Zugriff erforderlich sind. In diesem Beispiel ist die USAGE-Berechtigung erforderlich.

  • object_type: EXTERNAL ACCESS INTEGRATION: Zeigt eine Referenz auf eine Integration für den externen Zugriff an.

  • required_at_setup: Gibt an, dass der Verbraucher den Zugriff auf das Objekt autorisieren muss, bevor die App das Objekt erstellen kann, wenn es auf true eingestellt ist.

  • register_callback: Gibt die gespeicherte Prozedur für den Callback an, mit der die Referenz bei der App registriert wird.

  • configuration_callback: Gibt die Callback-Funktion für die Konfiguration des Geheimnisses an. Weitere Informationen dazu finden Sie unter Funktion „configuration_callback“ zu Setup-Skript hinzufügen.

Fügen Sie der Manifest-Datei eine geheime Referenz hinzu.¶

Das folgende Beispiel zeigt, wie ein Anbieter ein Geheimnis in der Manifest-Datei definiert:

references:
 ...
 - consumer_secret:
     label: "Consumer secret"
     description: "Needed to authenticate with an external endpoint"
     privileges:
       - READ
     object_type: SECRET
     register_callback: config.register_my_secret
     configuration_callback: config.get_config_for_ref

In diesem Beispiel werden unter references unter anderem die folgenden Eigenschaften angegeben:

• consumer_secret: Gibt den Namen der Referenz an.

  • privileges: Listet die Berechtigungen auf, die für das Geheimnis erforderlich sind. In diesem Beispiel ist die READ-Berechtigung angegeben.

  • object_type: SECRET: Zeigt an, dass die Referenz ein Geheimnis ist.

  • register_callback: Gibt die gespeicherte Prozedur für den Callback an, mit der die Referenz bei der App registriert wird.

  • configuration_callback: Gibt die Callback-Funktion für die Konfiguration des Geheimnisses an. Weitere Informationen dazu finden Sie unter Funktion „configuration_callback“ zu Setup-Skript hinzufügen.

Funktion „configuration_callback“ zu Setup-Skript hinzufügen¶

Nachdem Sie die Verweise für die Integration das Geheimnis und die Integration für den externen Zugriff hinzugefügt haben, müssen Sie die Funktion configuration_callback in das Setup-Skript einfügen. Um eine Integration für den externen Zugriff oder ein Geheimnis zu erstellen, muss die App in der Lage sein, Werte für den Port des Hosts, den Typ des Geheimnisses, den Endpunkt für die Autorisierung und das Token für OAuth zu bestimmen usw. Die configuration_callback-Funktion stellt der App diese Informationen vom Konto des Verbrauchers bereit.

CREATE OR REPLACE PROCEDURE CONFIG.GET_CONFIG_FOR_REFERENCE(ref_name STRING)
RETURNS STRING
LANGUAGE SQL
AS
$$
BEGIN
 CASE (UPPER(ref_name))
   WHEN 'my_external_access' THEN
     RETURN '{
       "type": "CONFIGURATION",
       "payload":{
         "host_ports":["google.com"],
         "allowed_secrets" : "LIST",
         "secret_references":["CONSUMER_SECRET"]}}';
   WHEN 'consumer_secret' THEN
     RETURN '{
       "type": "CONFIGURATION",
       "payload":{
         "type" : "OAUTH2",
         "security_integration": {
           "oauth_scopes": ["https://www.googleapis.com/auth/analytics.readonly"],
           "oauth_token_endpoint": "https://oauth2.googleapis.com/token",
           "oauth_authorization_endpoint":
               "https://accounts.google.com/o/oauth2/auth"}}}';
  END CASE;
  RETURN '';
END;
$$;

Snowsight führt diese Prozedur aus, um den Konfigurationsdialog zu füllen, der den Benutzer auffordert, die erforderlichen Objekte zu konfigurieren.

Damit die Prozedur ausgeführt wird, muss sie einer App-Rolle zugewiesen werden, wie im folgenden Beispiel gezeigt:

GRANT USAGE ON PROCEDURE CONFIG.GET_CONFIG_FOR_REFERENCE(STRING)
  TO APPLICATION ROLE app_admin;

Best Practices für die Verwendung von Integrationen für den externen Zugriff in einer App mit Containern¶

Snowflake empfiehlt die folgenden Best Practices für die Verwendung von Integrationen für den externen Zugriff in einer App mit Containern:

• Jede Referenz auf Integrationen für den externen Zugriff, die in einem CREATE SERVICE oder ALTER SERVICE-Befehl angegeben sind, muss gebunden sein, bevor die Befehle im Setup-Skript ausgeführt werden. Diese Befehle schlagen fehl, wenn die Referenz nicht gebunden ist.

• Alle Referenzen auf Geheimnisse, die in der Servicespezifikation angegeben sind, müssen ebenfalls gebunden sein, bevor die Befehle CREATE SERVICE oder ALTER SERVICE im Setup-Skript ausgeführt werden. Diese Befehle schlagen fehl, wenn die Referenz nicht gebunden ist.

• Wenn eine Nutzlast des Typs ERROR in der configuration_callback-Funktion zurückgegeben wird, sollten Anbieter eine informative Fehlermeldung zurückgeben, die dem Verbraucher hilft, die Ursache des Fehlers zu verstehen und ihn zu beheben. Beispiel:

  • Wenn ein Fehler in der App auftritt

  • Wenn die Referenz noch nicht erforderlich ist

  • Wenn die Referenz nicht bereit ist, zugelassen zu werden.

• Wenn die Funktion configuration_callback-Referenzen enthält, bei denen die Eigenschaft required_at_setup auf TRUE gesetzt ist, muss die Funktion configuration_callback beim Setup erfolgreich sein. In diesem Zusammenhang kann die configuration_callback-Funktion nicht von den Informationen des Verbrauchers abhängig sein.

• Wenn Sie eine Referenz auf eine Integration für den externen Zugriff auf einen Dienst verwenden, sollten Sie in Erwägung ziehen, den Dienst mit ALLOWED_AUTHENTICATION_SECRETS = ALL zu erstellen, wenn die App vom Verbraucher bereitgestellte Geheimnisse benötigt. Dies vereinfacht die Handhabung eines Geheimnisses innerhalb einer Integration für den externen Zugriff.

• Wenn eine App nur bestimmte Endpunkte erreichen muss und keine Geheimnisse benötigt, verwenden Sie ALLOWED_AUTHENTICATION_SECRETS = NONE. NONE ist der Standardwert. Weitere Informationen dazu finden Sie unter CREATE EXTERNAL ACCESS INTEGRATION.

• Wenn die Anwendung eine Referenz aktualisieren muss, heben Sie zunächst die Bindung der Referenz auf und fordern dann den Verbraucher auf, ein neues Objekt zu erstellen und an die Referenz zu binden. Ein Verbraucher kann ein vorhandenes Objekt bearbeiten und binden. Siehe CREATE EXTERNAL ACCESS INTEGRATION.