Das Multi-step API Monitoring einrichten

Um deine API richtig zu überwachen, wirst du häufig mehrere HTTP-Anfragen verwenden müssen. In der Regel wirst du eine Reihe von Anfragen einrichten, bei der jede neue Anfrage ein oder mehrere Daten aus einer vorherigen Anfrage enthält.

Mögliche Gründe für die Ausführung einer Reihe von HTTP-Anfragen sind:

• Deine API erfordert einen authentifizierten Zugang. Um eine Methode in der tatsächlichen API aufzurufen, muss zunächst ein API-Client authentifiziert werden (zum Beispiel unter Nutzung der OAuth-Authentifizierung).
• Du möchtest ein funktionierendes Szenario bestehend aus mehreren Schritten in deiner API testen, das üblicherweise in einer** speziellen Reihenfolge** von den Endnutzern ausgeführt wird.
• Eine deiner HTTP-Anfragen gibt eine Weiterleitung zu einer anderen URL zurück, aber du möchtest die Antwort untersuchen, bevor sie der Weiterleitung folgt.

Für jedes dieser Szenarien passt das Multi-step API-Monitoring großartig!

Ein API-Szenario kann als einzelner Schritt beginnen, aber du kannst selbst mehr Schritte hinzufügen und später die Szenarien erweitern. Du hast die volle Kontrolle über den kompletten HTTP-Abfrageinhalt. Funktionen sind unter anderem:

• Einrichten der HTTP-Methode, URL, Request Header und Request-Inhalte für jede Abfrage.
• Hinzufügen einer Authentifizierung (Basic/NTLM/Digest/OAuth) oder von Client-Zertifikaten, um Zugriff auf geschützte APIs zu erhalten.
• Definieren von Assertions (Prüfpunkte) für jede Antwort, um HTTP-Statuscode, Inhalt (basierend auf Klartext, JSON-Inhalt oder XML-Inhalt), Abfragedauer und mehr zu verifizieren.
• Extrahieren von Inhalt aus der Antwort, aus den Antwort-Headern sowie aus Cookies und Speichern dieses Inhalts in Variablen. Die Variablen können in späteren Schritten verwendet werden, um neue URLs, Anfrage-Header usw. zu erzeugen.

Diese Funktionen stellen sicher, dass deine API sich richtig verhält und innerhalb der von dir spezifizierten Grenzen arbeitet. Dieser schrittweise Ansatz ermöglicht dir, unkompliziert sehr mächtige Szenarien einzurichten. Sofern du weißt, wie deine API sich verhalten sollte, benötigst du keine Programmierkenntnisse, um das API-Monitoring aufzunehmen.

Das Multi-step API Monitoring-Prüfobjekt erstellen

Um ein Multi-step API Monitoring-Prüfobjekt zu erstellen:

Klicke auf die +-Schaltfläche im Menü unter Überwachung > Prüfobjekteinrichtung.

1. Gehe zu Überwachung > Prüfobjekteinrichtung und klicke auf das +-Symbol (Hinzufügen).
2. Wähle im Pop-up-Fenster Wähle einen Prüfobjekttyp aus zunächst den Prüfobjekttyp Multi-step API und klicke dann auf die Schaltfläche Wähle aus. Das neue Prüfobjekt wird erstellt und du siehst die Konfigurationsseite des Prüfobjekts.
3. Gib deinem Prüfobjekt einen Namen.
4. Lege das Überwachungsintervall fest. Dein [Überwachungsintervall(https://www.uptrends.de/support/kb/synthetic-monitoring/pruefobjekt-einstellungen/die-ueberwachungs-frequenz/) ist der Zeitraum zwischen dem Ende der letzten Überprüfung bis zum Beginn der nächsten.
5. Wechsele zur Registerkarte Schritte, um Informationen für jeden Schritt einzugeben.

Dein neues Prüfobjekt beginnt mit einem (leeren) Schritt. Klicke einfach auf Füge Abfrage Schritt hinzu, um zusätzliche Schritte hinzuzufügen. Du siehst, wie die Liste der Schritte sich erweitert. Klicke auf einen Schritt, um die Details zu bearbeiten. Um einen Schritt zu entfernen, klicke auf das Schritt löschen-Zeichen. Klicke auf das Schritt kopieren-Zeichen, um eine Kopie eines bestehenden Schritts zu erstellen. Du kannst die Reihenfolge der Schritte anhand der Pfeil-Schaltflächen Ein Schritt hoch und Ein Schritt runter ändern.

Einen Anfrage-Schritt konfigurieren

Im ersten Schritt des Prüfobjekts wirst du zwei Registerkarten unter der Schrittbeschreibung bemerken: Request und Response. Ein Schritt bei einem Multi-step API Monitoring besteht aus einem vollständigen API-Aufruf (d. h. eine Anfrage und eine Antwort). Bei jedem Schritt kannst du die Anfrage definieren und Uptrends mitteilen, wie es mit der Antwort umgehen soll. Jede Multi-step API beginnt mit einem leeren Schritt. Füllen wir ihn aus.

Request

Die Registerkarte Request enthält alle benötigten Daten, um eine tatsächliche HTTP-Anfrage in dem Schritt auszuführen. Mindestangaben:

1. Wähle die geeignete HTTP-Methode – entweder GET, POST, PUT, PATCH, DELETE, HEAD oder OPTIONS. Schreibe uns, wenn du eine andere Methode benötigst.
2. Gib die URL für die Anfrage ein. Verwende eine qualifizierte URL, einschließlich des Schemas („https://“ oder „http://“), des Domainnamens und Pfads für die API und aller gewünschten Parameter des Abfragestrings.
3. Gib optional für diesen Schritt eine kurze Beschreibung ein. Diese Beschreibung wird in den Ergebnissen zum Prüfobjekt gezeigt.

Request Body

Bei Angabe einer POST-, PUT-, PATCH, HEAD-, OPTIONS- oder DELETE-Anfrage erscheint das Feld Request Body. Gib die Daten ein, die als Teil der Anfrage (wahrscheinlich JSON-Daten, XML-Daten oder verschlüsselte Formulardaten) gesendet werden sollen. In den meisten Fällen wird der Server erwarten, dass du das Format der gesendeten Daten spezifizierst, sodass er weiß, wie sie gelesen und analysiert werden. Dafür musst du einen Anfrage-Header Content-Type wie im nächsten Abschnitt beschrieben hinzufügen.

Request Headers

Eine HTTP-Anfrage enthält üblicherweise einige Request Header, um das Format der gesendeten Daten zu spezifizieren oder näher zu beschreiben, welche Art Antwort erwartet wird. Bei der Einrichtung eines Abfrageschritts wirst du bemerken, dass bestimmte Request Header automatisch hinzugefügt wurden. Diese Header bestehen aus einem Standard-Set abhängig von deinem Abfragetyp (beispielsweise ist das Header-Set für GET-Abfragen ein anderes als das Set für POST-Abfragen). Ein Standard-Header kann (mit Ausnahme des Headers Content-Length) überschrieben werden, indem du einen neuen Header mit demselben Namen wie zuvor, aber einem anderen Wert hinzufügst.

Es können auch neue Header hinzugefügt werden. Um beispielsweise den zuvor genannten Content-Type-Header hinzuzufügen, folge diesen Schritten:

1. Klicke auf die Schaltfläche Request Header hinzufügen, um einen Namen und Wert für einen Request Header einzugeben.
2. Gib Content-Type als den Header-Namen ein.
3. Der entsprechende Header-Wert hängt von den Daten ab, die du sendest. Die meisten Content-Typen sind application/json für JSON-Daten, text/xml für XML-Daten und application/x-www-form-urlencoded für Webform-Daten.

Wenn deine API erfordert, dass du eine Authentifizierung einfügst, füge einen Header Authorization zusammen mit den richtigen Daten im Wert-Feld ein.

Die Abbildung oben zeigt ein Beispiel eines Abfrageschritts. Beachte Folgendes:

• Es handelt sich um eine POST-Abfrage an https://www.galacticresorts.com/api/Reservation
• Das Header-Standard-Set für diese Abfrage ist:
  • Host
  • Accept-Encoding
  • Connection
  • Content-Length
• Die Werte für die Header Host und Content-Length werden beim Senden der Abfrage bestimmt.
• Die manuellen Header Content-Type und Authorization wurden hinzugefügt, um jeweils das Datenformat anzugeben und die erforderlichen Anmeldedaten bereitzustellen.
• Der Standard-Header Connection wurde überschrieben.
• Der Request Body enthält x-www-form-urlencoded-Inhalte mit einigen Variablen.

Authentifizierung

Viele APIs sind geschützt und nur nach Angabe von Anmeldedaten zugänglich. Wenn deine API eine Authentifizierung auf HTTP-Protokollebene nutzt, wähle die Art der Authentifizierung (Basic, NTLM oder Digest) und gib den zugehörigen Benutzernamen und das Passwort ein. Alternativ kannst du eine OAuth-basierte Authentifizierung anhand separater Schritte einrichten. Weitere Informationen zur Einrichtung von einer integrierten oder benutzerdefinierten Authentifizierung.

Ein Credential Set aus der Vault nutzen

Es ist möglich, an jeder Stelle auf das Anmeldedaten-Set in der Vault als Teil eines Request Bodys oder Request Headers oder als Wert deiner Benutzername-Passwort-Kombination unter Authentifizierung Bezug zu nehmen. Um dich auf ein Vault Item zu beziehen, setze die folgende Syntax ein: {{@VaultItem.<itemGuid>.Password}} oder {{@VaultItem.<itemGuid>.Username}}, abhängig vom erforderlichen Wert. Du findest die itemGuid, indem du zu dem Vault Item mit dem Credential Set (Anmeldedaten-Set) navigierst. Kopiere den letzten Teil der URL in die URL-Leiste deines Browsers.

cURL Requests importieren

Es ist auch möglich, cURL Requests direkt zu importieren, um Schritte zu erstellen, ohne sie manuell zu erstellen. Das geschieht folgendermaßen:

1. Klicke im visuellen Schritte-Editor (auf der Registerkarte Schritte bei den Prüfobjekteinstellungen) des Multi-step API-Prüfobjekts, bei dem du einen Schritt auf Basis eines cURL-Befehls importieren möchtest, auf cURL-Import, um den Importassistenten aufzurufen.
2. Klicke auf Weiter.
3. Füge deine cURL Commandline Statement(s) ein. Nehmen wir beispielsweise an, dass wir einen Schritt einfügen möchten anhand des cURL Statements:

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"

Dies ist ein Request, um eine Reservierung auf unserer Test-Urlaubs-Website, GalacticResorts.com, zu erstellen.

Du kannst mehrere Schritte zugleich hinzufügen, indem du mehrere cURL-Befehle eingibst.

4. Sofern erforderlich, gib das Befehlsformat an. In den meisten fällen wird „Auto-Erkennung“ ausreichen.
5. Klicke auf Weiter.
6. Klicke im letzten Schritt des Assistenten auf Schritte generieren.

Das Ergebnis für den genannten cURL-Befehl dieses Beispiels sieht folgendermaßen aus:

Der Prüfobjekttyp Multi-step API unterstützt nicht alle Optionen, die in der cURL Commandline aufgeführt wurden. Die nicht unterstützten Optionen werden automatisch entfernt. Achte also darauf, den Schritt zu testen, um sicherzustellen, dass er wie erwartet funktioniert.

Response

Die Registerkarte Response enthält alle Optionen zur Ausführung von Checks bei den Antwortdaten (anhand von Prüfpunkten/Assertions) und zum Verarbeiten der Daten in Vorbereitung auf den nächsten Schritt (anhand von Variablen).

Assertions

Die Definition der Schritte und Übergabe der korrekten Daten in diese Schritte ist die Grundlage für eine nutzbringende Einrichtung. Es ist jedoch auch wichtig, die Ergebnisse jedes Schritts zu betrachten. Einfach eine Reihe von URLs aufzurufen, reicht nicht, wenn sie nicht die richtigen Ergebnisse zurückgeben. Assertions helfen bei diesen Statuschecks.

Assertions sind Prüfpunkte, auf die du testen kannst, um zu verifizieren, dass die Antwort in einem bestimmten Schritt wie erwartet ausfällt, zum Beispiel durch Überprüfen des Inhalts oder Verifizieren, dass er innerhalb eines bestimmten Zeitraums erhalten wurde. Wie bei den Variablen gibst du die Quelle für die Überprüfung an, zum Beispiel ein JSON-Merkmal aus dem JSON-Antwortinhalt, eine XPath-Anfrage im XML-Antwortinhalt oder einfach den Statuscode der Antwort, die Dauer oder die Inhaltslänge.

Weitere Beispiele für Assertions findest du in unserer ausführlichen Anleitung zur Definition von Assertions.

Variablen

Beim Einrichten von mehrstufigen Szenarien ist es wahrscheinlich, dass wenigstens einer der Schritte von dem Input abhängt, der im vorherigen Schritt abgerufen wurde. Durch Erfassen der Eingabe, das temporäre Speichern und die Übernahme in den nächsten Schritten erzeugst du eine natürliche Reihe verbundener Schritte, ohne programmieren zu müssen.

Variablen ermöglichen genau das! Mit jedem Schritt besteht die Möglichkeit, neue Variablen zu erzeugen und auf gespeicherte Variablen zuzugreifen, die in anderen Schritten erstellt wurden. Auf diese Weise können zuvor erfasste Daten deines Szenarios wiederverwendet werden.

Du kannst definieren, woher die Variablen kommen sollen: Wahrscheinlich ist es ein bestimmter Wert aus JSON- oder XML-Daten, aber die Erfassung von Antwort-Headern oder auch von Daten aus einer Weiterleitung ist ebenfalls möglich. Nachdem eine Variable definiert wurde, kannst du sie an jeder Stelle des mehrstufigen Set-ups verwenden, indem du einen Bezug zu ihrem Namen herstellst: {{my-variable}}.

Weitere Beispiele von Variablen: Variablen definieren und einsetzen.

Maximale Anzahl von Versuchen

In einigen Fällen benötigt deine API eventuell etwas Zeit, um bestimmte Abfragen zu verarbeiten, bevor sie mit dem erfolgreichen Ausführen der Aktion antworten kann. Nehmen wir beispielsweise an, du lädst eine Datei zur Bearbeitung in deine API hoch. Während dieser Verarbeitung reagiert die API auf die Abfrage des Status mit {"result":"processing"} in einer JSON-codierten Antwort. Sobald diese Verarbeitung abgeschlossen ist, antwortet die API stattdessen mit {"result":"success"}. In solchen Fällen kannst du das Prüfobjekt mit der Einstellung Maximale Anzahl Versuche anweisen, Abfragen an die API zu senden, bis sie mit „erfolgreich“ antwortet.

Mit dieser Funktion konfigurierst du das Prüfobjekt, den Schritt zu wiederholen, wenn eine oder mehrere Assertions des Schritts (wie etwa Response Body in JSON Ergebnis Ist gleich Erfolg für das oben genannte Beispiel) fehlschlagen. Du kannst einstellen, wie häufig das Prüfobjekt den Versuch wiederholen soll – bis maximal 50 Wiederholungen. Beachte, dass die Mindestzahl der Wiederholungen zwei beträgt, da die erste Abfrage als erster Versuch zählt.

Zusätzlich hast du die Option, die Zeit zwischen diesen Wiederholungen einzugeben. Die Wartezeit zwischen zwei Versuchen sollte zwischen 500 und 30.000 ms betragen. Sie ist standardmäßig auf 1.000 ms gesetzt.

Für jeden Schritt kannst du eine Höchstzahl an Wiederholungen zusammen mit einer Wartezeit zwischen diesen Wiederholungen konfigurieren.

Das Prüfobjekt wiederholt den Schritt, bis die angegebene Anzahl Versuche erreicht ist oder bis jede Assertion erfüllt wurde. Dann werden das Prüfobjekt und die Schritte in ihrer Reihenfolge wie gewöhnlich weiter ausgeführt. Wenn die angegebene Anzahl Versuche erreicht ist und eine Assertion immer noch nicht bestätigt wurde, verzeichnet das Prüfobjekt einen Fehler im Prüfobjektprotokoll.

Die Kosten für das MSA-Prüfobjekt ändern sich nicht, gleich wie viele Versuche ausgeführt werden sollen.

Datei-Uploads konfigurieren

Multi-step API-Prüfobjekte ermöglichen dir, Dateien aus deiner Vault als Teil eines deiner Abfrageschritte hochzuladen. Bei jedem HTTP-Schritt, den du im Rahmen eines Multi-step API Monitorings konfigurierst und der einen Abfrageteil enthält, kann es sich entweder um einen Form-Data- oder Binär-Datei-Upload- oder eine Klartext-Abfrage handeln. Dateien werden als multipart/form-data- oder als Binär-Content gesendet. Folge diesen Schritten, um eine Datei als Form-Data hinzuzufügen:

1. Lade die fragliche Datei in deine Vault hoch. Die Dateigröße beträgt maximal 2 MB.
2. Füge in den Einstellungen deines Multi-Step API-Prüfobjekts einen Request-Schritt hinzu oder nutze einen bestehenden Schritt, um den Datei-Upload auszuführen.
3. Setze die Abfrage-Methode auf der Registerkarte Request des Schritts, der den Datei-Upload ausführen soll, auf POST, PUT oder PATCH (je nach Anforderung) und gib die Abfrage-URL ein.
4. Wähle unter Request Body die Option Lade eine Datei hoch (als Form-Data).
5. Klicke auf die dann erscheinende Schaltfläche Füge Datei aus Vault hinzu.
6. Wähle die entsprechende Datei aus der Liste „Vault Datei Upload“ und klicke auf Auswählen.
7. Es ist nicht notwendig, besondere Abfrage-Header hinzuzufügen. Wir richten automatisch einen Abfrage-Header für Content-Length ein und setzen für Content-Type: multipart/form-data die korrekten Werte.

Wenn du eine Datei hochladen möchtest, ohne dass Uptrends Content-Disposition Metadaten zum Request Body hinzufügt, kannst du Lade eine Datei hoch (als Binary) unter Request Body bei Schritt 4 oben wählen. Wir werden immer noch die entsprechenden Header, die unter Request Header aufgeführt sind, automatisch generieren, aber keine speziellen Metadaten mehr zur Abfrage hinzufügen. Somit kann deine API, wenn sie Dateien als rohe Binärdaten erwartet, trotzdem getestet werden.

Bedenke, dass deine API eventuell einen bestimmten Wert für den Dateinamen erwartet. Die Abfrage wird den automatisch erstellten Header Content-Disposition enthalten, der einige Metadaten enthält. Der Wert für diesen Header enthält den Parameter Name. Standardmäßig verwenden wir den Dateinamen, der von dir in der Vault angegeben wurde. Achte darauf, dass der Dateiname, den du vergibst, wenn du die Datei der Vault hinzufügst, dem von deiner API erwarteten Wert entspricht. Wenn deine API zum Beispiel erwartet, dass die hochgeladene Datei den Namen „image“ hat, stelle sicher, dass du „image“ (ohne Dateierweiterung) als den Dateinamen beim entsprechenden Vault Item angibst.

Einen Wartezeit-Schritt konfigurieren

Wenn du bei dem Prüfobjekt eine Folge von „Request“-Schritten eingefügt hast, wird jeder Schritt ausgeführt, sobald der vorherige abgeschlossen ist – ohne Verzögerung. Die sofortige Ausführung kann jedoch für einige Situationen zu schnell sein.

Ein Beispiel ist eine API-Methode, die als Abfrage zur Erstellung einer Berichtsdatei dient. Die API initiiert einen im Backend ablaufenden Vorgang, der die Berichtsdatei erzeugt, und instruiert den Nutzer, eine zweite Abfrage zu senden, um diese neue Datei herunterzuladen. Die Erzeugung dieser Datei kann ein paar Sekunden dauern, sodass der Nutzer einige Sekunden warten sollte, bevor er eine zweite Abfrage sendet. Wenn die zweite Abfrage zu früh gesendet wird, könnte der Vorgang fehlschlagen, da die Berichtsdatei möglicherweise noch nicht komplett erstellt wurde.

In dieser Situation ist es wichtig zu warten, bevor die zweite Abfrage ausgeführt wird. Zu diesem Zweck kann ein Wartezeit-Schritt eingesetzt werden. Diese Art von Schritt ermöglicht dir, die Anzahl Millisekunden für das Warten festzulegen. Um beispielsweise drei Sekunden zu warten, gib 3000 Millisekunden als Wartezeit ein. Diese Wartezeit wird in den Gesamtzeitwerten des Prüfobjekts enthalten sein.

Um einen Wartezeit-Schritt hinzuzufügen, klicke einfach auf die Schaltfläche Füge Wartezeit Schritt hinzu und gib die Anzahl Millisekunden für die Wartezeit ein. Du kannst den Wartezeit-Schritt anhand der Pfeil-Schaltflächen bei „Ein Schritt hoch/runter“ an die richtige Position deines Szenarios verschieben.

Die Wartezeit für einen Wartezeit-Schritt ist auf 60 Sekunden beschränkt: Ein Wartezeit-Schritt ist nicht dazu gedacht, eine lange Aufgabe zu überwachen, die mehrere Minuten oder Stunden dauert. Wenn das Prüfobjekt die maximale Gesamtzeit zur Ausführung überschreitet, wird die Prüfung unterbrochen und meldet einen Fehler.

Das Hinzufügen eines Warteschritts ist kostenlos. Der Preis eines Multi-step API-Prüfobjekts basiert lediglich auf der Anzahl der „Request“-Schritte.

Multi-step Monitoring – Ergebnisse, Fehler und Warnmeldungen

Mehrstufige API-Prüfobjekte verhalten sich wie alle anderen Prüfobjekte. Jede Überprüfung erscheint im Prüfobjektprotokoll und zeigt ausführliche Informationen für jeden einzelnen Schritt. Für jeden Schritt besteht diese Information aus:

• die Gesamtdauer des Schritts (in Millisekunden)
• die URL, die während des Schritts aufgerufen wurde
• der HTTP-Statuscode, der zurückgegeben wurde
• das Ergebnis für jeden Prüfpunkt (in Ordnung oder Fehler)
• Anfrage-Header und -Inhalt, die wir gesendet haben
• Anfrage-Header und -Inhalt, die wir erhalten haben

Wenn bei einem Schritt ein Problem auftritt oder wenn einer der definierten Prüfpunkte nicht in Ordnung ist, wird das Prüfobjekt einen Fehler melden. Wie üblich können diese Fehler Warnmeldungen basierend auf den von dir festgelegten Meldedefinitionen ausgeben.