Utiliser des variables d’environnement
Objectif
Déclarer un paramètre une seule fois dans votre solution — une adresse d’API, une boîte aux lettres, un commutateur de fonctionnalité — et laisser Dev, Test et Production y répondre chacun à sa façon, sans modifier la solution après chaque importation.
Pourquoi cela existe
Une solution promue de Dev vers Test puis vers Production est censée être la même solution. Et pourtant, une partie de ce qu’elle fait doit varier d’un environnement à l’autre : le service qu’elle appelle, l’adresse depuis laquelle elle envoie, l’activation ou non d’une fonctionnalité.
Sans variables d’environnement, il n’existe que deux façons de l’exprimer, et toutes deux sont mauvaises. Vous pouvez modifier des composants après chaque importation — ce qui fait diverger vos environnements sans bruit, et masque cette divergence. Ou vous pouvez coder en dur la valeur de Dev en pensant à la changer — ce qui fonctionne jusqu’au jour où personne n’y pense.
Une variable d’environnement scinde le paramètre en deux :
- La déclaration — son nom, son type, sa description et sa valeur par défaut. Elle appartient à la solution et voyage avec elle.
- La valeur — la réponse de cet environnement. Elle appartient à l’environnement et ne le quitte jamais. Exporter la solution ne l’emporte pas, et importer la solution ne l’écrase pas.
Prérequis
- Vous êtes connecté en tant que créateur, avec une solution et un environnement sélectionnés.
Étapes
Déclarer une variable (généralement en Dev)
- Ouvrez votre solution et choisissez Variables d’environnement dans la navigation de gauche.
- Sélectionnez Nouveau.
- Saisissez un nom d’affichage (par exemple
Invoice API URL). Le nom logique se remplit en dessous avec le préfixe de votre éditeur appliqué —invoice_api_urldevientpar_invoice_api_url. - Choisissez un type : Texte, Nombre, Booléen (
true/false) ou JSON. Toute valeur définie pour la variable est contrôlée par rapport à ce type, dans l’environnement où elle est saisie. - Rédigez une description. Elle mérite ici plus d’efforts que la plupart de ce que vous construisez : la personne qui définit la valeur en Production n’est souvent pas vous, et un simple nom dit rarement à quoi ressemble une valeur correcte.
- Saisissez éventuellement une valeur par défaut — celle qui est utilisée partout où un environnement n’en a défini aucune. Laissez-la vide pour ce qui n’a pas de valeur par défaut raisonnable (un secret, une adresse propre à un client), afin qu’une variable non définie soit visiblement non définie plutôt que discrètement fausse.
- Sélectionnez Enregistrer.
Définir la valeur de cet environnement (dans chaque environnement)
- Ouvrez Variables d’environnement et sélectionnez la ligne de la variable (ou sélectionnez-la et choisissez Définir la valeur).
- Saisissez la valeur que cet environnement doit utiliser, puis sélectionnez Enregistrer.
- Pour revenir à la valeur par défaut déclarée, videz la zone et enregistrez. C’est une décision, et c’est le seul moyen de revenir en arrière une fois qu’une valeur a été définie.
La colonne Valeur effective vous indique dans lequel des trois états se trouve chaque variable :
| Elle affiche | Cela signifie |
|---|---|
| une valeur | cet environnement l’a définie |
| une valeur, suivie de (valeur par défaut utilisée) | rien n’a été défini ici ; la valeur par défaut de la solution s’applique |
| Non définie | ni l’un ni l’autre — rien ne répond à cette variable ici, et tout ce qui la lit ne trouvera rien |
Non définie est l’état à éliminer avant la mise en production.
Lire une variable depuis une étape de plug-in
Dans une étape de plug-in BS Lang, getEnvironmentVariable("par_invoice_api_url") renvoie la
valeur effective pour l’environnement dans lequel l’écriture a lieu. C’est ce qui permet à un même
script d’être correct partout : il nomme le paramètre plutôt que l’adresse.
Une variable non définie se lit comme une chaîne vide ; un script qui en a besoin doit donc le dire plutôt que de poursuivre :
if (getEnvironmentVariable("par_invoice_api_url") == "") {
throwValidationError("The invoice API URL is not configured in this environment.");
}
Un paramètre manquant est une erreur de configuration, pas une valeur — échouer bruyamment ici est bien plus charitable qu’échouer obscurément plus tard.
Ce qui se passe en coulisses
La déclaration est un composant de solution comme une table ou un groupe d’options : elle est validée par rapport à un schéma publié, elle appartient à l’espace de noms de votre éditeur, et elle voyage dans le paquet de la solution. La valeur est stockée au niveau de l’environnement et n’est jamais écrite dans un paquet.
Lors de l’importation dans un autre environnement :
- une variable qui arrive pour la première fois est créée avec sa valeur par défaut déclarée et sans valeur ;
- une variable déjà présente voit sa déclaration mise à jour — un libellé renommé, une valeur par défaut modifiée, une description corrigée — et sa valeur laissée exactement telle que cet environnement l’avait définie.
C’est pour cette seconde règle que toute la fonctionnalité existe. Promouvoir une solution en Production ne doit jamais rediriger silencieusement la Production vers le point de terminaison de Dev.
La désinstallation de la solution retire ses variables, valeurs comprises — à ce stade, il n’y a plus rien à configurer.
Dépannage
- « '…' is not a valid Number value. » (ou Boolean/JSON) — la valeur ne correspond pas au type déclaré. Elle est contrôlée à l’endroit où vous la saisissez, volontairement, plutôt qu’à l’endroit où elle est lue plus tard : un script qui la découvrirait échouerait loin de l’erreur, et probablement en Production.
- J’ai changé le type et ma valeur a disparu. — la valeur ne correspondait plus au nouveau type ; elle a donc été effacée plutôt que conservée sous une forme que rien ne peut lire. La variable revient à sa valeur par défaut et apparaît comme non définie, ce qui est visible. Définissez-la à nouveau.
- J’ai importé la solution et la Production affiche toujours l’ancienne valeur. — c’est le comportement prévu : une importation n’écrase jamais la valeur propre à un environnement. Modifiez-la dans le tiroir Définir la valeur en Production.
- Ma valeur par défaut a atteint la Production, mais pas ma valeur de Dev. — c’est également voulu. La valeur par défaut fait partie de la déclaration et voyage ; la valeur appartient à l’environnement et ne voyage pas.
- Un script lit une chaîne vide. — la variable est déclarée mais non définie dans cet environnement, ou son nom est mal orthographié. Vérifiez la colonne Valeur effective : Non définie distingue le premier cas d’une faute de frappe, qui n’apparaîtra pas du tout dans la liste.
- « An environment variable named … already exists in this environment. » — les noms logiques sont uniques au sein d’un environnement. Choisissez-en un autre, ou modifiez la variable existante.