Omgevingsvariabelen gebruiken

Doel

Declareer een instelling één keer in je oplossing — een API-adres, een mailbox, een functieschakelaar — en laat Ontwikkeling, Test en Productie die elk op hun eigen manier invullen, zonder de oplossing na elke import te bewerken.

Waarom dit bestaat

Een oplossing die van Ontwikkeling naar Test naar Productie wordt gepromoveerd, hoort dezelfde oplossing te zijn. En toch moet een deel van wat ze doet per omgeving verschillen: de service die ze aanroept, het adres waarvandaan ze verstuurt, of een functie aan staat.

Zonder omgevingsvariabelen zijn er maar twee manieren om dat uit te drukken, en beide zijn slecht. Je kunt na elke import componenten bewerken — waardoor je omgevingen stilletjes uit elkaar groeien, en dat verschil verborgen blijft. Of je kunt de waarde van Ontwikkeling hard coderen en onthouden dat je die moet wijzigen — wat werkt tot de dag dat niemand het meer onthoudt.

Een omgevingsvariabele splitst de instelling in tweeën:

• De declaratie — de naam, het type, de beschrijving en de standaardwaarde. Die hoort bij de oplossing en reist ermee mee.
• De waarde — het antwoord van deze omgeving. Die hoort bij de omgeving en verlaat haar nooit. Exporteren neemt haar niet mee, en importeren overschrijft haar niet.

Vereisten

• Je bent aangemeld als maker, met een oplossing en een omgeving geselecteerd.

Stappen

Een variabele declareren (meestal in Ontwikkeling)

1. Open je oplossing en kies Omgevingsvariabelen in de linkernavigatie.
2. Selecteer Nieuw.
3. Voer een weergavenaam in (bijvoorbeeld Invoice API URL). De logische naam wordt eronder ingevuld met het voorvoegsel van je uitgever — invoice_api_url wordt par_invoice_api_url.
4. Kies een type: Tekst, Getal, Booleaans (true/false) of JSON. Elke waarde die voor de variabele wordt ingesteld, wordt daaraan getoetst, in welke omgeving die ook wordt getypt.
5. Schrijf een beschrijving. Die verdient hier meer moeite dan bij de meeste dingen die je bouwt: wie de waarde in Productie instelt, ben vaak niet jij, en een kale naam zegt zelden hoe een juiste waarde eruitziet.
6. Voer desgewenst een standaardwaarde in — die wordt gebruikt overal waar een omgeving niets heeft ingesteld. Laat haar leeg voor iets zonder zinnige standaard (een geheim, een adres per klant), zodat een niet-ingestelde variabele zichtbaar niet is ingesteld in plaats van stilletjes fout.
7. Selecteer Opslaan.

De waarde van deze omgeving instellen (in elke omgeving)

1. Open Omgevingsvariabelen en selecteer de rij van de variabele (of selecteer hem en kies Waarde instellen).
2. Voer de waarde in die deze omgeving moet gebruiken en selecteer Opslaan.
3. Wil je terug naar de gedeclareerde standaardwaarde, maak het vak dan leeg en sla op. Dat is een bewuste beslissing, en het is de enige weg terug zodra er een waarde is ingesteld.

De kolom Werkelijke waarde vertelt je in welke van drie toestanden elke variabele zich bevindt:

Er staat	Het betekent
een waarde	deze omgeving heeft haar ingesteld
een waarde, en dan (standaardwaarde gebruikt)	hier is niets ingesteld; de standaardwaarde van de oplossing geldt
Niet ingesteld	geen van beide — niets beantwoordt deze variabele hier, en alles wat haar leest, vindt niets

Niet ingesteld is de toestand die je vóór de livegang moet oplossen.

Een variabele lezen vanuit een plug-instap

In een BS Lang-plug-instap geeft getEnvironmentVariable("par_invoice_api_url") de werkelijke waarde terug voor de omgeving waarin de schrijfactie plaatsvindt. Zo kan één script overal kloppen: het noemt de instelling in plaats van het adres.

Een niet-ingestelde variabele leest als een lege tekenreeks, dus een script dat er een nodig heeft, moet dat zeggen in plaats van door te gaan:

if (getEnvironmentVariable("par_invoice_api_url") == "") {
    throwValidationError("The invoice API URL is not configured in this environment.");
}

Een ontbrekende instelling is een configuratiefout, geen waarde — hier luid falen is veel vriendelijker dan later op een duistere manier falen.

Wat er achter de schermen gebeurt

De declaratie is een oplossingscomponent zoals een tabel of een keuzeset: ze wordt gevalideerd tegen een gepubliceerd schema, ze hoort in de naamruimte van je uitgever, en ze reist mee in het oplossingspakket. De waarde wordt bij de omgeving opgeslagen en wordt nooit in een pakket geschreven.

Bij een import in een andere omgeving:

• komt een variabele die voor het eerst binnenkomt aan met haar gedeclareerde standaardwaarde en zonder waarde;
• wordt bij een variabele die er al is de declaratie bijgewerkt — een hernoemd label, een gewijzigde standaardwaarde, een verbeterde beschrijving — en blijft de waarde precies zoals die omgeving haar heeft ingesteld.

Die tweede regel is de reden dat de hele functie bestaat. Een oplossing naar Productie promoveren mag Productie nooit stilletjes naar het endpoint van Ontwikkeling laten wijzen.

De installatie van de oplossing ongedaan maken, verwijdert haar variabelen, inclusief de waarden — op dat moment valt er niets meer te configureren.

Problemen oplossen

• "'…' is not a valid Number value." (of Boolean/JSON) — de waarde past niet bij het gedeclareerde type. Dat wordt bewust gecontroleerd waar je haar typt, en niet waar ze later wordt gelezen: een script dat het ontdekt, zou ver van de fout mislukken, en waarschijnlijk in Productie.
• Ik heb het type gewijzigd en mijn waarde is verdwenen. — de waarde paste niet meer bij het nieuwe type, dus ze is gewist in plaats van bewaard als iets wat niets kan lezen. De variabele valt terug op haar standaardwaarde en leest als niet ingesteld, wat zichtbaar is. Stel haar opnieuw in.
• Ik heb de oplossing geïmporteerd en Productie toont nog de oude waarde. — dat is het bedoelde gedrag: een import overschrijft nooit de eigen waarde van een omgeving. Wijzig haar in de lade Waarde instellen in Productie.
• Mijn standaardwaarde is in Productie aangekomen, maar mijn waarde uit Ontwikkeling niet. — ook bedoeld. De standaardwaarde maakt deel uit van de declaratie en reist mee; de waarde is van de omgeving en reist niet mee.
• Een script leest een lege tekenreeks. — de variabele is gedeclareerd maar in deze omgeving niet ingesteld, of de naam is verkeerd gespeld. Controleer de kolom Werkelijke waarde; Niet ingesteld onderscheidt die twee van een typfout, want die verschijnt helemaal niet in de lijst.
• "An environment variable named … already exists in this environment." — logische namen zijn uniek binnen een omgeving. Kies een andere, of bewerk de bestaande.

Gerelateerde scenario's

• Een oplossing maken.
• Een oplossing exporteren.
• Een component aan een oplossing toevoegen.