Configuration d’application¶

Cette rubrique explique comment une Snowflake Native App peut utiliser des objets de configuration de l’application pour demander une entrée au consommateur.

Configuration d’application : Vue d’ensemble¶

Une configuration d’application est une paire clé-valeur qui fournit un mécanisme de coordination entre une Snowflake Native App et le consommateur. Lorsqu’une Snowflake Native App nécessite une entrée du consommateur, elle définit une clé de configuration ainsi qu’une description expliquant l’objectif de la configuration. Le consommateur fournit ensuite la valeur de cette clé.

La configuration de l’application prend en charge les types suivants :

APPLICATION_NAME: Le consommateur fournit le nom d’une application installée dans le compte consommateur. Ce type est utilisé pour la communication inter-applications.
STRING: Le consommateur fournit une valeur de chaîne arbitraire. Ce type peut être utilisé dans divers cas, par exemple pour fournir des URLs externes, des identifiants de compte ou d’autres paramètres spécifiques à une application.

Le workflow de configuration d’application comprend les étapes suivantes :

L’application crée une définition de configuration à l’aide de ALTER APPLICATION SET CONFIGURATION DEFINITION, en spécifiant le type d’informations nécessaires et les rôles d’application qui ont accès à la configuration.
Le consommateur voit les demandes de configuration entrantes à l’aide de SHOW CONFIGURATIONS ou Snowsight.
Le consommateur fournit la valeur demandée à l’aide de ALTER APPLICATION SET CONFIGURATION VALUE ou Snowsight .
L’application extrait la valeur et l’utilise pour effectuer d’autres opérations, telles que la création d’une spécification d’application pour une connexion.

Le Snowflake Native App Framework fournit des rappels pour informer l’application lorsqu’une valeur de configuration est définie ou modifiée. Pour plus d’informations, voir Rappels de configuration.

Terminologie¶

La configuration de l’application utilise les termes suivants :

Définition de la configuration: Un objet que l’application crée pour demander une information spécifique au consommateur. La définition de la configuration spécifie le type d’informations demandées, une étiquette, une description et les rôles d’application qui ont accès à la configuration.
Valeur de la configuration: La valeur que le consommateur fournit en réponse à une demande de définition de configuration.

Utilisation des configurations¶

Cette section décrit comment créer, afficher et gérer des configurations.

Créer une requête de configuration
Afficher les demandes de configuration
Fournir la valeur de la configuration
Mettre à jour la valeur d’une configuration
Annuler la valeur d’une configuration
Récupérer la valeur d’une configuration

Créer une requête de configuration¶

Pour demander une valeur de configuration au consommateur, l’application crée une définition de configuration dans le script d’installation ou dans le runtime. La définition de la configuration spécifie le type de valeur attendue, une balise et une description qui sont affichées au consommateur, ainsi que les rôles d’application qui peuvent voir la configuration et modifier la valeur.

L’exemple suivant montre comment créer une définition de configuration de type STRING qui demande une URL d’entreprise au consommateur :

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

Les propriétés suivantes contrôlent la manière dont la configuration est affichée et gérée :

LABEL : Le nom affiché au consommateur dans Snowsight.
DESCRIPTION : Une description qui aide le consommateur à comprendre l’objectif de la configuration.
APPLICATION_ROLES : Les rôles de l’application qui peuvent visualiser et définir la valeur de cette configuration. Les rôles de consommateur auxquels l’un des rôles d’application spécifiés est attribué peuvent afficher la configuration et modifier sa valeur.
SENSITIVE : Spécifie si la valeur de la configuration doit être traitée comme sensible. Lorsque définie sur TRUE, la valeur n’est pas affichée dans la sortie de SHOW CONFIGURATIONS. Pour plus d’informations, voir Configurations sensibles.

Afficher les demandes de configuration¶

Une fois qu’une application a créé une demande de configuration, le consommateur peut afficher les demandes en attente à l’aide de SQL ou de Snowsight.

Pour afficher les demandes de configuration et les détails d’une définition de configuration à l’aide de SQL, utilisez les commandes SHOW CONFIGURATIONS et DESCRIBE CONFIGURATION :

SHOW CONFIGURATIONS IN APPLICATION example_app;

DESCRIBE CONFIGURATION company_url IN APPLICATION example_app;

Copy

Fournir la valeur de la configuration¶

Une fois que l’application a créé une demande de configuration, le consommateur fournit la valeur demandée à l’aide de SQL ou de Snowsight.

Pour fournir une valeur à la configuration à l’aide de SQL, utilisez la commande ALTER APPLICATION SET CONFIGURATION VALUE :

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

Copy

Mettre à jour la valeur d’une configuration¶

Vous pouvez mettre à jour la valeur d’une configuration à l’aide de SQL ou de Snowsight.

Pour mettre à jour une valeur de configuration, utilisez la même syntaxe que pour définir la valeur initiale :

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

Copy

Annuler la valeur d’une configuration¶

Vous pouvez annuler la valeur d’une configuration à l’aide de SQL ou de Snowsight.

Pour annuler la valeur d’une configuration à l’aide de SQL, utilisez la commande ALTER APPLICATION UNSET CONFIGURATION :

ALTER APPLICATION <app> UNSET CONFIGURATION <config>;

Copy

Récupérer la valeur d’une configuration¶

En plus de SHOW CONFIGURATIONS ou de DESCRIBE CONFIGURATION, une application peut récupérer la valeur d’une configuration que le consommateur a fournie à l’aide de la fonction get_configuration_value. L’exemple suivant montre comment récupérer la valeur d’une configuration :

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

Copy

Note

Seule l’application peut récupérer la valeur de la configuration à partir du contexte du système. Pour afficher la valeur de la configuration en tant que consommateur, vous pouvez afficher les détails de la configuration en utilisant soit SQL, soit Snowsight. Pour plus d’informations, voir Afficher les demandes de configuration.

Configurations sensibles¶

Lorsqu’une application crée une configuration, elle peut marquer la configuration comme sensible en définissant SENSITIVE = TRUE. Ceci est utile lorsque l’application doit demander des informations sensibles au consommateur, comme un jeton d’accès personnel ou une clé API.

Note

La propriété SENSITIVE n’est prise en charge que pour les configurations de type STRING.

Lorsqu’une configuration est sensible, la valeur fournie par le consommateur est protégée contre les autres utilisateurs et rôles du consommateur. Le Snowflake Native App Framework applique des protections similaires à celles utilisées pour les objets SECRET dans Snowflake :

Une fois que le consommateur a défini une valeur, l’historique des requêtes pour la commande ALTER APPLICATION SET CONFIGURATION VALUE masque cette valeur afin qu’elle ne soit pas exposée à d’autres rôles de consommateurs ou utilisateurs.
La valeur n’est pas affichée dans la sortie des vues SHOW CONFIGURATIONS, DESCRIBE CONFIGURATION, INFORMATION_SCHEMA ou des vues ACCOUNT_USAGE.

L’application qui crée la configuration peut toujours récupérer la valeur fournie par le consommateur, même si la configuration est sensible. Cela est voulu, car le but d’une configuration d’application est que le consommateur fournisse une valeur à l’application.

Modification de la propriété SENSITIVE¶

Une application ne peut pas modifier la propriété SENSITIVE si la configuration a une valeur définie (c’est-à-dire lorsque la configuration n’est pas dans un état PENDING). Cette restriction empêche la valeur du consommateur d’être accidentellement exposée. Si l’application tente de modifier la propriété SENSITIVE alors qu’une valeur est définie, la commande se termine sans erreur mais n’a aucun effet.

Pour modifier la propriété SENSITIVE, le consommateur doit d’abord désactiver la valeur de la configuration à l’aide de ALTER APPLICATION UNSET CONFIGURATION.

Référence SQL¶

Les commandes, fonctions et vues SQL suivantes sont utilisées pour gérer les configurations des applications.

commandes SQL¶

ALTER APPLICATION SET CONFIGURATION DEFINITION : Crée ou met à jour une définition de la configuration de l’application qui demande une valeur au consommateur.
ALTER APPLICATION DROP CONFIGURATION DEFINITION : Supprime une définition de configuration d’application.
ALTER APPLICATION SET CONFIGURATION VALUE : Définit une valeur dans une configuration d’application.
ALTER APPLICATION UNSET CONFIGURATION : Désactive la valeur d’une configuration d’application.
SHOW CONFIGURATIONS : Répertorie toutes les configurations d’application dans une application.
DESCRIBE CONFIGURATION : Décrit les détails d’une configuration d’application.

Fonctions SQL¶

IS_CONFIGURATION_SET (fonction SYS_CONTEXT) : Indique si la configuration possède ou non une valeur définie.
GET_CONFIGURATION_VALUE (fonction SYS_CONTEXT) : Renvoie la valeur actuelle de la configuration.

Vues et fonctions du schéma d’information¶

Vue APPLICATION_CONFIGURATIONS : Cette vue Schéma d’information affiche une ligne pour chaque configuration d’application actuellement définie dans la base de données spécifiée ou actuelle dans laquelle INFORMATION_SCHEMA se trouve.
APPLICATION_CONFIGURATION_VALUE_HISTORY : Renvoie l’historique des valeurs pour une configuration.

Vues du schéma d’utilisation du compte¶

Vue APPLICATION_CONFIGURATIONS : Cette vue Utilisation du compte affiche une ligne pour chaque configuration d’application du compte.
Vue APPLICATION_CONFIGURATION_VALUE_HISTORY : Cette vue Utilisation du compte affiche l’historique des valeurs d’une configuration.

Rappels¶

Lorsqu’une valeur de configuration est modifiée, le Snowflake Native App Framework peut invoquer des rappels de cycle de vie enregistrés dans le fichier manifeste de l’application. Ces rappels permettent à l’application de valider, de se préparer ou de répondre aux changements de configuration. Par exemple, lors de la configuration de la communication inter-applications, un cas d’utilisation courant consiste à utiliser le rappel before_configuration_change pour créer ou mettre à jour automatiquement une spécification de connexion lorsque le consommateur définit le nom de l’application serveur. Cela évite au consommateur d’avoir à effectuer des étapes manuelles supplémentaires après avoir défini la valeur de configuration. Pour plus d’informations sur la communication inter-applications, voir Communication inter-applications.

Les rappels de configuration suivants sont disponibles :

validate_configuration_change: Un rappel synchrone appelé dans le cadre de la commande ALTER APPLICATION SET CONFIGURATION VALUE. Permet à l’application d’effectuer une validation personnalisée sur la valeur fournie. Si le rappel renvoie une erreur, la commande échoue et la nouvelle valeur n’est pas définie.
before_configuration_change: Un rappel synchrone appelé dans le cadre des commandes ALTER APPLICATION SET CONFIGURATION VALUE et ALTER APPLICATION UNSET CONFIGURATION. Permet à l’application d’effectuer des opérations en fonction de la valeur de la configuration avant qu’elle ne soit enregistrée.
after_configuration_change: Un rappel asynchrone appelé après l’exécution des commandes ALTER APPLICATION SET CONFIGURATION VALUE ou ALTER APPLICATION UNSET CONFIGURATION. Permet à l’application de répondre au changement, par exemple à des fins de notification ou de suivi.

Pour obtenir les signatures complètes des rappels et les valeurs de retour, voir Rappels.