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.

Kurzanleitung: Eine vollständige Liste aller Ablaufvariablen und ihrer Attribute finden Sie unter Referenz zu Ablaufvariablen.

Video

Hinweis: Das folgende Video zeigt den klassischen Proxy-Editor in der Apigee-UI. Apigee führt eine neue Version des Proxy-Editors ein, die ein anderes Design als die im Video gezeigte klassische Version hat.

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, 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.

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

Weitere Informationen: Wenn Sie mehr zu Proxy-Abläufen erfahren möchten, finden Sie weitere Informationen unter Abläufe konfigurieren.

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.

Hinweis: Nachdem eine Ablaufvariable innerhalb des vorgegebenen Bereichs ausgefüllt wurde, bleibt sie für den Rest des Proxy-Lebenszyklus verfügbar. Wenn Sie versuchen, auf eine Variable zuzugreifen, die sich noch nicht im Gültigkeitsbereich befindet, erhalten Sie eine Fehlermeldung oder einen NULL-Wert.

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.

Hinweis: Bereiche für alle integrierten Edge-Variablen sind in der Referenz zu Ablaufvariablen aufgeführt.

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.

Hinweis: Es ist möglich, einige Richtlinien zu konfigurieren, die entweder einen Fehler auslösen oder NULL zurückgeben, wenn auf eine nicht definierte Variable zugegriffen wird. Weitere Informationen finden Sie auf den Referenzseiten zu Richtlinien.

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

Best Practice: Google empfiehlt beim Erstellen von benutzerdefinierten Ablaufvariablen die Namenskonvention für Punkte. Es kann nützlich sein, die Punkte zu verwenden, um eine Hierarchie Ihrer benutzerdefinierten Variablen zu organisieren.

Beispielsweise können sich approval.code und approval.status auf eine Genehmigungsfunktion innerhalb des Ablaufs beziehen.

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

• Mit Ablaufvariablen im JavaScript-Code arbeiten
• 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.

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.

Hinweis: Sie können JavaScript von einem Proxy aus mithilfe der JavaScript-Richtlinie aufrufen.

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.

Hinweis: Die Referenz für Ablaufvariablen gibt an, welche Variablen schreibbar sind und welche schreibgeschützt sind. Weitere Informationen finden Sie unter JavaScript-Objektmodell.

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

Hinweis: Sie finden eine Reihe von Beispielen, in denen Variablen auf eine Weise angewendet werden. Suchen Sie nach Einträgen, die die ExtractVariables-Richtlinie verwenden. Diese Methode wird im Allgemeinen zur Verarbeitung von Variablen in einem Proxyablauf 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.