Multi-step API Variabelen

Om aan de slag te gaan met variabelen raden we aan het artikel Multi-step API Response te lezen voor een overzicht van de belangrijkste functies en features.

In dit artikel worden de verschillende types variabelen beschreven die u kunt gebruiken om waarden uit de API-response vast te leggen en op te slaan.

Variabelen

In een multi-step API-set-up worden variabelen gebruikt om waarden uit HTTP-responses te extraheren en deze tijdelijk op te slaan voor later gebruik.

Stel u een scenario voor waarin u een Product-ID of API-key heeft die in uw hele API-scenario moet worden gebruikt. Mogelijk heeft u ook andere waarden, zoals een domein voor elke API, die u één keer wilt definiëren en in meerdere stappen wilt hergebruiken. In dit geval kunt u een variabele creëren met de naam BaseUrl met de waarde https://test.yourapi.com. Verwijs vervolgens naar deze variabele in uw API-URL’s, bijvoorbeeld: {{BaseUrl}}/UserService/GetUserInfo of {{BaseUrl}}/UserService/GetProductInfo. Door deze variabele te definiëren, kunt u eenvoudig schakelen tussen omgevingen, zoals staging en production, door de variabele bij te werken in plaats van elke stap afzonderlijk te wijzigen.

In dergelijke scenario’s kunt u met variabelen:

• Informatie uit één HTTP-response extraheren en die specifieke waarde gebruiken om de volgende HTTP-request te bouwen.
• Definieer eenmaal een waarde en hergebruik deze in meerdere stappen in het hele API-scenario.
• Werk de waarde van een variabele op één plaats bij en laat de wijziging automatisch doorvoeren in volgende stappen.

Alle variabelen die in een stap zijn gedefinieerd, worden geëvalueerd nadat de HTTP-request is uitgevoerd en de response is verwerkt. Als een variabele al bestond, via een eerdere stap of omdat u deze heeft voorgedefinieerd, wordt de bestaande waarde op dat moment overschreven.

Anders wordt er een nieuwe variabele gecreëerd en toegevoegd aan de lijst met variabelen. Deze lijst met variabelen en de bijbehorende waarden worden vervolgens meegenomen naar de volgende stap. Variabelen kunnen zo vaak als nodig is worden gecreëerd en hergebruikt.

Variabelen definiëren

In het onderstaande voorbeeld worden twee variabelen gedefinieerd om de productprijs en product-ID uit de response op te slaan. Vergelijkbaar met het patroon dat wordt gebruikt om assertions te definiëren, worden variabelen gedefinieerd met behulp van drie velden: source property variable name. Elk veld komt overeen met een specifieke waarde, die laat zien hoe de API-waarden worden opgeslagen en hoe de variabele wordt gecreëerd.

Hieronder vindt u de variabele-velden die u kunt definiëren op basis van uw monitoringbehoeften.

Variable source

Dit veld definieert de oorsprong of de databron die u wilt controleren. Deze kan afkomstig zijn van een Response body als JSON, Response body als tekst of een attribute van een HTTP-response, zoals Statuscode, en nog veel meer. Raadpleeg Sources voor meer informatie.

Variable property

Sommige Source-opties zoals Response body als JSON en Response header vereisen dat u een specifieke inhoudcontrole opgeeft om de response verder te valideren. Als u specifieke data uit de response wilt controleren, moet u de exacte propertywaarde opgeven die geschikt is voor het sourcetype. In het bovenstaande voorbeeld is [0].ProductId de propertywaarde.

Raadpleeg Property voor meer informatie.

Naam van de variabele

Dit veld is de identifier die wordt gebruikt om in elke stap naar de variabele te verwijzen. Gebruik de volgende syntaxis om variabelen te gebruiken: {{VariableName}}.

Als er tijdens de evaluatie van de variabele een probleem optreedt, zoals bij een poging om een waarde te extraheren die niet in de response-inhoud voorkomt, mislukt de stap en wordt er een fout gerapporteerd.

Types variabelen

Er zijn verschillende types variabelen die u kunt creëren, afhankelijk van uw gebruikssituatie.

Voorgedefinieerde variabelen

Onder de stap-editor vindt u een extra gedeelte waar u voorgedefinieerde variabelen kunt specificeren. Deze variabelen zijn direct aan het begin van het volledige API-scenario beschikbaar. Als u een bepaalde waarde meerdere keren wilt gebruiken, kunt u die waarde vooraf definiëren en in verschillende stappen gebruiken.

Zoals in de afbeelding te zien is, kunt u de variabele {{BaseUrl}} gebruiken om verschillende eindpunten voor elke stap te targeten, zoals {{BaseUrl}}/Products en {{BaseUrl}}/Status. Raadpleeg het artikel Multi-step API Voorgedefinieerde variabelen voor meer informatie.

Vrije kengetallen variabelen

Wanneer uw multi-step API-controleregel data van uw API’s vastlegt, wilt u mogelijk numerieke waarden volgen die geen deel uitmaken van de standaard meetgegevens. U kunt vrije kengetallen gebruiken die verder gaan dan de response-statuscode, responseduur en andere, om het gedrag van uw API beter te evalueren.

Met vrije kengetal-variabelen kunt u een door de gebruiker gedefinieerde variabele maken om numerieke data op te slaan die uit de response van de API zijn vastgelegd. Dit is handig wanneer u uw productvoorraden, verkopen en andere gegevens wilt bijhouden.

Raadpleeg het artikel Vrije kengetallen voor meer informatie.

Automatische variabelen

Naast de variabelen die u in uw controleregelset-up definieert, heeft u ook toegang tot een aantal automatische variabelen die we voor u hebben gecreëerd. Deze variabelen zijn al ingesteld om waarden te genereren die u kunt gebruiken in uw HTTP-requests en tijdens de evaluatie van uw HTTP-responses met gebruik van assertions. Enkele voorbeelden van automatische variabelen zijn {{@DateTime(format,offset)}} en {{@RedirectUrl}}.

Raadpleeg het artikel Automatische variabelen voor meer informatie.

Door de gebruiker gedefinieerde functies

In sommige situaties moeten waarden die uit de API-response zijn geëxtraheerd, worden getransformeerd of gemapt aan een bepaald formaat voordat ze kunnen worden gebruikt. Dit is handig wanneer u waarden uit een array van strings wilt extraheren of wanneer u een reguliere expressie wilt gebruiken om de bestandsnaam uit een volledig pad op te halen. Met Uptrends kunt u door de gebruiker gedefinieerde functies instellen, die waarden van variabelen uit een vorige stap of een systeemvariabele naar een nieuwe waarde kunnen omzetten.

Raadpleeg Door de gebruiker gedefinieerde functies voor meer informatie.

Variabelen in andere stappen gebruiken

Nadat een variabele succesvol is opgehaald en geëvalueerd, kan de waarde ervan worden hergebruikt in de requestdefinitie van volgende stappen en in assertions. U kunt naar een variabele verwijzen door de variabelenaam tussen dubbele accolades te plaatsen: {{variable-name}}.

De volgende voorbeelden laten zien hoe u in verschillende gebruiksscenario’s naar een variabele kunt verwijzen:

• In de URL van een stap: https://myapi.customer.com/ProductInfo/{{ProductId}}

• In een Request header: "Authorization": Bearer {{access_token}}

• In een Request Body content: { "ProductId": "{{ProductId}}", "Code": "P123456" }

• In de target value van een assertion. Als u een variabele, {{ProductId}}, heeft gevuld in een vorige stap of als een voorgedefinieerde variabele, kunt u deze gebruiken om de response- en de variabelewaarde te vergelijken:

  Response body als JSON Products[0].Id"/Name/text() Is gelijk aan {{ProductId}}

• In de property-waarde van een assertion. Als u een variabele {{ProductId}} heeft, kunt u naar die variabele verwijzen in een JSON-expressie of XPath-query om de inhoud te selecteren die u wilt verifiëren:

  Response body als XML //Product[@Id="{{ProductId}}"]/Name/text() Is gelijk aan Chocolate chip cookie

Codering van waarden van variabelen

Afhankelijk van waar u uw variabelen gebruikt, is het soms nodig om hun waarden te coderen. Coderen betekent speciale tekens converteren naar een formaat dat geschikt is voor HTTP-requests. Variabelen die in een URL worden gebruikt, moeten meestal worden gecodeerd.

Stel dat u een URL bouwt die een naamparameter gebruikt en u wilt een variabele genaamd CompanyName gebruiken om een waarde voor die parameter op te geven. Zonder rekening te houden met codering, zou u dit als volgt doen:

https://my.api.com/GetCompanyInfo?name={{CompanyName}}

Stel 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 codering toe te passen zou u de niet de juiste waarde aan de server doorgeven.

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. Om een variabele te coderen, gebruikt u de functie {{@UrlEncode(...)}} en plaatst u de volledige variabelenaam tussen haakjes.

In dit geval zou het er als volgt uit moeten zien:

https://my.api.com/GetCompanyInfo?name={{@UrlEncode({{CompanyName}})}}

Als een variabele alleen numerieke waarden en geen speciale tekens bevat, hoeft u de functie @UrlEncode niet te gebruiken. Variabelen die in het veld Request body van een stap worden gebruikt, worden automatisch URL-gecodeerd, zolang de header Content-Type is ingesteld op application/x-www-form-urlencoded. Andere soorten inhoud vereisen meestal geen URL-codering.