Ablaufvariablen verwenden

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

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

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, wenn eine Anfrage bei Apigee eingeht
  • Daten, die bei der Ausführung einer Richtlinie abgeleitet werden. Beispiel: Nachdem eine Richtlinie, die ein OAuth-Token validiert, ausgeführt wurde, erstellt Apigee Ablaufvariablen, die Informationen wie den Namen der anfragenden Anwendung enthalten.
  • Informationen zur Antwort vom Zielsystem

Einige Variablen sind in Apigee integriert und werden automatisch jedes Mal ausgefüllt, wenn eine API-Anfrage eingeht. 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- 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 über Apigee zu leiten, ähnlich wie bei einer Switch-Anweisung in der Programmierung.

    Beispiel: Eine Richtlinie, die einen Fehler zurückgibt, kann nur ausgeführt werden, wenn eine bestimmte Ablaufvariable festgelegt wurde.

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 kann vom Wert der aktuellen Kontingentzahl und einer Ablaufvariablen abhängen, die den Namen system.time hat und eine der integrierten Apigee-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 dazu, wann Variablen erstellt werden und zur Verfügung stehen, finden Sie unter Ablauf eines API-Proxys visualisieren.

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 Art der Verwendung von JavaScript zum Lesen und Festlegen von Variablen ähnelt der Arbeit mit der AssignMessage-Richtlinie (siehe oben). Dies ist nur eine weitere Möglichkeit zur Ausführung der gleichen Aufgaben in Apigee. Beachten Sie, dass von der JavaScript-Richtlinie ausgeführtes JavaScript Zugriff auf alle vorhandenen Ablaufvariablen hat, die sich im Bereich des API-Proxy-Ablaufs befinden.

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.

Eine HTTP-Clientanfrage wird über einen API-Proxy an den HTTP-Dienst gesendet und die Antwort wird dann über den API-Proxy an den Client zurückgegeben.

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 Apigee-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 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

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.

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 das Debug-Tool verwenden, um beispielsweise 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 die Richtlinie „ExtractVariables” 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 Apigee 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 oder festlegen, die Sie mit der JavaCallout-Richtlinie ausführen.

Wichtige Hinweise

Beachten Sie bei Ablaufvariablen Folgendes:

  • Einige out-of-the-box 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 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.

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.