Ein Multi-Step API-Prüfobjekt besteht aus Schritten. Du kannst für jeden Schritt sowohl die HTTP-Abfrage- wie auch -Antwort-Komponenten konfigurieren. Dieser Artikel bietet einen Überblick darüber, wie Abfragen funktionieren und wie du eine HTTP-Abfragedefinition einrichten kannst.
Request
Innerhalb eines Schritts siehst du den Tab Request. Du kannst den API-Endpunkt definieren und spezifische Informationen beim Senden der Abfrage an den Server einrichten.
Methode und URL
Als Mindestanforderung ist die entsprechende HTTP-Methode und URL anzugeben, um die Überwachung deiner API zu beginnen.
Die verfügbaren HTTP-Methoden sind:
GETHEADPOSTPUTPATCHDELETEOPTIONS
Die URL ist eine qualifizierte URL, einschließlich des Schemas („https://“ oder „http://“), Domainnamens und Pfads für die API. Du kannst auch Abfrageparameter verwenden, um aufgrund der Abfrage zurückgegebene Daten zu filtern, ordnen oder anzupassen.
Einige URL-Beispiel sind:
https://galacticresorts.com/api/Destinationshttps://galacticresorts.com/api/Destinations?name=AlphaCygnusIX- Du kannst auch eine
vordefinierte Variable nutzen, um einen Wert aus der URL zu speichern und sie als
{{BaseUrl}}/api/Destinationsoderhttps://galacticresorts.com/api/Destinations/{{ProductId}}einzubinden.
Request Header
Eine HTTP-Abfrage enthält Request Header, die mit der Abfrage gesendete Schlüssel-Wert-Paare sind, um zusätzliche Informationen an den Server zu senden. Diese Header definieren die Parameter der Abfrage, wie Content Type, Autorisierung und alle besonderen Anweisungen dafür, wie der Server die Abfrage verarbeiten sollte.
Bei der Einrichtung eines Abfrageschritts wirst du bemerken, dass bestimmte Request Header standardmäßig hinzugefügt wurden. Es gibt die Möglichkeiten, einen neuen Request Header hinzuzufügen, einen Standard-Header zu überschreiben oder Vault Items zu verwenden.
Das Bild oben zeigt ein Beispiel eines GET-Abfrageschritts an https://www.galacticresorts.com/api/Destinations. Standardmäßig enthält eine Abfrage solche Header wie Host, Accept-Encoding und Content-Length. Die Werte für den Header Host und Content-Lengthwerden beim Senden der Abfrage bestimmt. Außerdem wurde der Header Accept auf application/json gesetzt und der Standard-Header Accept-Encoding überschrieben.
Du kannst zudem Header wie Content-Type hinzufügen. Die meisten Inhaltstypen 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 eine Authentifizierung erfordert, integriere einen Header Authorization zusammen mit den entsprechenden Daten im Feld Wert.
Neue Header hinzufügen
Um einen neuen Header hinzuzufügen:
- Klicke auf Request Header hinzufügen.
- Gib den Header-Namen an. Zum Beispiel
Content-Type. - Gib den Header-Wert ein. Zum Beispiel
application/json.
Standard-Header überschreiben
Um einen Standard-Header zu überschreiben:
- Klicke auf Request Header hinzufügen.
- Gib einen bestehenden Header-Namen ein. Zum Beispiel
Accept-Encoding. - Gib einen neuen Header-Wert ein. Zum Beispiel
gzip, compress. Der Standard-Header erscheint nun durchgestrichen, um zu zeigen, dass er überschrieben wurde.
Request Body
Bei Eingabe einer POST-, PUT-, PATCH-, HEAD-, OPTIONS- oder DELETE-Abfrage, enthält der Request Body den jeweiligen Inhalt oder die Payload als Teil der Abfragedefinition.
Es gibt unterschiedliche Request-Body-Formate, aus denen du wählen kannst, wenn du Daten als Teil der Abfrage sendest:
- Klartext – sende reinen Text ohne jede Formatierung.
- Lade eine Datei hoch (als Form-Data) – sende eine Datei, zum Beispiel Bilder und Dokumente, aus der Vault im Form-Datenformat.
- Lade eine Datei hoch (als Binary) – sende eine Datei, zum Beispiel Bilder und Dokumente, aus der Vault in einem einfachen Binär-Datenformat.
- Multipart Form – sende mehrere Content-Typen in unterschiedlichen Formaten. Sende zum Beispiel Klartext-Einträge und Dateien, die aus der Vault abgerufen wurden, gleichzeitig.
Um Vault Items im Request Body zu verwenden, lies Vault Items beim Datei-Upload verwenden.
Authentifizierung
Wenn deine API geschützt ist und eine Authentifizierung bei einer Server-Abfrage erfordert, kannst du aus den verfügbaren Authentifizierungsoptionen unten wählen:
- Basic Authentication – spezifiziere einen Benutzernamen und ein Passwort, die in einem Base64-Format codiert und an den API-Server gesendet werden.
- NTLM (Windows) Authentication – spezifiziere einen Benutzernamen und ein Passwort, um eine Authentifizierung bei einem Windows-Server oder bei Domains durchzuführen.
- Digest Authentication – spezifiziere einen Benutzernamen und ein Passwort, die einen MD5-Hashwert erhalten und an den API-Server gesendet werden.
- Set up OAuth-based Authentication – verwende eine benutzerdefinierte Authentifizierung, genauer OAuth 2.0.
Wenn du deine bestehenden Vault Items für die Authentifizierung deiner Abfrage verwenden möchtest, lies im Abschnitt Vault Items verwenden unten weiter. Weitere Informationen findest du unter Multi-Step Monitoring-Authentifizierung.
Client-Zertifikate
Wenn deine API erfordert, dass Clients sich anhand eines Client-Zertifikats identifizieren, kannst du aus folgenden Optionen wählen:
- Uptrends Client Zertifikat – verwendet ein Uptrends Zertifikat, das mit der HTTP-Abfrage gesendet wird.
- Individuelles Client Zertifikat – füge dein eigenes Client-Zertifikat aus der Vault hinzu, das mit der HTTP-Abfrage gesendet wird.
Weitere Informationen findest du unter Multi-Step API – Client-Zertifikate.
HTTP- und TLS-Versionen
Um bessere Kontrolle über deine API-Aufrufe zu haben, kannst du für die HTTP- und TLS-Versionen zusätzliche Einschränkungen angeben. Weitere Informationen findest du im Knowledge-Base-Artikel HTTP- und TLS-Versionen.
HTTP-Verbindung
Immer wenn ein API-Aufruf erfolgt, verifiziert dein Server standardmäßig automatisch das TLS- oder SSL-Zertifikat. Solltest du die Zertifikatsvalidierung umgehen und jedwede Fehler ignorieren wollen, aktivere einfach diese Option.
Fehlerhandhabung
Auf dem Tab Request ermöglicht dir die Auswahl von Fehlerbehandlung das Ignorieren von Fehlern, die in einem Schritt auftreten. Wenn ein Prüfobjekt einen beliebigen Fehler in einem Schritt entdeckt, überspringt das Prüfobjekt diesen Schritt einfach. Es fährt dann mit den anderen Schritten fort, bis alle Schritte ausgeführt wurden. Weitere Informationen findest du im Knowledge-Base-Artikel Fehlerbehandlung.
Vault Items verwenden
Die Vault ist ein zentraler Speicherort, in dem du Anmeldedaten und andere sensible Daten, die du in deinen Prüfobjekteinrichtungen nutzt, speichern und verwalten kannst.
Nehmen wir an, du möchtest anhand bestimmter Benutzernamen und Passwörter eine Authentifizierung durchführen, wenn du eine Abfrage an den Server sendest. Nutze einfach ein Vault Item wie ein Vault Credential Set als Teil des Request Bodys und Request Headers. Alternativ kannst du auch, wie bereits erwähnt, das Feld Authentifizierung verwenden.
Um ein Vault Item zu nutzen, setze die folgende Syntax ein, abhängig vom erforderlichen Wert:
- Benutzername:
{{@VaultItem.<itemGuid>.Username}} - Passwort:
{{@VaultItem.<itemGuid>.Password}}
Die <itemGuid> findest du, wenn du im Menü aufrufst und ein bestimmtes Vault Item auswählst. Kopiere aus der URL den Wert nach VaultItemGuid=. Zum Beispiel 91303546-79e1-4f62-9b62-8973323dfe3b aus https://app.uptrends.com/report/VaultItem?VaultItemGuid=91303546-79e1-4f62-9b62-8973323dfe3b.
Wie im Bild zu sehen, wurden Benutzername und Passwort als ein Vault Credential Set abgerufen. Beide wurden in den Definitionen von URL, Request Header und Request Body verwendet.
Vault Items als Datei-Upload verwenden
Multi-Step API-Prüfobjekte ermöglichen dir, Dateien aus der Vault als Teil der Abfragedefinition hochzuladen.
Um eine Datei aus der Vault hochzuladen, führe diese Schritte aus:
- Wähle unter Request > Request Body eine der folgenden Optionen:
- Lade eine Datei hoch (als Form-Data)
- Lade eine Datei hoch (als Binary)
- Multipart Form
- Klicke auf Füge Datei aus Vault hinzu.
- Wähle die entsprechende, in der Vault gespeicherte Datei aus.
- Klicke auf , um die Datei hinzuzufügen.
Die Datei wurde hinzugefügt. Es ist nicht nötig, Request Header anzugeben, da einige Header wie Content-Type: multipart/form-data automatisch hinzugefügt und mit den korrekten Werten versehen wurden.
Du kannst prüfen, ob der Datei-Upload erfolgreich war, indem du einen Test des Prüfobjekts ausführst. Das Ergebnis wird unter Request Header und Inhalt angezeigt:
Eigene Skripte
Sowohl der Request- als auch Response-Teil eines Schritts können optional anhand von benutzerdefinierten Skripten auf den Tabs Vor-Anfrage und Nach-Antwort erweitert werden. Damit kannst du Skripte in JavaScript ausführen, um benutzerdefinierte Programme umzusetzen und eingehende Funktionstests abzuwickeln. Neben der vollen Bandbreite, die Standard-JavaScript bietet, kannst du auch Schnipsel einsetzen. Das sind vordefinierte Skripte von Uptrends, um die korrekte Funktionsweise und das Verhalten deiner APIs zu prüfen.