Multi-step API aangepaste scripting

Het controleregeltype API heeft veel handige ingebouwde functies: controles uitvoeren (met behulp van Assertions), tijdelijk waarden opslaan voor later hergebruik (met behulp van Variabelen), waarden transformeren (met behulp van Systeemfuncties) en zelfs uw eigen logica toevoegen (met behulp van Door de gebruiker gedefinieerde functies). Deze functies maken de API-controleregel tot een krachtige, geen codering vereist-oplossing.

Hoewel u met een no-code-benadering een heel eind komt bij het bouwen van nuttige monitoring-set-ups, kunt u hiermee misschien niet altijd zo diep gaan als u wilt. Met name voor het uitvoeren van diepgaande functionele correctheidstests moet u mogelijk aangepaste logica toevoegen die nu eenmaal niet kan worden uitgedrukt in een op gebruikersinterface gebaseerde configuratie. U heeft een scripttaal nodig om echt expressief en beschrijvend te zijn over wat u van uw API’s verwacht. Met het API-controleregeltype kunt u dit doen!

U kunt zelfs klassieke no-code-functies zoals Assertions en Variabelen combineren met hun scripting-tegenhangers. Als u bestaande API-controleregels heeft die Assertions en Variabelen gebruiken, maar u van scripting wilt profiteren, hoeft u uw controleregels niet helemaal opnieuw te schrijven. U kunt beginnen met het toevoegen van kleine stukjes script en deze naast uw bestaande controles en variabelen laten werken.

Twee scripteditors: Pre-Request en Post-Response

Een API-controleregel kan één stap hebben, of meerdere stappen achter elkaar uitvoeren. Maar elke stap (met uitzondering van Wachtstappen) bestaat uit een voorbereidingsgedeelte dat de HTTP-request voor die stap instelt en een verificatiegedeelte dat de HTTP-response verwerkt die terugkomt van de API. Beide delen kunnen hun eigen script hebben:

Het Pre-Request-script wordt uitgevoerd voordat de HTTP request volledig is opgebouwd en uitgevoerd.
Daarom is het Pre-Request-script erg handig voor het voorbereiden en berekenen van waarden die u in de request wilt opnemen, zoals URL-parameters, request headers of tekstinhoud.
Het Post-Response-script wordt uitgevoerd nadat de bijbehorende HTTP response volledig is ontvangen en nadat alle Assertions en Variabelen in het tabblad Response zijn verwerkt.
Het Post-Response-script is waar u uw aangepaste logica uitvoert om response headers te controleren, de volledigheid en consistentie van uw inhoud te controleren en die inhoud te gebruiken om eventuele volgende stappen voor te bereiden.

Zoals weergegeven in het volgende screenshot, hebben zowel de Pre-Request- als Post-Response-scripts hun eigen tabblad in de API-controleregeleditor. Elk heeft zijn eigen code-editor met regelnummering, codemarkering en code-aanvulling, en een snippetpaneel ernaast. Klik op een van de snippets om handige codefragmenten in het codevenster in te voegen om u op weg te helpen.

Tabbladen Aangepaste scripting De tabbladen Request, Pre-Request, Response en Post-Response in stap 1

Javascript met monitoring-extensies

Met de Pre-Request- en Post-Response-scripts in de API-controleregelconfiguratie kunt u Javascript-code uitvoeren. Naast het volledige scala aan mogelijkheden dat standaard Javascript biedt, zijn er speciale functies beschikbaar om toegang te krijgen tot de data die relevant zijn voor het instellen van requests (tijdens Pre-Request) en verwerking van de responses (tijdens Post-Response), voor het uitvoeren van tests op die data, voor het uitvoeren van log statements (voor foutopsporing of informatieve doeleinden) en voor het opslaan van berekende data als custom metrics.

Deze speciale functies zijn beschikbaar via een speciaal object genaamd ut. In de onderstaande secties wordt een volledige beschrijving gegeven van elke beschikbare functie en elk kenmerk in het ut-object. Maar we kijken eerst naar de algehele structuur:

ut.request en ut.response geven toegang tot de API-request- en API-response-objecten – de belangrijkste objecten in elke stap.
ut.variables is de verzameling variabelen die u in het hele API-scenario kunt gebruiken, in alle stappen. U gebruikt deze om waarden van de ene stap naar de volgende door te geven. Als u voorgedefinieerde variabelen creëert, worden deze toegevoegd aan deze variabelenverzameling. Alle klassieke (geen-code)-variabelen die u op het tabblad Response gebruikt, communiceren ook met deze variabelenverzameling.
ut.log() is een helperfunctie die tekst naar een logvenster stuurt. Het is handig om tijdelijk tekst en waarden naar het log te schrijven terwijl u uw scripts schrijft of debugt.
ut.test() is de hoofdfunctie voor het vastleggen van testuitvoer. Alle testuitvoer die u definieert binnen elke ut.test()-call, wordt vastgelegd en vermeld als een Assertion-resultaat, direct naast alle klassieke (geen-code) assertions die u definieert.
ut.customMetrics is een verzameling die u tijdens uw scripts kunt vullen met numerieke waarden – direct afkomstig van een API response of een berekende waarde – die u wilt vastleggen als uw eigen metric. Deze waarde wordt weergegeven in de details van de monitorcontrole voor elke meting en kan ook worden vermeld en in kaart worden gebracht in dashboards.

Request

Attributes die de definitie van de API request in de huidige stap beschrijven.

Attributes van ut.request:

.url (de url van de request ophalen of instellen)
.method (de HTTP-methode van de request ophalen of instellen, bijvoorbeeld GET, POST, etc.)
.body (een onbewerkte tekstversie van de request body ophalen of instellen)

Request headers

Functies van ut.request.headers:

.has(header): retourneert of de header bestaat
.get(header): retourneert de waarde van de header of een lege string als deze niet bestaat
.add(header, value): voegt de header toe met de gespecificeerde waarde

Response

Attributes van ut.request:

.code (haalt de numerieke HTTP response-statuscode op, bijvoorbeeld 200)
.status (haalt de HTTP statusbeschrijving op, bijvoorbeeld OK)
.responseSize (haalt de omvang van de response op in bytes)

Functies van ut.request:

.text():retourneert een onbewerkte tekstversie van de response body
.json(): retourneert een object door de responsetekst te parseren als JSON

Response headers

Functies van ut.response.headers:

.has(header): retourneert of de header bestaat
.get(header): retourneert de waarde van de header of een lege string als deze niet bestaat

Variabelen

Functies van ut.variables:

.has(key): retourneert of deze variabele bestaat
.get(key): retourneert de waarde van de variabele of een lege string als deze niet bestaat
.set(key, value): creëert indien nodig de variabele en slaat de gespecificeerde waarde op

Custom metrics

Functies van ut.customMetrics:

.get(key): retourneert de waarde van de custom metric of een lege string als deze niet bestaat
.set(key, value): slaat de waarde van de custom metric op

Log

ut.log(text): geeft de gespecifieerde log door naar de console-log: de Request-log als deze wordt uitgevoerd in het Pre-Request-script; de Response-log als deze wordt uitgevoerd in het Post-Response-script.

Test/Assert

We ondersteunen de Expect- en Should-interfaces van Chai JS, zie Chai - Should en Chai - Expect om te lezen hoe u verschillende waardetests en vergelijkingen kunt uitdrukken:

ut.expect(value) + verschillende expressies
ut.should(value) + verschillende expressies

Alle .expect() en .should() expressies zullen, als ze op zichzelf worden gebruikt, een fout genereren als niet aan de gewenste criteria wordt voldaan en zullen de uitvoering van de controleregel stoppen. Alle aanvullende assertions die in de rest van het script zijn gedefinieerd zullen niet worden uitgevoerd. Meestal wilt u echter de volledige set assertions uitvoeren, ongeacht of een van de eerdere assertions mislukt. Dit kan worden bereikt met ut.test():

ut.test(descriptionText, testFunction): de uitvoer (succes of mislukking) van een .expect of .should die is gedefinieerd in de gespecificeerde testFunction, komt terecht in de assertions-uitvoer van de controleregel. Bovendien zorgt ut.test() ervoor dat de uitvoering van het script niet wordt stopgezet wanneer een assertion mislukt.