Anwendungskonfiguration¶

Unter diesem Thema wird beschrieben, wie eine Snowflake Native App Konfigurationsobjekte der Anwendung verwenden kann, um Eingaben vom Verbrauchende anzufordern.

Anwendungskonfiguration: Überblick¶

Eine Anwendungskonfiguration ist ein Schlüssel-Wert-Paar, das einen Koordinationsmechanismus zwischen einer Snowflake Native App und dem Verbrauchenden bereitstellt. Wenn eine Snowflake Native App eine Eingabe vom Verbrauchenden erfordert, definiert dieses Paar einen Konfigurationsschlüssel zusammen mit einer Beschreibung, die den Zweck der Konfiguration erläutert. Der Verbrauchende gibt dann den Wert für diesen Schlüssel an.

Die Anwendungskonfiguration unterstützt die folgenden Typen:

APPLICATION_NAME: Der Verbrauchende gibt den Namen einer installierten App im Verbraucherkonto an. Dieser Typ wird für die :doc:` Kommunikation zwischen Apps<inter-app-communication>` verwendet.
STRING: Der Verbrauchende stellt einen beliebigen Zeichenfolgenwert bereit. Dieser Typ kann für eine Vielzahl von Anwendungsfällen verwendet werden, z. B. für die Bereitstellung von externenURLs, Kontobezeichner oder andere App-spezifische Einstellungen.
SECRET_AUTHORIZATION: The consumer completes an OAuth flow to populate a secret with tokens. This type is used when the provider creates the security integration and secret, and the consumer completes third-party authentication directly. For more information, see Request OAuth authorization from consumers.

Der Workflow für die Anwendungskonfiguration umfasst die folgenden Schritte:

Die App erstellt eine Konfigurationsdefinition mit:code:ALTER APPLICATION SET CONFIGURATION DEFINITION und gibt den Typ der benötigten Informationen und die App-Rollen an, die Zugriff auf die Konfiguration haben.
Der Verbrauchende zeigt eingehende Konfigurationsanforderungen mithilfe von SHOW CONFIGURATIONS oder Snowsight an.
Der Verbrauchende stellt den angeforderten Wert über ALTER APPLICATION SET CONFIGURATION VALUE oder Snowsight bereit.
Die App ruft den Wert ab und verwendet ihn, um weitere Vorgänge auszuführen, z. B. das Erstellen einer Anwendungsspezifikation für eine Verbindung.

Das Snowflake Native App Framework bietet Callbacks, um die App zu benachrichtigen, wenn ein Konfigurationswert festgelegt oder geändert wird. Weitere Informationen dazu finden Sie unter Konfigurations-Callbacks.

Terminologie¶

Unter der Anwendungskonfiguration werden die folgenden Begriffe verwendet:

Konfigurationsdefinition: Ein Objekt, das die App erstellt, um eine bestimmte Information vom Verbrauchenden anzufordern. Die Konfigurationsdefinition gibt die Art der angeforderten Informationen, eine Bezeichnung, eine Beschreibung und die App-Rollen an, die Zugriff auf die Konfiguration haben.
Konfigurationswert: Der Wert, den der Verbrauchende als Antwort auf eine Anforderung nach Konfigurationsdefinitionen angibt.

Verwenden von Konfigurationen¶

Unter diesem Thema wird beschrieben, wie Sie Konfigurationen erstellen, anzeigen und verwalten.

Erstellen einer Konfigurationsanforderung
Anzeigen von Konfigurationsanforderungen
Angeben des Konfigurationswerts
Aktualisieren des Werts einer Konfiguration
Zurücksetzen des Werts einer Konfiguration
Abrufen des Werts einer Konfiguration

Erstellen einer Konfigurationsanforderung¶

Um einen Konfigurationswert vom Verbrauchenden anzufordern, erstellt die App eine Konfigurationsdefinition im Setup-Skript oder zur Laufzeit. Die Konfigurationsdefinition gibt den erwarteten Werttyp an, eine Bezeichnung und eine Beschreibung, die dem Verbrauchenden angezeigt werden, und die App-Rollen, die die Konfiguration anzeigen und den Wert bearbeiten können.

Das folgende Beispiel zeigt, wie Sie eine Konfigurationsdefinition vom Typ STRING erstellen, die eine Unternehmens-URL vom Verbrauchenden anfordert:

ALTER APPLICATION SET CONFIGURATION DEFINITION company_url
  TYPE = STRING
  LABEL = 'Company URL'
  DESCRIPTION = 'Provide the company website URL'
  APPLICATION_ROLES = (app_user)
  SENSITIVE = FALSE;

Die folgenden Eigenschaften steuern, wie die Konfiguration angezeigt und verwaltet wird:

LABEL: Der Name, der dem Verbrauchenden in Snowsight angezeigt wird.
DESCRIPTION: Eine Beschreibung, die dem Verbrauchenden hilft, den Zweck der Konfiguration zu verstehen.
APPLICATION_ROLES: Die App-Rollen, die den Wert für diese Konfiguration anzeigen und festlegen können. Verbraucherrollen, denen eine der angegebenen App-Rollen zugewiesen wurde, können die Konfiguration anzeigen und deren Wert bearbeiten.
SENSITIVE: Specifies whether the configuration value should be treated as sensitive. When set to TRUE, the value is not displayed in the output of SHOW CONFIGURATIONS. Required when TYPE = STRING. For more information, see Sensible Konfigurationen.

Anzeigen von Konfigurationsanforderungen¶

After an app creates a configuration request, the consumer can view pending requests using Snowsight or SQL.

Zum Anzeigen der Konfigurationsanforderungen und der Details einer Konfigurationsdefinition unter Verwendung von Snowsight gehen Sie wie folgt vor:

Sign in to Snowsight.
Wählen Sie im Navigationsmenü die Option Catalog » Apps aus.
Wählen Sie die App aus.
Open the Configurations tab. The Configurations section displays the string configurations in the Other configurations section. Each string configuration shows the following:
- Die Bezeichnung der Konfiguration.
- Eine Beschreibung, wofür die Konfiguration vorgesehen ist.
- Eine Schaltfläche Review.

Zum Anzeigen der Konfigurationsanforderungen und der Details einer Konfigurationsdefinition unter Verwendung von SQL verwenden Sie die Befehle SHOWCONFIGURATIONS und DESCRIBECONFIGURATION:

SHOW CONFIGURATIONS IN APPLICATION example_app;

DESCRIBE CONFIGURATION company_url IN APPLICATION example_app;

Angeben des Konfigurationswerts¶

After the app creates a configuration request, the consumer provides the requested value using Snowsight or SQL.

Um einen Wert für die Konfiguration mithilfe von Snowsight bereitzustellen, gehen Sie wie folgt vor:

Klicken Sie auf der Detailseite der Konfiguration in Snowsight auf die Schaltfläche Review. Auf der Seite mit den Konfigurationsdetails wird Folgendes angezeigt:
- Die Bezeichnung der Konfiguration.
- Eine Beschreibung, wofür die Konfiguration vorgesehen ist.
- Wenn die Konfiguration sensibel ist, wird das Banner Sensitive data protection angezeigt. Weitere Informationen dazu finden Sie unter Sensible Konfigurationen.
Geben Sie den Wert für die Konfiguration im Feld Value an.
Klicken Sie auf die Schaltfläche Save, um den Wert für die Konfiguration zu übermitteln. Configuration updated successfully wird angezeigt. Die Konfigurationsliste wird aktualisiert und zeigt den neuen Wert an.

Um einen Wert für die Konfiguration mithilfe von SQL bereitzustellen, verwenden Sie den Befehl ALTER APPLICATION SET CONFIGURATION VALUE:

ALTER APPLICATION <app> SET CONFIGURATION <config> VALUE = '<value>';

Aktualisieren des Werts einer Konfiguration¶

You can update the value of a configuration using Snowsight or SQL.

Zum Aktualisieren des Werts einer Konfiguration mithilfe von Snowsight gehen Sie wie folgt vor:

Wenn für eine Konfiguration ein Wert festgelegt ist, werden auf der Detailseite der Konfiguration in Snowsight die folgenden Informationen angezeigt:
- Ein Banner mit dem Text Configured.
- Wenn die Konfiguration nicht sensibel ist, wird der Wert angezeigt.
- Wenn die Konfiguration sensibel ist, wird der Wert maskiert.
- Eine Schaltfläche Update.
- Eine Schaltfläche Clear value.
Click the Update button to update the value for the configuration.
Geben Sie den neuen Wert für die Konfiguration im Feld Value an.
Klicken Sie auf die Schaltfläche Save, um den neuen Wert für die Konfiguration zu übermitteln. Configuration updated successfully wird angezeigt. Die Konfigurationsliste wird aktualisiert und zeigt den neuen Wert an.

Um einen Konfigurationswert zu aktualisieren, verwenden Sie dieselbe Syntax wie beim Festlegen des Anfangswerts:

ALTER APPLICATION <app> SET CONFIGURATION <config> VALUE = '<value>';

Zurücksetzen des Werts einer Konfiguration¶

You can unset the value of a configuration using Snowsight or SQL.

Zum Zurücksetzen des Werts einer Konfiguration mithilfe von Snowsight gehen Sie wie folgt vor:

Klicken Sie auf der Detailseite der Konfiguration in Snowsight auf die Schaltfläche Clear value.
Bestätigen Sie die Aktion. Die Konfigurationsliste wird aktualisiert, um die zurückgesetzte Konfiguration anzuzeigen.

Um den Wert einer Konfiguration mithilfe von SQL zurückzusetzen, verwenden Sie den Befehl ALTER APPLICATION UNSET CONFIGURATION:

ALTER APPLICATION <app> UNSET CONFIGURATION <config>;

Abrufen des Werts einer Konfiguration¶

Zusätzlich zu SHOWCONFIGURATIONS oderDESCRIBECONFIGURATION kann eine App den Wert einer Konfiguration abrufen, die der Verbrauchende über die Funktion :doc:` get_configuration_value</sql-reference/functions/get_configuration_value>` angegeben hat. Das folgende Beispiel zeigt, wie Sie den Wert einer Konfiguration abrufen:

SELECT SYS_CONTEXT('SNOWFLAKE$APPLICATION', 'GET_CONFIGURATION_VALUE' , '<config_name>')

Bemerkung

Nur die App kann den Konfigurationswert aus dem Systemkontext abrufen. Um den Konfigurationswert als Verbrauchender anzuzeigen, können Sie die Konfigurationsdetails entweder mithilfe von SQL oder Snowsight anzeigen. Weitere Informationen dazu finden Sie unter Anzeigen von Konfigurationsanforderungen.

Sensible Konfigurationen¶

Wenn eine App eine Konfiguration erstellt, kann sie die Konfiguration durch die Einstellung SENSITIVE = TRUE als sensibel markieren. Dies ist nützlich, wenn die App vom Verbrauchende sensible Informationen anfordern muss, wie z. B. ein persönliches Zugriffstoken oder einenAPI-Schlüssel.

Bemerkung

Die SENSITIVE-Eigenschaft wird nur für Konfigurationen des Typs STRING unterstützt.

Wenn eine Konfiguration sensibel ist, ist der vom Verbrauchenden angegebene Wert vor anderen Verbrauchenden und Rollen geschützt. Das Snowflake Native App Framework wendet ähnliche Schutzmaßnahmen an wie für SECRET-Objekte in Snowflake:

Nachdem der Verbrauchende einen Wert festgelegt hat, wird er im Abfrageverlauf des ALTER APPLICATION SET CONFIGURATION VALUE-Befehls ausgeblendet, sodass er für andere Verbraucherrollen oder Benutzende nicht sichtbar ist.
Der Wert wird in der Ausgabe von SHOW CONFIGURATIONS,:code:DESCRIBE CONFIGURATION,INFORMATION_SCHEMA-Ansichten oder ACCOUNT_USAGE-Ansichten nicht angezeigt.

Die App, die die Konfiguration erstellt, kann immer den vom Verbrauchenden angegebenen Wert abrufen, auch wenn die Konfiguration sensibel ist. Dies ist beabsichtigt, denn der Zweck einer Anwendungskonfiguration ist es, dass der Verbrauchende der App einen Wert zur Verfügung stellen kann.

Ändern der SENSITIVE-Eigenschaft¶

Eine App kann die SENSITIVE-Eigenschaft nicht ändern, während für die Konfiguration ein Wert festgelegt ist (d. h. wenn sich die Konfiguration nicht in einem PENDING-Status befindet). Diese Einschränkung verhindert, dass der Wert des Verbrauchenden versehentlich offengelegt wird. Wenn die App versucht, die SENSITIVE-Eigenschaft zu ändern, während ein Wert festgelegt ist, wird der Befehl ohne Fehler abgeschlossen, hat aber keine Auswirkungen.

Um die SENSITIVE-Eigenschaft zu ändern, muss der Verbrauchende zunächst den Konfigurationswert mithilfe von ALTER APPLICATION UNSET CONFIGURATION zurücksetzen.

SQL-Referenz¶

Die folgenden SQL-Befehle, Funktionen und Ansichten werden zum Verwalten von Anwendungskonfigurationen verwendet.

SQL-Befehle¶

ALTER APPLICATION SET CONFIGURATION DEFINITION: Erstellt oder aktualisiert eine Definition für die Konfiguration der Anwendung, die einen Wert vom Verbrauchenden anfordert.
ALTER APPLICATION DROP CONFIGURATION DEFINITION: Löscht die Definition einer Anwendungskonfiguration.
ALTER APPLICATION SET CONFIGURATION VALUE: Legt einen Wert in einer Anwendungskonfiguration fest.
ALTER APPLICATION UNSET CONFIGURATION: Setzt den Wert einer Anwendungskonfiguration zurück.
SHOW-CONFIGURATIONS: Listet alle Anwendungskonfigurationen in einer App auf.
DESCRIBE-CONFIGURATION: Beschreibt die Details einer Anwendungskonfiguration.

SQL-Funktionen¶

IS_CONFIGURATION_SET (SYS_CONTEXT-Funktion): Gibt zurück, ob für die Konfiguration ein Wert festgelegt wurde oder nicht.
GET_CONFIGURATION_VALUE (SYS_CONTEXT-Funktion): Gibt den aktuellen Wert einer Konfiguration zurück.

Information Schema-Ansichten und -Funktionen¶

Ansicht APPLICATION_CONFIGURATIONS: In dieser Information Schema-Ansicht wird eine Zeile für jede Anwendungskonfiguration angezeigt, die derzeit in der angegebenen oder aktuellen Datenbank definiert ist, in der sich das INFORMATION_SCHEMA befindet.
APPLICATION_CONFIGURATION_VALUE_HISTORY: Gibt den Werteverlauf für eine Konfiguration zurück.

Ansichten des Account Usage-Schemas¶

Ansicht APPLICATION_CONFIGURATIONS: In dieser Account Usage-Ansicht wird für jede Anwendungskonfiguration im Konto eine Zeile angezeigt.
Ansicht APPLICATION_CONFIGURATION_VALUE_HISTORY: Diese Account Usage-Ansicht zeigt den Verlauf der Werte für eine Konfiguration an.

Callbacks¶

Wenn sich ein Konfigurationswert ändert, kann das Snowflake Native App Framework Lebenszyklus-Callbacks aufrufen, die in der Manifest-Datei der App registriert sind. Mit diesen Callbacks kann die App Konfigurationsänderungen validieren, sich darauf vorbereiten oder darauf reagieren. Ein typischer Anwendungsfall bei der Konfiguration der Kommunikation zwischen Apps ist die Verwendung des Callbacks before_configuration_change, um automatisch eine Verbindungsspezifikation zu erstellen oder zu aktualisieren, wenn der Verbrauchende den Namen der Server-App festlegt. Dadurch wird vermieden, dass der Verbrauchenden nach dem Festlegen des Konfigurationswerts zusätzliche manuelle Schritte ausführen muss. Weitere Informationen zur Kommunikation zwischen Apps finden Sie unter Kommunikation zwischen Apps.

Die folgenden Konfigurations-Callbacks sind verfügbar:

validate_configuration_change: Ein synchroner Callback, der als Teil des ALTER APPLICATION SET CONFIGURATION VALUE-Befehls aufgerufen wird. Ermöglicht der App eine kundenspezifische Validierung des angegebenen Wertes. Wenn der Callback einen Fehler zurückgibt, schlägt der Befehl fehl und der neue Wert wird nicht festgelegt.
before_configuration_change: Ein synchroner Callback, der als Teil des ALTER APPLICATION SET CONFIGURATION VALUE- und des ALTER APPLICATION UNSET CONFIGURATION-Befehls aufgerufen wird. Ermöglicht es der App, Vorgänge auf der Grundlage des Konfigurationswertes auszuführen, bevor dieser gespeichert wird.
after_configuration_change: Ein asynchroner Callback, der nach Abschluss des ALTER APPLICATION SET CONFIGURATION VALUE- oder ALTER APPLICATION UNSET CONFIGURATION-Befehls aufgerufen wird. Ermöglicht es der App, auf die Änderung zu reagieren, z. B. zur Benachrichtigung oder zur Nachverfolgung.

Vollständige Callback-Signaturen und Rückgabewerte finden Sie unter:doc:/developer-guide/native-apps/callbacks.

Using the Permission SDK with application configurations¶

If your app includes a Streamlit frontend, you can use the Python Permission SDK to prompt consumers to review and set values for configurations. The SDK provides the following functions for working with application configurations:

get_application_configurations(): Returns all configurations defined for the app. This is equivalent to running SHOW CONFIGURATIONS.
request_application_configuration_value(): Opens a dialog in the Streamlit app that allows the consumer to review and set values for application configurations.
request_application_connection_review(): Opens a dialog for the consumer to approve an application connection for inter-app communication.

For more information, see the Permission SDK reference.