1. Support
  2. Knowledge Base
  3. API Monitoring
  4. Das Multi-step API Monitoring einrichten

Das Multi-step API Monitoring einrichten

Wir verbessern z. Zt. die Benutzeroberfläche. Manche Infos hier sind evtl. nicht mehr aktuell. Erfahre mehr.

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 Authentication).
  • 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. Die Funktionen:

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, ohne Schwierigkeiten 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:

  1. Wähle + Prüfobjekt hinzufügen aus dem Menü Prüfobjekte.
  2. Wähle Multi-step API aus der Liste unter Typ.
  3. Gib deinem Prüfobjekt einen Namen.
  4. Wechsele zur Registerkarte Schritte, um Informationen für jeden Schritt einzugeben.

Dein neues Prüfobjekt beginnt mit einem (leeren) Schritt. Klicke einfach auf die Schaltfläche + Füge 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 Schritt löschen, was als x erscheint, wenn du mit der Maus über den Schritt in der Liste fährst.

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 auf der rechten Seite bemerken. Request und Response. Sehen wir sie uns an.

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 Header

Eine HTTP-Anfrage enthält üblicherweise einige Anfrage-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.

Beispiele für Request Header

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.

Authentifizierung

Viele APIs sind geschützt und nur zugänglich durch Angabe von Anmeldedaten. 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 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.

Beispiele für Bezugname auf Vault Items

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, die du abtesten 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 Prüfpunkte: Lies unsere ausführliche Anleitung zur Definition von Prüfpunkten.

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 Aufzeichnen 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 Aufzeichnung von Antwort-Headern oder auch von Daten aus einer Weiterleitung sind 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: Definition und Einsatz von Variablen.

Wiederholen bis erfolgreich

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 Funktion Wiederholen bis erfolgreich 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 zu 50 Versuche). Jeder Versuch wird mit einer Sekunde Verzögerung zum vorherigen ausgeführt. Aktiviere die Option einfach auf der Response-Registerkarte eines Schritts und bestimme die Anzahl der Wiederholungen.

MSA-Schritt-Wiederholung

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.

Beachte, dass die Kosten für das MSA-Prüfobjekt sich nicht ändern, 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 eine Datei-Upload- oder ein Klartext-Abfrage handeln. Dateien werden als multipart/form-data-Content gesendet. Folge diesen Schritten, um dies einzurichten:

  1. Lade die benötigte 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 Eine Datei aus dem Vault hochladen.
  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. Auswahltool beim Datei-Upload
  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. Beispiel-Header für Datei-Upload

Einen “Wait”-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 zusenden, um diese neue Datei herunterzuladen. Die Erzeugung dieser Datei kann 1–2 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 „Wait“-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 „Wait“-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 „Wait“-Schritt anhand der Pfeil-Schaltflächen bei „Ein Schritt hoch/runter“ an die richtige Position deines Szenarios verschieben.

Die Wartezeit für einen “Wait”-Schritt ist auf 60 Sekunden beschränkt: Ein „Wait“-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:

  • Gesamtdauer des Schritts (in Millisekunden)
  • URL, die während des Schritts aufgerufen wurde
  • HTTP-Statuscode, der zurückgegeben wurde
  • Ergebnis für jeden Prüfpunkt (in Ordnung oder Fehler)
  • Abfrage-Header und -Inhalt, die wir gesendet haben
  • Abfrage-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.

Durch die Nutzung dieser Website stimmen Sie der Verwendung von Cookies gemäß unserer Cookie-Richtlinien zu.