Multi-Step API-Variablen

Für die ersten Schritte in Bezug auf Variablen empfehlen wir, den Artikel zur Multi-Step API-Antwort zu lesen, um einen Überblick der Kernfunktionen und wichtigen Merkmale zu erhalten.

Dieser Artikel erläutert die unterschiedlichen Variablentypen, die du zur Erfassung und Speicherung von Werten aus der API-Antwort nutzen kannst.

Variablen

In einer mehrstufigen API-Einrichtung werden Variablen verwendet, um Werte aus HTTP-Antworten zu extrahieren und sie vorübergehend für einen späteren Einsatz zu speichern.

Ein Beispiel wäre ein Szenario, bei dem du eine Product ID oder einen API-Schlüssel hast, die oder der im gesamten API-Szenario verwendet werden muss. Es kann sich auch um andere Werte handeln, etwa eine Domain für jede API, die du einmal festlegen und dann über mehrere Schritte wiederverwenden möchtest. In diesem Fall erstellst du eine Variable namens BaseUrl mit dem Wert https://test.yourapi.com. Beziehe dich dann auf diese Variable in deinen API URLs, zum Beispiel {{BaseUrl}}/UserService/GetUserInfo oder {{BaseUrl}}/UserService/GetProductInfo. Durch Festlegen dieser Variable kannst du leicht zwischen Umgebungen wie der Staging und Produktion wechseln, indem du die Variable änderst, statt jeden einzelnen Schritt zu bearbeiten.

In deartigen Szenarien ermöglichen dir Variablen:

• Informationen aus einer HTTP-Antwort zu extrahieren und diesen speziellen Wert zu nutzen, um die nächste HTTP-Abfrage einzurichten.
• einen Wert einmal zu definieren und ihn in mehreren Schritten des gesamten API-Szenarios wiederzuverwenden.
• einen Variablenwert an einer Stelle zu aktualisieren und diese Änderung automatisch an die nachfolgenden Schritte zu vererben.

Alle in einem Schritt definierten Variablen werden nach Ausführung der HTTP-Abfrage bewertet und die Antwort wird verarbeitet. An diesem Punkt wird der Wert einer durch einen früheren Schritt bestehenden oder von dir vordefinierten Variable überschrieben.

Andernfalls wird eine neue Variable erstellt und der Liste der Variablen hinzugefügt. Diese Liste von Variablen und den zugehörigen Werten wird dann im nächsten Schritt übernommen. Variablen können so oft wie nötig erstellt und wiederverwendet werden.

Variablen definieren

In dem folgenden Beispiel werden zwei Variablen definiert, um den Produktpreis und die Produkt-ID aus der Antwort zu speichern. Ähnlich dem Muster zur Definition von Assertions werden Variablen anhand von drei Feldern bestimmt: Quelle Merkmal Variablenname. Jedes Feld entspricht einem bestimmten Wert und zeigt, wie API-Werte gespeichert und Variablen erstellt werden.

Unten siehst du die Variablenfelder, die du gemäß deinen Monitoring-Anforderungen definieren kannst.

Variablenquelle

Dieses Feld bestimmt den Ursprung bzw. die Datenquelle, die du überprüfen möchtest. Dies kann ein Response Body als JSON, ein Response Body als Text oder ein Attribut aus einer HTTP-Antwort wie beispielsweise Status Code und vieles weitere sein. Weitere Informationen findest du unter Quellen.

Variablenmerkmal

Einige Optionen zur Quelle wie Response Body als JSON und Response Header erfordern, dass du einen bestimmten Inhaltsabgleich vornimmst, um die Antwort weiter zu validieren. Wenn du bestimmte Daten aus der Antwort prüfen möchtest, musst du den genauen Merkmalswert gemäß dem Quelltyp angeben. Im Beispiel oben ist [0].ProductId der Merkmalswert.

Weitere Informationen findest du unter Merkmal.

Variablenname

Dieses Feld ist die Kennung, mit der die Variable in jedem Schritt referenziert wird. Nutze zur Verwendung von Variablen die folgende Syntax: {{VariableName}}.

Klicke auf Erfahre mehr, um die Grundlagen eines Schritts zu erkunden.

Variablentypen

Es gibt mehrere Variablentypen, die du je nach Einsatzbereich erstellen kannst.

Vordefinierte Variablen

Unter dem Schritte-Editor siehst du einen Bereich, in dem du vordefinierte Variablen eingeben kannst. Diese Variablen werden direkt zu Beginn des gesamten API-Szenarios verfügbar sein. Wenn du einen bestimmten Wert häufiger verwenden musst, kannst du diesen Wert vorher definieren und in unterschiedlichen Schritten nutzen.

Wie im Bild zu sehen, kannst du die Variable {{BaseUrl}} verwenden, um unterschiedliche Endpunkte für jeden Schritt anzusteuern, zum Beispiel mit {{BaseUrl}}/Products und {{BaseUrl}}/Status. Weitere Informationen findest du im Artikel Multi-Step API – Vordefinierte Variablen.

Benutzerdefinierter Metrikvariablen

Erfasst dein Multi-Step API-Prüfobjekt Daten von deinen APIs, kann es sein, dass du numerische Werte überwachen möchtest, die nicht Teil der Standardmetriken sind. Du möchtest vielleicht weitere benutzerdefinierte Werte neben dem Status Code, Antwortdauer und den anderen Standardwerten verwenden, um das Verhalten deiner API besser einschätzen zu können.

Benutzerdefinierte Metrikvariablen ermöglichen dir, eine eigene Variable zu erzeugen, um numerische Daten, die von der API-Antwort erfasst wurden, zu speichern. Dies ist hilfreich, wenn du dein Produktbestand, Verkauf und weiteres überwachen möchtest.

Weitere Informationen findest du im Artikel Benutzerdefinierte Metriken.

Automatische Variablen

Abgesehen von den Variablen, die in der Prüfobjekteinrichtung definiert werden, hast du auch Zugang zu einer Anzahl automatischer Variablen, die wir für dich erzeugt haben. Diese Variablen sind bereits eingerichtet, um Werte zu erzeugen, die du in den HTTP-Abfragen und während der Bewertung von HTTP-Antworten anhand von Assertions nutzen kannst. Beispiele von automatischen Variablen sind {{@DateTime(format,offset)}} und {{@RedirectUrl}}.

Weitere Informationen findest du im Artikel Automatische Variablen.

Benutzerdefinierte Funktionen

In einigen Fällen müssen die von einer API-Antwort extrahierten Werte umgewandelt und gegen ein bestimmtes Format gemappt werden, bevor sie genutzt werden können. Das ist hilfreich, wenn du Werte aus einem Array von Zeichenfolgen extrahieren oder einen regulären Ausdruck verwenden möchtest, um einen Dateinamen aus einem Pfad zu lesen. Uptrends bietet dir die Möglichkeit, benutzerdefinierte Funktionen einzurichten, die Variablenwerte aus einem vorherigen Schritt oder aus einer von Uptrends bereitgestellten Systemvariable in einen neuen Wert konvertieren können.

Weitere Informationen findest du im Artikel Benutzerdefinierte Funktionen.

Variablen in anderen Schritten nutzen

Sobald eine Variable erfolgreich abgerufen und geprüft wurde, kann ihr Wert in der Abfragedefinition in folgenden Schritten und innerhalb von Assertions wiederverwendet werden. Du kannst dich auf eine Variable beziehen, in dem du den Variablennamen in doppelte geschwungene Klammern setzt: {{variable-name}}.

Die folgenden Beispiele zeigen, wie du eine Variable in unterschiedlichen Fällen referenzieren kannst:

• In der URL eines Schritts: https://myapi.customer.com/ProductInfo/{{ProductId}}

• In einem Request Header: `“Authorization”: Bearer {{access_token}}

• Im Inhalt des Request Body: { "ProductId": "{{ProductId}}", "Code": "P123456" }

• Im Zielwert einer Assertion. Wenn eine Variable, {{ProductId}}, in einem vorherigen Schritt oder als vordefinierte Variable ausgefüllt wurde, kannst du dies verwenden, um die Antwort und den Variablenwert zu vergleichen:

  Response Body als JSON Products[0].Id"/Name/text() Ist identisch mit {{ProductId}}

• Im Merkmalswert einer Assertion. Hast du eine Variable {{ProductId}}, kannst du dich auf diese Variable in einem JSON-Ausdruck oder einer XPath-Abfrage beziehen, um den Inhalt auszuwählen, den du verifizieren möchtest:

  Response Body als XML //Product[@Id="{{ProductId}}"]/Name/text() Ist identisch mit Chocolate chip cookie

Codierung von Variablenwerten

Abhängig vom „Einsatzort“ der Variablen müssen ihre Werte gelegentlich codiert werden. Codierung bedeutet, dass Sonderzeichen in ein Format konvertiert werden, das für HTTP-Anfragen geeignet ist. In der Regel müssen Variablen, die in einer URL verwendet werden, codiert werden.

Stelle dir vor, du erzeugst eine URL, die einen Namensparameter enthält und du möchtest eine Variable CompanyName verwenden, um den Wert des Parameters anzugeben. Ohne Codierung würde dies so aussehen:

https://my.api.com/GetCompanyInfo?name={{CompanyName}}

Nehmen wir an, dass die Variable CompanyName den Wert Ben & Jerry's enthält. Dieser Wert enthält Leerzeichen und ein kaufmännisches „&“: beide haben eine besondere Bedeutung in einer URL. Ohne Codierung würde nicht der richtige Wert an den Server übermittelt.

Setzt du also zuerst eine codierte Version des Werts ein, wird die Variable in Ben\+%26\+Jerry's konvertiert, was von dem Server wie der ursprüngliche Wert interpretiert wird. Um eine Variable zu codieren, verwende die Funktion {{@UrlEncode(...)}} und setze den vollständigen Variablennamen innerhalb der Klammern ein.

In diesem Fall sollte es folgendermaßen aussehen:

https://my.api.com/GetCompanyInfo?name={{@UrlEncode({{CompanyName}})}}

Wenn eine Variable nur numerische Werte und keine Sonderzeichen enthält, brauchst du die Funktion @UrlEncode nicht zu verwenden. Wir codieren Variablen für URLs im Feld Request Body eines Schritts automatisch, sofern der Header Content-Type auf application/x-www-form-urlencoded gesetzt ist. Andere Inhalte erfordern in der Regel kein URL-Codieren.