In een multi-step API monitoring set-up worden variabelen meestal gebruikt om waarden uit uw HTTP-responses te extraheren en ze tijdelijk op te slaan, zodat u ze opnieuw kunt gebruiken in een latere stap. Hiermee kunt u in feite stappen aan elkaar koppelen: elke keer dat u een stukje informatie uit een HTTP-respons wilt halen en die informatie wilt gebruiken om de volgende HTTP-request uit te voeren, hebt u een variabele nodig. Simpel gezegd: stap 1 ontvangt een waarde van uw server en slaat deze op in een variabele. Stap 2 neemt dan de waarde die we zojuist hebben opgeslagen en gebruikt deze om een nieuwe request op te bouwen. U kunt zoveel variabelen gebruiken als u wilt en ze in zoveel stappen gebruiken als u nodig hebt.
Een tweede reden om variabelen te gebruiken, is om bepaalde waarden slechts eenmaal te definiëren en ze in verschillende stappen opnieuw te gebruiken. Normaal gesproken voegt u deze waarden toe in het gedeelte Voorgedefinieerde variabelen: die variabelen zijn in elke stap beschikbaar gedurende het gehele meerstapsscenario. Zie het gedeelte Voorgedefinieerde variabelen voor meer informatie.
Alle variabelen die u in een stap definieert worden geëvalueerd zodra de HTTP-request is uitgevoerd en de respons is verwerkt. Op dat moment, als een variabele al bestond (ofwel door een vorige stap, of omdat u deze vooraf hebt gedefinieerd), wordt de bestaande waarde ervan overschreven. Anders wordt een nieuwe variabele gemaakt en aan de lijst toegevoegd. Deze lijst met variabelen en bijbehorende waarden wordt vervolgens meegenomen naar de volgende stap.
Variabelen definiëren
Als u variabelen wilt gebruiken, moet u ons vertellen welke waarde we in die variabele moeten opslaan. Vergelijkbaar met het patroon dat wordt gebruikt om assertions te definiëren, worden variabelen op de volgende manier gedefinieerd:
Source property variable name
bijvoorbeeld:
Response body as JSON access_token access_token
- De variable source: dit veld definieert welk kenmerk van de HTTP respons u wilt extraheren. Alle beschikbare opties worden in dit artikel beschreven.
- De variable property: sommige source-opties (met name de inhoudextractie en header-gerelateerde opties) vereisen dat u verder specificeert welke inhoud of header moet worden gecontroleerd. Dit wordt uitgebreider uitgelegd voor elk geschikt sourcetype.
- De variable name: dit is de identifier die in de volgende stappen zal worden gebruikt om terug te verwijzen naar deze variabele, met behulp van een speciale notatie.
Als er een probleem optreedt tijdens de evaluatie van een variabele (bijvoorbeeld omdat u probeert een waarde te extraheren die niet aanwezig is in de responsinhoud), zal de stap mislukken en een fout worden gerapporteerd.
Verwijzen naar variabelen in andere stappen
Nadat een variabele met succes is geëvalueerd, kan zijn waarde opnieuw worden gebruikt in de requestdefinitie van volgende stappen en binnen assertions (responsinhoud-controles). Verwijs altijd naar een variabele door de variabelenaam tussen dubbele accolades te plaatsen: {{variable-name}}.
-
In de URL van een stap:
https://myapi.customer.com/ProductInfo/{{ProductId}} -
In een Request header:
"Authorization": Bearer {{access_token}} -
In Request Body inhoud:
{ "ProductId": "{{ProductId}}", "Code": "P123456" } -
In de doelwaarde van een assertion. Hebt u bijvoorbeeld een variabele {{ProductId}} (in een vorige stap ingevuld, of als een voorgedefinieerde variabele), dan kunt u die gebruiken om te verifiëren dat een respons de feitelijke waarde in die variabele bevat:
Response body as JSONProducts[0].IdEquals{{ProductId}} -
In de propertywaarde van een assertion. Als u een variabele {{ProductId}} hebt, kunt u naar die variabele verwijzen in een JSON expression of XPath query om de inhoud te selecteren die u wilt verifiëren:
Response body as XML//Product[@Id="{{ProductId}}"]/Name/text()EqualsChocolate chip cookie
Voorgedefinieerde variabelen
Onder de stap-editor vindt u een extra gedeelte waar u meer variabelen kunt specificeren. Deze variabelen zijn beschikbaar aan het begin van het hele scenario. Als u een bepaalde waarde meerdere keren nodig heeft, kunt u die waarde van tevoren definiëren en in verschillende stappen gebruiken. Dit kan een product-ID zijn die u in uw scenario wilt gebruiken, een API-key of andere speciale waarden die uw API nodig heeft. Een speciaal geval is het gebruik van een variabele die de domeinnaam voor elke API bevat. Door die variabele als onderdeel van elke URL te gebruiken, hoeft u deze niet in elke stap te herhalen, waardoor u deze heel gemakkelijk voor het hele scenario kunt wijzigen. Om een voorgedefinieerde variabele toe te voegen klikt u op in de controleregelinstellingen, onder Voorgedefinieerde variabelen. Maak dan een variabele genaamd BaseUrl met de waarde https://test.yourapi.com. Door een verwijzing naar die variabele te gebruiken, kan de URL voor elke API-stap de vorm {{BaseURL}}/UserService/GetUserInfo hebben. Met deze aanpak kunt u uw meerstapsscenario zo wijzigen dat die naar een andere omgeving verwijst (bijvoorbeeld een staging-omgeving versus een production-omgeving), zonder elke stap te hoeven wijzigen.
Voorgedefinieerde variabelen kunnen ook worden gebruikt als op enig moment tijdens het uitvoeren van de controleregel gevoelige gegevens moeten worden verzonden. Als uw API bijvoorbeeld geauthenticeerde toegang vereist, moet u mogelijk inloggen of een toegangstoken ophalen door inloggegevens toe te voegen aan een van uw requests. Gevoelige gegevens worden opgeslagen in de vault. Om vault-inloggegevens in te stellen voor gebruik in een Multi-Step API-controleregel doet u het volgende:
-
Zorg er eerst voor dat u de inloggegevens heeft toegevoegd aan de vault.
-
Creëer de voorgedefinieerde variabele zoals u dat normaal zou doen, zoals hierboven beschreven.
-
Om te verwijzen naar een vault-item klikt u op het pictogram […] onder Waarde, waardoor de waardekiezer wordt geopend.
-
Selecteer de juiste set inloggegevens in de lijst en selecteer de waarde in het veld gebruikersnaam of het veld wachtwoord.
-
Geef uw variabele een geschikte Naam. Naar deze naam gaat u verwijzen tijdens het uitvoeren van de controleregel, zoals beschreven in dit artikel. In het onderstaande voorbeeld verwijzen we naar de variabele examplePassword als
{{examplePassword}}.
In de controleregel-log worden waarden uit het veld wachtwoord in het vault-item weergegeven met sterretjes om de gevoelige gegevens verborgen te houden.
Codering van waarden van variabelen
Afhankelijk van waar u uw variabelen gebruikt, is het soms nodig om de waarden te coderen. Codering betekent dat we speciale tekens converteren naar een formaat dat geschikt is voor een HTTP-request. Doorgaans moeten variabelen die in een URL worden gebruikt, worden gecodeerd. Stel dat u een URL bouwt waarbij een naamparameter wordt gebruikt en dat u een variabele met de naam CompanyName wilt gebruiken om een waarde voor die parameter te specificeren. Zonder rekening te houden met codering, zou u die als volgt gebruiken:
https://my.api.com/GetCompanyInfo?name={{CompanyName}}
Stel nu dat de variabele CompanyName de waarde Ben & Jerry's. bevat. Die waarde bevat spaties en een ampersand-teken (&), die een speciale betekenis hebben in een URL. Zonder enige codering toe te passen, komt de correcte waarde niet op de server terecht. Als u eerst codering toepast, wordt de waarde geconverteerd naar Ben\+%26\+Jerry's, die door de server wordt geïnterpreteerd als de oorspronkelijke waarde. Gebruik de functie {{@UrlEncode(…)}} om codering toe te passen op uw variabelen. Vermeld binnen de haakjes de volledige naam van de variabele, bijvoorbeeld {{CompanyName}}. Gebruikt in een URL ziet het er als volgt uit:
https://my.api.com/GetCompanyInfo?name={{@UrlEncode({{CompanyName}})}}
Als een variabele nooit speciale tekens bevat (bijvoorbeeld alleen numerieke waarden), is het niet nodig om de @UrlEncode-functie te gebruiken. We URL-coderen automatisch variabelen die worden gebruikt in het veld Request Body van een stap, maar alleen als er een Content-Type header is gespecificeerd met de waarde application/x-www-form-urlencoded. Andere soorten inhoud vereisen meestal geen URL-codering.
Automatische variabelen
Afgezien van de variabelen die u in uw controleregelinstellingen definieert, hebt u ook toegang tot een aantal automatische variabelen die wij voor u maken. De meeste daarvan zijn feitelijk functies die een waarde genereren die u kunt gebruiken in uw HTTP requests en tijdens de evaluatie van uw HTTP responses met behulp van assertions. Wilt u automatische variabelen gebruiken in uw Multi-Step API monitoring, raadpleeg dan onze volledige lijst met beschikbare automatische variabelen.
Door de gebruiker gedefinieerde functies
In bepaalde gevallen moeten de waarden van de inkomende data getransformeerd of gemapt worden om ze inzichtelijker te maken. Met Uptrends kunt u gebruiker-gedefinieerde functies instellen die kunnen worden gebruikt om waarden van variabelen (uit een vorige stap of een systeemvariabele uit Uptrends) om te zetten naar een nieuwe waarde. Meer informatie over het instellen en gebruiken van door de gebruiker gedefinieerde functies vindt u in dit Knowledge Base-artikel.