Multi-step API monitoring configureren

Om uw API adequaat te monitoren moet u vaak gebruikmaken van multiple HTTP requests. Meestal zult u een reeks requests willen configureren, waarbij iedere nieuwe request gebruikmaakt van een of meer stukjes data afkomstig van een vorige request om zijn taak uit te voeren.

Mogelijke redenen om een reeks HTTP requests te doen zijn:

Uw API vereist geverifieerde toegang. Om een method aan te roepen in de daadwerkelijke API moet een API client zich eerst authenticeren (bijvoorbeeld door het gebruik van OAuth authentication).
U wilt een functioneel scenario in uw API testen dat bestaat uit meerdere stappen die meestal door uw eindgebruikers in een bepaalde volgorde worden uitgevoerd.
Een van uw HTTP requests retourneert een redirect naar een andere URL, maar u wilt die respons inspecteren voordat de redirect wordt gevolgd.

Voor al deze scenario’s is Multi-step API monitoring heel geschikt!

Een API scenario kan beginnen als slechts een enkele stap, maar u kunt zelf meer stappen toevoegen en uw scenario’s zelfs later uitbreiden. U heeft volledige controle over de complete HTTP request content. Functies omvatten:

Instellen van de HTTP method, URL, request headers en request body voor iedere request.
Toevoegen van authenticatie (Basic/NTLM/Digest/OAuth) of cliëntcertificaten toevoegen om toegang te verkrijgen tot beveiligde API’s.
Definiëren van assertions (controles) voor iedere response, voor het verifiëren van de HTTP-statuscode, content checks (gebaseerd op platte tekst, JSON- of XML-content), requestduur en meer.
Content extraheren uit de response body, response headers, cookies en ze opslaan in variabelen. Deze variabelen kunnen in latere stappen gebruikt worden om nieuwe URL’s, request headers enzovoort te bouwen.

Deze functies helpen u ervoor te zorgen dat uw API zich correct gedraagt en binnen de door u gespecificeerde limieten presteert. De stapsgewijze aanpak stelt u in staat om zeer krachtige scenario’s op te zetten zonder complexiteit toe te voegen. Zolang u maar weet hoe uw API zich moet gedragen, hoeft u niet te kunnen programmeren om aan de slag te gaan met API monitoring.

Een multi-step API controleregel creëren

Een multi-step API-controleregel toevoegen:

Klik op de + knop in het menu Monitoring > Controleregels beheren..
Klik in het pop-upvenster Kies een controleregel type eerst op het controleregeltype Multi-step API en klik dan op de knop Kiezen.
De nieuwe controleregel is gecreëerd en u bevindt zich in het configuratiescherm van de controleregel.
Geef uw controleregel een Naam.
Stel het Controle-interval in. Uw controle-interval is de tijd tussen het einde van de ene controle en het begin van de volgende.
Ga naar het tabblad Stappen om de details voor elke stap in te voeren.

Uw nieuwe controleregel begint met één (lege) stap. Ga door en klik op Request-stap toevoegen om extra stappen toe te voegen. U zult zien dat de lijst met stappen groeit. Klik op een stap om de details ervan te bewerken. Om een stap te verwijderen klikt u op de knop Stap verwijderen.
Klik op de knop Stap dupliceren om een kopie te maken van een bestaande stap. U kunt ook de volgorde van de stappen wijzigen met de knoppen Verplaats stap omhoog en Verplaats stap omlaag.

Voorbeeld MSA-stappen

Een Request-stap configureren

Bekijk de eerste stap van onze controleregel, u ziet twee tabbladen onder de stapomschrijving: Request en Response. Een stap in Multi-step API monitoring bestaat uit één round-trip call naar de API (d.w.z. één request en één response). Binnen elke stap kunt u uw request definiëren en Uptrends vertellen hoe de response moet worden afgehandeld. Elke Multi-step API begint met één lege stap. Laten we die vullen!

Request

Het tabblad Request bevat alle data die nodig zijn om de daadwerkelijke HTTP request in de stap uit te voeren. Doe ten minste het volgende:

Kies de juiste HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD of OPTIONS. Als u een andere methode nodig heeft, neem dan contact met ons op.
Vul de URL in voor de request. Gebruik een volledig gekwalificeerde URL, inclusief het protocol (https:// of http://), de domeinnaam en het pad voor uw API, en eventuele query string parameters die u wilt opnemen.
Voer optioneel een korte beschrijving in voor deze stap. Deze beschrijving verschijnt in de resultaten van de controleregelcheck.

Request body

Bij het opgeven van een POST, PUT, PATCH, DELETE, HEAD of OPTIONS request, verschijnt het veld Request body. Specificeer de data die u wilt verzenden als onderdeel van de request (hoogstwaarschijnlijk JSON data, XML data of gecodeerde formulierdata). In de meeste gevallen verwacht uw server dat u de indeling specificeert van de data die u verzendt, zodat het weet hoe deze data moeten worden gelezen en gedeconstrueerd. Om dit te doen moet u een Content-Type request header toevoegen zoals in de volgende alinea wordt beschreven.

Request headers

Een HTTP request bevat meestal enkele request headers om het formaat van de data die worden verzonden te specificeren, of om verder te beschrijven wat voor een soort respons verwacht wordt. Bij het configureren van een request stap zult u merken dat bepaalde headers automatisch worden toegevoegd. Deze headers bestaan uit een standaardset, afhankelijk van het type request dat u doet (GET-requests hebben bijvoorbeeld een andere set headers dan POST-requests). Een standaard header kan worden overschreven (met uitzondering van de Content-Length header) door simpelweg een nieuwe header toe te voegen met precies dezelfde naam als de bestaande, maar met een andere waarde.

Er kunnen ook nieuwe headers worden toegevoegd. Bijvoorbeeld, om de eerder genoemde Content-Type header toe te voegen, volgt u deze stappen:

Klik op de knop Request header toevoegen om een request header key en waarde toe te voegen.
Voer Content-Type in als de header key.
De juiste header waarde is afhankelijk van de data die u verzendt. De meest voorkomende content types zijn application/json voor JSON data, text/xml voor XML data en application/x-www-form-urlencoded voor webformulierendata.

Evenzo, als uw API vereist dat u authenticatie opneemt, voegt u een Authorization header toe samen met de juiste data in het veld Waarde.

Voorbeelden van request headers

De afbeelding hierboven toont een voorbeeld van een request stap. Let op het volgende:

Het is een POST request naar https://www.galacticresorts.com/api/Reservation
De standaard headers die voor deze request zijn ingesteld, zijn:
- Host
- Accept-Encoding
- Connection
- Content-Length
De waarden voor de headers Host en Content-Length worden bepaald bij het verzenden van de request.
Handmatige headers Content-Type en Authorization zijn toegevoegd om respectievelijk het dataformaat te specificeren en de benodigde inloggegevens te verstrekken.
Standaard header Connection is overschreven.
De request body bevat wat x-www-form-urlencoded inhoud, verwijzend naar enkele variabelen.

Authenticatie

Veel API’s zijn beveiligd en alleen toegankelijk door inloggegevens te verstrekken. Als uw API gebruikmaakt van authenticatie op het HTTP-protocolniveau, kies dan uw type authenticatie (Basic, NTLM or Digest) en vul de bijbehorende gebruikersnaam en wachtwoord in. Als alternatief kunt u een op OAuth gebaseerde authenticatie instellen met afzonderlijke stappen. Meer informatie over het instellen van ingebouwde of aangepaste authenticatie.

Inloggegevens uit de vault gebruiken

Het is mogelijk om op elk punt verwijzingen naar vault-inloggegevens te gebruiken als onderdeel van de request body, request headers of als de waarde voor uw gebruikersnaam/wachtwoord onder Authenticatie. Gebruik de volgende syntaxis om naar een vault-item te verwijzen: {{@VaultItem.<itemGuid>.Password}} of {{@VaultItem.<itemGuid>.Username}} afhankelijk van welke waarde vereist is. Om de itemGuid te vinden navigeert u naar het vault-item met de inloggegevens en kopieert u vervolgens het laatste deel van de URL in de URL-balk van uw browser.

Voorbeelden van verwijzingen naar vault-items

cURL requests importeren

Het is ook mogelijk om cURL requests rechtstreeks te importeren om uw stappen te creëren, zonder ze handmatig opnieuw te hoeven maken. Dit doet u als volgt:

In de Visuele stap-editor (in het tabblad Stappen van de controleregelinstellingen) van de Multi-step API-controleregel waarin u een stap wilt importeren op basis van een curl-opdracht, klikt u op de knop cURL import om de importwizard te openen.
Klik op de knop Volgende.
Plak uw cURL-commandoregel statement(s). Stel dat we bijvoorbeeld een stap willen maken op basis van cURL-statement:

curl -X POST https://www.galacticresorts.com/api/Reservation -H "Content-Type: application/x-www-form-urlencoded" -u username:password -d "name=Joe&productId=97f8fcc9-11b5-4d86-b208-ccb6d2be35e3&sols=5"

Dit is een request om een reservering te creëren op onze voorbeeldsite voor het testen van vakantieboekingen, GalacticResorts.com.

U kunt meerdere stappen tegelijk toevoegen door meerdere cURL-opdrachten te plakken.

Specificeer indien nodig het opdrachtformaat. In de meeste gevallen is ‘Automatisch detecteren’ echter voldoende.
Klik op de knop Volgende.
Klik in de laatste stap van de wizard op de knop Stappen genereren.

Het resultaat van de cURL-opdracht die in dit voorbeeld wordt genoemd, zou als volgt zijn:

resultaat cURL import

Het controleregeltype Multi-step API ondersteunt niet alle opties in de cURL-opdrachtregel. Niet-ondersteunde opties worden automatisch genegeerd, probeer de stap dus uit om te controleren of deze naar verwachting werkt.

Response

Het tabblad Response bevat alle opties voor het uitvoeren van controles op responsdata (met behulp van Assertions) en het verwerken van die data ter voorbereiding op de volgende stap (met behulp van Variabelen).

Response tab

Assertions

Het definiëren van uw stappen en het invoeren van de juiste data in deze stappen is de basis voor een bruikbare opzet. Het is echter ook belangrijk om naar de resultaten van elke stap te kijken. Alleen het aanroepen van een reeks URL’s is niet zinvol als ze niet de juiste resultaten terugsturen. Assertions helpen u bij deze gezondheidscontroles.

Assertions zijn controles die u kunt uitvoeren om te verifiëren dat de respons zich in een bepaalde stap gedraagt als verwacht, bijvoorbeeld, door zijn content te controleren of te verifiëren of het binnen een bepaalde hoeveelheid tijd is opgehaald. Net als bij variabelen, geeft u de bron voor de controle op, bijvoorbeeld een JSON property van de JSON response body, een XPath query op de XML response body, of zelfs alleen de statuscode van de response, de duur ervan of de lengte van de inhoud.

Meer voorbeelden van Assertions: lees onze uitgebreide handleiding voor het definiëren van assertions.

Variabelen

Wanneer u multi-step scenario’s aan het opzetten bent, is het waarschijnlijk dat ten minste één van die stappen afhankelijk is van invoer die tijdens een vorige stap is opgehaald. Door die invoer vast te leggen, tijdelijk op te slaan en mee te nemen naar de volgende stappen, creëert u een natuurlijke progressie van verbonden stappen, zonder dat u enige code hoeft te schrijven.

Dat is precies wat u met variabelen kunt doen! Elke stap kan nieuwe variabelen maken en heeft toegang tot variabelen die door andere stappen zijn gemaakt, zodat u data kunt hergebruiken die eerder in het scenario zijn vastgelegd.

U kunt definiëren waar een variabele vandaan moet komen: waarschijnlijk een bepaalde waarde uit JSON- of XML-data, maar het vastleggen van response headers of zelfs van data van een redirect is ook mogelijk. Nadat een variabele is gedefinieerd, kunt u deze eenvoudig overal in uw multi-step-opzet gebruiken door er met zijn naam naar te verwijzen: {{my-variable}}.

Meer voorbeelden van Variabelen: Variabelen definiëren en gebruiken.

Maximaal aantal pogingen

In sommige gevallen kan het zijn dat uw API enige tijd nodig heeft om een binnenkomende request te verwerken voordat hij kan reageren met de melding dat het is gelukt. Stel dat u bijvoorbeeld een bestand voor verwerking uploadt naar uw API. Tijdens de verwerking reageert de API op requests over de status met {"result":"processing"} in een JSON-body. Zodra de verwerking is voltooid, begint de API in plaats daarvan te reageren met {"result":"success"}. In dergelijke gevallen kunt u de controleregel configureren om de API te blijven peilen totdat deze met succes reageert door de instelling Maximaal aantal pogingen te gebruiken.

Deze functie zorgt ervoor dat de controleregel de stap opnieuw doet als een of meer van de assertions (aannames) in de stap (zoals Response body als JSON result Is gelijk aan success voor het hierboven genoemde voorbeeld) mislukt. U kunt instellen hoeveel keer de controleregel het opnieuw moet proberen, met een maximum van 50 keer. Houd er rekening mee dat het minimum aantal pogingen twee is, aangezien de initiële request al als de eerste poging telt.

Naast het aantal pogingen kunt u de wachttijd tussen deze pogingen instellen. De wachttijd tussen pogingen moet tussen 500 en 30000 ms liggen en is standaard ingesteld op 1000 ms.

Voor elke stap kunt u een maximum aantal pogingen configureren in combinatie met een minimale wachttijd ertussen.

De controleregel zal de stap opnieuw blijven proberen ofwel totdat het maximum aantal pogingen is bereikt ofwel totdat elke assertion is geslaagd. Vanaf dat punt zal de controleregel gewoon verdergaan en de rest van de stappen in volgorde uitvoeren. Als het maximum aantal pogingen is bereikt en er nog steeds ten minste één assertion mislukt, rapporteert de controleregel een fout in het controleregel-log.

De kosten van de MSA-controleregel blijven gelijk, ongeacht het aantal pogingen.

Bestandsuploads configureren

Met Multi-step API-controleregels kunt u bestanden uploaden vanuit uw vault als onderdeel van een van uw request-stappen. Elke HTTP-stap die u configureert in de Multi-step API-controleregel die een request body bevat, kan een form-data- of binaire bestandsupload zijn of een gewone request met platte tekst. Bestanden worden verzonden als multipart/form-data of binaire inhoud. Volg deze stappen om een bestand als form-data toe te voegen:

Upload het betreffende bestand naar uw vault. De maximale bestandsgrootte is 2 MB.
Voeg in de instellingen van uw Multi-step API-controleregel een request-stap toe of gebruik een bestaande stap om het uploaden van het bestand uit te voeren.
In het tabblad Request van de stap die het uploaden van het bestand moet uitvoeren, stelt u de request-methode in op POST, PUT of PATCH (afhankelijk van wat u nodig heeft) en vult u de request-URL in.
Selecteer onder Request body de optie Bestand uploaden (als form-data).
Klik op de knop Bestand uit de vault toevoegen die verschijnt.
Kies het juiste bestand uit de Vault-bestandsuploadlijst en klik op de knop Selecteren.
Het is niet nodig om specifieke request headers toe te voegen. We stellen automatisch een request header in voor Content-Length en stellen Content-Type: multipart/form-data in met de juiste boundary (grens).

Als u een bestand wilt uploaden zonder dat Uptrends ‘Content-Disposition’-metadata toevoegt aan de request body, kunt u Een bestand uploaden (als binair) selecteren onder Request body bij stap 4 hierboven. We zullen nog steeds automatisch de juiste headers genereren die worden vermeld bij Request headers, maar zonder deze specifieke metadata aan de request toe te voegen. Op deze manier kunt u, als uw API bestanden verwacht die zijn geüpload als onbewerkte binaire data, deze nog steeds testen.

Houd er rekening mee dat uw API mogelijk een specifieke waarde voor de bestandsnaam verwacht. De request zal een automatisch geconstrueerde header Content-Disposition bevatten, die wat metadata bevat. De waarde voor deze header bevat een name parameter. Standaard gebruiken we de bestandsnaam zoals die door u in de vault is gespecificeerd. Zorg ervoor dat de bestandsnaam die u specificeert wanneer u het bestand aan de vault toevoegt, overeenkomt met de waarde die wordt verwacht door uw API. Als uw API bijvoorbeeld verwacht dat het geüploade bestand de naam “afbeelding” heeft, moet u ervoor zorgen dat u “afbeelding” (zonder bestandsextensie) opgeeft als bestandsnaam in het juiste vault-item.

Een Wachtstap configureren

Als u een reeks Request-stappen aan uw controleregel heeft toegevoegd, wordt elke stap uitgevoerd zodra de vorige stap is voltooid, zonder vertraging. Echter, deze onmiddellijke uitvoering kan voor sommige scenario’s iets te snel zijn.

Denk bijvoorbeeld aan een API-methode die vraagt een rapportbestand te genereren. De API start een backendproces dat het bestand genereert en de caller instrueert een tweede request te sturen om het nieuwe bestand te downloaden. Het genereren van het bestand kan zo’n twee seconden duren, dus de caller moet enkele seconden wachten voordat de tweede request wordt verstuurd. Wordt deze te snel verstuurd, dan zal de tweede request mislukken omdat het gegenereerde bestand nog niet gereed is.

Voor dit scenario is het belangrijk om te wachten voordat Multi-step API om de tweede request vraagt. Om een vertraging toe te voegen kunt u een afzonderlijke Wachtstap invoegen. Met een Wachtstap kunt u het aantal milliseconden opgeven dat moet worden vertraagd. Om bijvoorbeeld 3 seconden te wachten geeft u 3000 milliseconden op als de wachttijd. Het rapport bevat de extra wachttijd in de totale tijdsduur voor de controleregel.

Om een wachtstap toe te voegen klikt u gewoon op de knop Wachtstap toevoegen en specificeert dan het aantal milliseconden dat u wilt wachten. Zo nodig kunt u de wachtstap naar de juiste plek in uw scenario verplaatsen met de knoppen Verplaats stap omhoog/omlaag.

De wachttijd voor een wachtstap is beperkt tot 60 seconden: een wachtstap is niet bedoeld voor het monitoren van een langlopende taak die enkele minuten of uren duurt. Als de controleregel de maximale totale uitvoertijd overschrijdt, stopt de controle met uitvoeren en rapporteert een fout.

Het toevoegen van een wachtstap aan uw controleregel kost u niets. Uptrends baseert de kosten van een Multi-step API-controleregel alleen op het aantal Request-stappen.

Opmerking: De duur van de uitvoering van alle stappen in uw controleregel mag in totaal niet langer zijn dan 4 minuten. Als het langer dan 4 minuten duurt om de controleregel van begin tot eind uit te voeren, is het resultaat van de controleregelcheck een fout. Overweeg in dergelijke gevallen om uw requests, indien mogelijk, over meerdere controleregels uit te spreiden.

Resultaten, fouten en alerts van een multi-step-controleregel

Multi-step API-controleregels gedragen zich hetzelfde als elke andere controleregel. Elke controle verschijnt in de controleregel log en geeft uitgebreide informatie weer over elke afzonderlijke stap. Voor elke stap bestaat deze informatie uit:

de totale duur van de stap (in milliseconden)
de URL die werd uitgevoerd gedurende die stap
de HTTP statuscode die is geretourneerd
het resultaat voor iedere assertion (slagen of mislukken)
de request headers en content die we hebben verzonden
de response headers en content die we hebben ontvangen

Als er tijdens een van de stappen een probleem optreedt, of als een van de assertions die u heeft gedefinieerd mislukt, zal de controleregel mislukken en een fout rapporteren. Zoals gewoonlijk kunnen deze fouten alerts genereren op basis van uw alertdefinities.