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.

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;

Copy

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: Gibt an, ob der Konfigurationswert als sensibel behandelt werden soll. Ist dies auf TRUE gesetzt, wird der Wert in der Ausgabe von SHOW CONFIGURATIONS nicht angezeigt. Weitere Informationen dazu finden Sie unter Sensible Konfigurationen.

Anzeigen von Konfigurationsanforderungen¶

Nachdem eine App eine Konfigurationsanforderung erstellt hat, kann der Verbrauchende ausstehende Anforderungen mithilfe von SQL oder|sf-web-interface| anzeigen.

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;

Copy

Angeben des Konfigurationswerts¶

Nachdem eine App eine Konfigurationsanforderung erstellt hat, stellt der Verbrauchende den anforderten Wert mithilfe von SQL oder Snowsight bereit.

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

Copy

Aktualisieren des Werts einer Konfiguration¶

Sie können den Wert einer Konfiguration mit mithilfe von SQL oder Snowsight aktualisieren.

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

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

Copy

Zurücksetzen des Werts einer Konfiguration¶

Sie können den Wert einer Konfiguration mithilfe von SQL oder Snowsight zurücksetzen.

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

ALTER APPLICATION <app> UNSET CONFIGURATION <config>;

Copy

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>')

Copy

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.