Ablaufvariablen verwenden

Sie sehen sich die Dokumentation zu Apigee Edge an.
Sehen Sie sich die Apigee X-Dokumentation an. info

Flussvariablen sind konzeptionell Objekte, auf die Sie über Ihre Richtlinien oder Dienstprogramme, z. B. das Trace-Tool, zugreifen können. Dadurch können Sie den Status einer API-Transaktion beibehalten, die von Apigee Edge verarbeitet wird.

Video

Das folgende Video bietet eine Einführung in Ablaufvariablen:

Was sind Ablaufvariablen?

Ablaufvariablen existieren im Kontext eines API-Proxy-Ablaufs und verfolgen den Status in einer API-Transaktion so, wie benannte Variablen den Status in einem Softwareprogramm verfolgen. In Ablaufvariablen werden unter anderem folgende Daten gespeichert:

• Die IP-Adresse, Header, URL-Pfad und Nutzlast, die von der anfordernden Anwendung gesendet wurden
• Systeminformationen wie Datum und Uhrzeit des Empfangs von Edge
• Daten, die bei der Ausführung einer Richtlinie abgeleitet werden. Nach der Ausführung einer Richtlinie, die ein OAuth-Token validiert, erstellt Edge Ablaufvariablen, die Informationen wie den Namen der anfragenden Anwendung enthalten.
• Informationen zur Antwort vom Zielsystem

Einige Variablen sind in Edge "integriert" und werden beim Empfang einer API-Anfrage automatisch ausgefüllt. Sie sind über alle API-Transaktionen verfügbar. Sie können auch eigene benutzerdefinierte Variablen erstellen und dafür Richtlinien wie die AssignMessage-Richtlinie oder in JavaScript-, Node.js- und Java-Code verwenden.

Wie Sie sehen, haben Variablen den Umfang, wo sie zugänglich sind, je nachdem, wann sie im API-Proxy-Flow erstellt werden. Im Allgemeinen ist eine erstellte Variable für alle Richtlinien und Code verfügbar, die später im API-Transaktionsablauf ausgeführt werden.

Wie werden Ablaufvariablen verwendet?

Ablaufvariablen werden in Richtlinien und bedingten Abläufen verwendet:

• Richtlinien können den Status von Ablaufvariablen abrufen und für ihre Arbeit verwenden.

  Zum Beispiel kann mit einer VerifyJWT-Richtlinie das zu überprüfende Token aus einer Ablaufvariable abgerufen und dann die Bestätigung dafür durchgeführt werden. Als weiteres Beispiel kann eine JavaScript-Richtlinie Ablaufvariablen abrufen und die in diesen Variablen enthaltenen Daten codieren.

• Bedingte Abläufe können auf Ablaufvariablen verweisen, um den Ablauf einer API durch Edge zu leiten, ähnlich wie eine Switch-Anweisung bei der Programmierung.

  Beispiel: Eine Richtlinie, die einen Fehler zurückgibt, kann nur ausgeführt werden, wenn eine bestimmte Ablaufvariable festgelegt wurde. Schließlich können Sie Ablaufvariablen in einer Node.js-Zielanwendung abrufen und festlegen.

Sehen wir uns Beispiele für die Verwendung von Variablen in jedem dieser Kontexte an.

Ablaufvariablen in Richtlinien

Einige Richtlinien akzeptieren Ablaufvariablen als Eingabe.

Die folgende AssignMessage-Richtlinie verwendet beispielsweise den Wert der Ablaufvariablen client.ip und fügt sie in einen Anfrage-Header namens My-Client-IP ein. Wenn diese Richtlinie dem request-Ablauf hinzugefügt wird, legt diese Richtlinie einen Header fest, der an das Back-End-Ziel weitergeleitet wird. Wenn dieser Vorgang im response-Ablauf festgelegt wird, wird der Header an die Clientanwendung zurückgesendet.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="My-Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Bei einem anderen Beispiel werden bei der Ausführung einer Kontingentrichtlinie mehrere Ablaufvariablen mit richtlinienbezogenen Werten gefüllt. Eine dieser Variablen heißt ratelimit.my-quota-policy.used.count. Dabei ist my-quota-policy der Name der Kontingentrichtlinie, an der Sie interessiert sind.

Sie können später einen bedingten Ablauf ausführen, der besagt: "Wenn die aktuelle Kontingentanzahl unter 50% des Maximalwerts liegt und zwischen 9 und 17 Uhr liegt, erzwingen Sie ein anderes Kontingent." Diese Bedingung hängt möglicherweise vom Wert der aktuellen Kontingentanzahl und von einer Ablaufvariablen namens system.time ab, die eine der integrierten Edge-Variablen ist.

Ablaufvariablen in bedingten Abläufen

Bei bedingten Datenflüssen werden Ablaufvariablen bewertet und Proxys dynamisch ausgeführt. Bedingungen werden üblicherweise verwendet, um das Verhalten von Abläufen, Schritten und Routingregeln zu ändern.

Hier sehen Sie einen bedingten Ablauf, mit dem der Wert der Variablen request.verb in einem Proxyablaufschritt ausgewertet wird. In diesem Fall wird die VerifyAPIKey-Richtlinie ausgeführt, wenn das Anfrage-Verb POST ist. Dies ist ein gängiges Muster, das in API-Proxy-Konfigurationen verwendet wird.

<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Condition>request.verb equals "POST"</Condition>
            <Name>VerifyApiKey</Name>
        </Step>
    </Request>
</PreFlow>

Vielleicht fragen Sie sich, woher die Variablen request.verb, client.ip und system.time stammen? Wann werden sie instanziiert und mit einem Wert gefüllt? Informationen darüber, wann Variablen erstellt werden und wann sie Ihnen zur Verfügung stehen, finden Sie unter Umfang der Ablaufvariablen.

Ablaufvariablen in JavaScript-Code, der mit der JavaScript-Richtlinie aufgerufen wird

Mit der JavaScript-Richtlinie können Sie JavaScript-Code aus dem Kontext eines API-Proxy-Ablaufs ausführen. Von dieser Richtlinie ausgeführte JavaScript verwendet das JavaScript-Objektmodell von Apigee, das Ihren benutzerdefinierten Codezugriff auf Anfrage-, Antwort- und Kontextobjekte ermöglicht, die dem API-Proxy-Flow zugeordnet sind. in der Ihr Code ausgeführt wird. Dieser Code legt beispielsweise einen Antwortheader mit dem Wert fest, der aus der Ablaufvariablen target.name abgerufen wurde.

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));

Diese Technologie verwendet die Verwendung von JavaScript zum Lesen und Festlegen von Variablen ähnelt der Arbeit, die Sie mit der AssignMessage-Richtlinie ausführen können (siehe oben). Dies ist eine weitere Möglichkeit, um dieselben Dinge in Edge zu erreichen. Beachten Sie, dass JavaScript, das von der JavaScript-Richtlinie ausgeführt wird, Zugriff auf alle vorhandenen Ablaufvariablen hat und sich im API-Proxy-Ablauf im scope befinden.

Ablaufvariablen in Node.js-Code

Wenn Sie das Modul apigee-access benötigen, können Sie Flussvariablen über den in Edge bereitgestellten Node.js-Code festlegen und darauf zugreifen.

Hier ein einfaches Beispiel, in dem eine Variable namens custom.foo auf den Wert Bar festgelegt wird. Nach der Festlegung ist diese neue Variable für alle Richtlinien oder anderen Code verfügbar, die im Proxy-Ablauf nach der Ausführung des Node.js-Codes auftreten.

var http = require('http');
var apigee = require('apigee-access');

http.createServer(function (request, response) {
  apigee.setVariable(request, "custom.foo", "Bar");
  response.writeHead(200, {'Content-Type': 'text/plain'});
  response.end('Hello World\n');
}).listen(8124);

console.log('Server running at http://127.0.0.1:8124/');

Weitere Informationen zur Verwendung von apigee-access für die Arbeit mit Variablen finden Sie unter Auf Ablaufvariablen in Node.js zugreifen.

Bereich von Ablaufvariablen

Der Variablenbereich bezieht sich auf den Ablauf oder den gesamten „Lebenszyklus“ eines API-Proxyaufrufs.

Ablauf eines API-Proxys visualisieren

Damit Sie den Umfang von Ablaufvariablen verstehen können, ist es wichtig zu verstehen, wie Nachrichten durch einen API-Proxy geleitet werden. Ein API-Proxy besteht aus einer Reihe von Schritten zur Nachrichtenverarbeitung, die als Ablauf organisiert sind. Bei jedem Schritt in einem Proxy-Ablauf wertet der Proxy die verfügbaren Informationen aus und entscheidet, was als Nächstes zu tun ist. Darüber hinaus kann der Proxy Richtliniencode oder bedingte Zweige ausführen.

Die folgende Abbildung zeigt diese Abfolge von Abläufen. Sie sehen, dass die Abläufe aus vier Hauptsegmenten bestehen: ProxyEndpoint Anfrage , TargetEndpoint Anfrage , TargetEndpoint Antwort und ProxyEndpoint Antwort , um die Option zu aktivieren.

Behalten Sie diese Ablaufstruktur im Hinterkopf, wenn wir beginnen, Ablaufvariablen im weiteren Verlauf dieses Themas zu untersuchen.

Zusammenhang zwischen dem Variablenbereich und dem Proxyablauf

Sobald Sie wissen können, wie Nachrichten durch einen Proxy fließen, wie zuvor beschrieben, können Sie den variablen Umfang verstehen. Der Bereich umfasst den Punkt im Lebenszyklus des Proxyablaufs, wenn eine Variable zum ersten Mal instanziiert wird.

Wenn Sie beispielsweise eine Richtlinie an das ProxyEndpoint-Anfragesegment angehängt haben, kann diese Richtlinie nicht auf Variablen zugreifen, die zum TargetEndpoint-Anfragesegment gehören. Der Grund dafür ist, dass das TargetEndpoint-Anforderungssegment des Ablaufs noch nicht ausgeführt wurde, sodass der API-Proxy keine Variablen in diesem Bereich füllen konnte.

In der folgenden Tabelle werden alle Variablenbereiche aufgeführt und angegeben, wann sie im Proxy-Ablauf verfügbar sind.

Bereich von Variablen	Wo diese Variablen eingetragen werden
Proxyanfrage	Das ProxyEndpoint-Anfragesegment
Zielanfrage	Das TargetEndpoint-Anforderungssegment
Ziel-Antwort	Das TargetEndpoint-Antwortsegment
Proxy-Antwort	Das ProxyEndpoint-Antwortsegment
Immer verfügbar	Sobald der Proxy eine Anfrage erhält. Diese Variablen stehen über den gesamten Lebenszyklus des Proxy-Ablaufs zur Verfügung.

Beispielsweise gibt es eine integrierte Edge-Variable namens client.ip. Diese Variable hat den Bereich "Proxyanfrage". Es enthält automatisch die IP-Adresse des Clients, der den Proxy aufgerufen hat. Sie wird ausgefüllt, wenn eine Anfrage den ProxyEndpoint zum ersten Mal erreicht und bleibt über den gesamten Lebenszyklus des Proxyablaufs verfügbar.

Es gibt eine weitere integrierte Variable namens target.url. Der Umfang dieser Variable lautet "Zielanfrage". Sie wird im TargetEndpoint-Anfragesegment gefüllt, wobei die Anfrage-URL an das Back-End-Ziel gesendet wird. Wenn Sie versuchen, auf das target.url-Anfragesegment im ProxyEndpoint zuzugreifen, erhalten Sie einen NULL-Wert. Wenn Sie versuchen, diese Variable festzulegen, bevor sie im Umfang liegt, erzeugt der Proxy nichts und führt keine Fehlermeldung aus.

Dieses einfache Beispiel zeigt, wie Sie in Bezug auf den Variablenbereich nachdenken. Angenommen, Sie möchten den gesamten Inhalt eines Anfrageobjekts (Header, Parameter, Text) kopieren und der Antwortnutzlast zuweisen, die an die aufrufende Anwendung zurückgesendet werden soll. Sie können die AssignMessage-Richtlinie für diese Aufgabe verwenden. Der Richtliniencode sieht so aus:

<AssignMessage name="CopyRequestToResponse">
    <AssignTo type="response" createNew="false">response</AssignTo>
    <Copy source="request"/>
</AssignMessage>

Diese Richtlinie kopiert einfach das Objekt request und weist es dem response-Objekt zu. Aber wo soll diese Richtlinie im Proxyablauf platziert werden? Die Antwort lautet, dass sie in die TargetEndpoint-Antwort eingefügt werden muss, da der Bereich der Antwortvariable "target response" ist.

Verweisvariablen referenzieren

Alle in Apigee Edge integrierten Variablen folgen einer Namenskonvention für die Punktnotation. Diese Konvention erleichtert den Zweck der Variable. Zum Beispiel: system.time.hour und request.content

Apigee reserviert verschiedene Präfixe, um relevante Variablen entsprechend zu organisieren. Zu diesen Präfixen gehören:

• request
• response
• system
• target

Wenn Sie in einer Richtlinie auf eine Variable verweisen möchten, schließen Sie sie in geschweifte Klammern. Die folgende AssignMessage-Richtlinie verwendet beispielsweise den Wert der Variable client.ip und fügt sie in einen Anfrage-Header namens Client-IP ein.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

In bedingten Abläufen sind die geschweiften Klammern nicht erforderlich. Die folgende Beispielbedingung wertet die Variable request.header.accept aus:

<Step>
    <Condition>request.header.accept = "application/json"</Condition>
    <Name>XMLToJSON</Name>
</Step>

Sie können auch in JavaScript- und Java-Code auf Ablaufvariablen verweisen. Weitere Informationen finden Sie unter:

• Mit Variablen in JavaScript arbeiten
• Auf Ablaufvariablen in Node.js zugreifen
• JavaScript-Richtlinie

Datentyp der Ablaufvariablen

Jedes Attribut einer Ablaufvariable hat einen klar definierten Datentyp, z. B. String, Long, Integer, Boolesch oder Collection. Sie finden die Datentypen in der Referenz zu Ablaufvariablen. Informationen zu Variablen, die von einer Richtlinie erstellt wurden, finden Sie im Thema zu den Richtlinienreferenzen für Datentypinformationen.

Variablen, die Sie manuell erstellen, gehen von dem Typ aus, der bei der Erstellung angegeben wurde und von den zulässigen Werttypen. Variablen, die in Node.js-Code erstellt werden, sind beispielsweise auf „Zahl“, „String“, „Boolescher Wert“, „Null“ oder „Undefiniert“ beschränkt.

Ablaufvariablen in Richtlinien verwenden

Viele Richtlinien erstellen Ablaufvariablen als Teil ihrer normalen Ausführung. In der Richtlinienreferenz werden alle diese richtlinienspezifischen Variablen dokumentiert.

Wenn Sie mit Proxys und Richtlinien arbeiten, sollten Sie in der Richtlinienreferenz nachlesen, welche Variablen erstellt werden und wofür sie verwendet werden. Beispielsweise erstellt die Kontingentrichtlinie eine Reihe von Variablen, die Informationen zur Anzahl der Kontingente und Limits, zur Ablaufzeit usw. enthalten.

Einige Richtlinienvariablen sind für die Fehlerbehebung hilfreich. Sie können beispielsweise das Trace-Tool verwenden, um zu sehen, welche Variablen für eine bestimmte Instanz in einem Proxyablauf festgelegt wurden.

Mit der ExtractVariables-Richtlinie können Sie benutzerdefinierte Variablen mit Daten füllen, die aus Nachrichten extrahiert wurden. Sie können Abfrageparameter, Header und andere Daten extrahieren. Sie können zum Beispiel Anfrage- und Antwortnachrichten mithilfe von Mustern parsen, um bestimmte Daten aus den Nachrichten zu extrahieren.

Im folgenden Beispiel parst Variablen eine Antwortnachricht und speichert bestimmte Daten aus der Antwort. Die Richtlinie erstellt zwei benutzerdefinierte Variablen, geocoderesponse.latitude und geocoderesponse.longitude, und weist ihnen Werte zu.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>response</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
      <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
      <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

Beachten Sie, dass in vielen Richtlinien automatisch Variablen erstellt werden. Sie können auf diese Variablen im Kontext des Proxyablaufs zugreifen und sie werden in der Richtlinienreferenz unter jedem einzelnen Richtlinienthema dokumentiert.

Mit Ablaufvariablen im JavaScript-Code arbeiten

Sie können direkt im JavaScript-Code, der im Kontext eines API-Proxys ausgeführt wird, auf Variablen zugreifen und diese festlegen. Durch das JavaScript-Objektmodell von Apigee hat JavaScript, das in Edge ausgeführt wird, direkten Zugriff auf Proxy-Ablaufvariablen.

Für den Zugriff auf Variablen im JavaScript-Code rufen Sie Getter-/Setter-Methoden für eines der folgenden Objekte auf:

• context
• proxyRequest
• proxyResponse
• targetRequest
• targetResponse

Wie Sie sehen, sind diese Objektreferenzen den bekannten Segmenten des Proxy-Ablaufmodells zugeordnet, wie zuvor unter Ablauf eines API-Proxys visualisieren erläutert.

Das Objekt context entspricht "global" verfügbaren Variablen, wie Systemvariablen. Sie können beispielsweise getVariable() für das Objekt context aufrufen, um das aktuelle Jahr abzurufen:

var year = context.getVariable('system.time.year');

Ebenso können Sie setVariable() aufrufen, um den Wert einer benutzerdefinierten Variable oder für alle schreibbaren vorkonfigurierten Variablen festzulegen. Hier erstellen wir eine benutzerdefinierte Variable namens organization.name.myorg und weisen ihr einen Wert zu.

var org = context.setVariable('organization.name.myorg', value);

Da diese Variable mit dem Objekt context erstellt wird, ist sie für alle Flow-Segmente verfügbar. Dies entspricht im Wesentlichen der Erstellung einer globalen Variablen.

Sie können auch Proxy-Ablaufvariablen in Java-Code abrufen/festlegen, die Sie mit der JavaCallout-Richtlinie ausführen.

Auf Flussvariablen in Node.js-Anwendungen zugreifen

Sie können Ablaufvariablen aus Node.js-Code abrufen, festlegen und löschen, der in Edge bereitgestellt wird. Sie müssen nur das Apigee-Zugriffsmodul in Ihrem Code „verlangen“. Weitere Informationen finden Sie unter Auf Ablaufvariablen in Node.js zugreifen.

Wichtige Hinweise

Beachten Sie bei Ablaufvariablen Folgendes:

• Einige "vorkonfigurierte" Variablen werden vom Proxy selbst instanziiert und automatisch ausgefüllt. Diese sind in der Referenz zu Ablaufvariablen dokumentiert.
• Sie können benutzerdefinierte Variablen erstellen, die im Proxyablauf verwendet werden können. Es ist möglich, Variablen mithilfe von Richtlinien wie AssignMessage-Richtlinien und JavaScript-Richtlinien sowie in Node.js-Code zu erstellen.
• Die Variablen haben einen Umfang. Beispielsweise werden einige Variablen automatisch ausgefüllt, wenn der erste Proxy eine Anfrage von einer Anwendung erhält. Andere Variablen werden im Antwortablaufsegment des Proxys dargestellt. Diese Antwortvariablen bleiben undefiniert, bis das Antwortsegment ausgeführt wird.
• Wenn Richtlinien ausgeführt werden, können sie richtlinienspezifische Variablen erstellen und ausfüllen. In der Dokumentation der einzelnen Richtlinien werden alle relevanten richtlinienspezifischen Variablen aufgeführt.
• Mit bedingten Abläufen werden in der Regel eine oder mehrere Variablen ausgewertet. Informieren Sie sich über Variablen, wenn Sie bedingte Abläufe erstellen möchten.
• Viele Richtlinien verwenden Variablen als Eingabe oder Ausgabe. Möglicherweise wird eine Variable, die von einer Richtlinie erstellt wurde, später von einer anderen verwendet.
• Sie können viele Ablaufvariablen in Node.js abrufen und festlegen, indem Sie JavaScript (und unser JavaScript-Objektmodell) oder die JavaCallout-Richtlinie verwenden, mit der Code in Edge ausgeführt wird.

Verwandte Codebeispiele

API-Proxy-Beispiele sind auf GitHub verfügbar und lassen sich einfach herunterladen und verwenden. Weitere Informationen zum Herunterladen und Verwenden der Beispiele finden Sie unter Beispiel-API-Proxys verwenden. Eine Beschreibung der API-Proxy-Beispiele und ihrer Funktion finden Sie in der Liste der Beispiele.

Beispiele für Proxys, die Variablen und Variablenverarbeitung verwenden:

• Variablen - Veranschaulicht, wie Variablen basierend auf Transport-, JSON- und XML-Nachrichteninhalten extrahiert und festgelegt werden.
• policy-mashup-cookbook: Eine vollständige Anwendung, die zwei Richtlinien miteinander über den Aufruf von zwei öffentlichen APIs aufruft, die Ergebnisse kombiniert und eine angereicherte Antwort für die Clientanwendung generiert. Weitere Informationen zu diesem Beispiel finden Sie unter Richtlinienzusammensetzung verwenden.
• conditional-policy: implementiert eine einfache bedingte Richtlinienerzwingung auf Basis von Variablenwerten.

Weitere Informationen

• Alle Variablen, die automatisch in einen API-Proxy ausgefüllt werden, sind in der Referenz zu Ablaufvariablen aufgeführt. In der Referenz werden auch Typ und Umfang der einzelnen Variablen aufgeführt.
• Wenn Sie wissen möchten, welche Variablen eine bestimmte Richtlinie enthält, lesen Sie das Referenzthema der Richtlinie. Ein Beispiel finden Sie unter Ablaufvariablen in der Referenz zu Kontingentrichtlinien.