API-Proxys mit Abläufen steuern

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Abläufe sind die grundlegenden Bausteine von API-Proxys. Mit Abläufen können Sie das Verhalten einer API programmieren, indem Sie die Sequenz konfigurieren, in der Richtlinien und Code von einem API-Proxy ausgeführt werden.

Abläufe sind sequenzielle Phasen entlang des Pfades, in dem die API-Anfragen verarbeitet werden. Wenn Sie eine Proxylogik hinzufügen, z. B. zum Bestätigen eines API-Schlüssels, fügen Sie die Logik als Schritt in der von einem Ablauf angegebenen Reihenfolge hinzu. Wenn Sie eine Bedingung definieren, um festzulegen, ob und wann die Logik ausgeführt wird, fügen Sie die Bedingung einem Ablauf hinzu.

Im folgenden Beispiel einer Ablaufkonfiguration wird ein Ablauf definiert, in dem die VerifyAPIKey-Richtlinie ausgeführt wird, wenn der eingehende Anfragepfad mit / endet und das HTTP-Verb der Anfrage GET ist.

<Flow name="Get Food Carts">
    <Description>Get Food Carts</Description>
    <Request>
        <Step>
            <Name>Verify-API-Key</Name>
        </Step>
    </Request>
    <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

Der Wert Verify-API-Key im Element <Name> des Ablaufs stellt eine Richtlinie bereit, die an anderer Stelle im Proxy mit XML konfiguriert ist. Beispiel:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
    <DisplayName>Verify API Key</DisplayName>
    <Properties/>
    <APIKey ref="request.header.x-api-key"/>
</VerifyAPIKey>

Ablaufausführungsreihenfolge entwerfen

Sie strukturieren Abläufe so, dass Logik in der richtigen Sequenz entlang des Verarbeitungspfads ausgeführt wird.

Entscheiden Sie zuerst, ob die Logik einem Proxy-Endpunkt oder einem Ziel-Endpunkt hinzugefügt werden soll. Ein API-Proxy teilt seinen Code in Code auf, der mit dem Proxy-Client (Proxy-Endpunkt) interagiert, und optionalen Code, der mit dem Back-End-Ziel des Proxys interagiert (sofern vorhanden).

Beide Endpunkte enthalten Abläufe, wie hier beschrieben:

Endpunkttyp	Beschreibung	Unterstützte Flows
ProxyEndpoint	Enthält die API-Proxy-Abläufe, die dem Client am nächsten sind. Bietet Platz für die Logik, die als Erstes auf die Anfrage des Clients angewendet wird, und zuletzt auf die Antwort an den Client.	PreFlow, bedingte Abläufe, PostFlow, PostClientFlow
TargetEndpoint	Enthält die API-Proxy-Abläufe, die der Back-End-Ressource am nächsten sind. Stellt Platz für die Logik zur Vorbereitung einer Anfrage und Verarbeitung der Antwort aus einer Back-End-Ressource bereit.	PreFlow, bedingte Abläufe, PostFlow

Sie konfigurieren den Ablauf mit XML-Code, der angibt, was in welcher Reihenfolge geschieht. Die folgende Abbildung zeigt, wie Abläufe innerhalb eines Proxy-Endpunkts und eines Ziel-Endpunkts sequenziell geordnet werden:

Die Anfrage vom HTTP-Client wird vom Proxy-Endpunkt an den TargetEndpoint im Back-End weitergeleitet, um den HTTP-Dienst zu erreichen. Jeder Anfrage- und Antwortbereich zeigt den PreFlow, bedingte Abläufe und den PostFlow. Darüber hinaus werden Beispiele für den Proxy-Endpunkt und den Ziel-Endpunkt bereitgestellt.

Der Proxy-Endpunkt und der Ziel-Endpunkt enthalten jeweils Abläufe, die Sie in der folgenden Reihenfolge anordnen können:

Position	Ablauftyp	Beschreibung
1	PreFlow	Dieser Ablauf ist hilfreich, wenn Sie dafür sorgen müssen, dass bestimmter Code ausgeführt wird, bevor irgendetwas anderes geschieht. Befindet sich der PreFlow in einem Ziel-Endpunkt, wird er nach dem PostFlow des Proxy-Endpunkts ausgeführt.
2	Bedingter Ablauf	Die Stelle für bedingte Logik. Sie wird nach dem PreFlow und vor dem PostFlow ausgeführt. Pro Segment wird nur ein bedingter Ablauf ausgeführt – der erste Ablauf, dessen Bedingung als "true" ausgewertet wird. Das bedeutet, dass Sie für jede der folgenden Pipelines einen bedingten Ablauf ausführen können: Anfragepipeline des Proxy-Endpunkts Anfragepipeline des Ziel-Endpunkts Antwortpipeline des Proxy-Endpunkts Antwortpipeline des Ziel-Endpunkts
3	PostFlow	Eine gute Stelle, um Daten zu protokollieren, eine Benachrichtigung zu senden, dass etwas während der Verarbeitung der Anfrage passiert ist, usw. Er wird nach bedingten Abläufen und dem PreFlow ausgeführt. Wenn sich der PostFlow in einem Proxy-Endpunkt befindet und es einen Ziel-Endpunkt gibt, wird der Proxy-Endpunkt-PostFlow vor dem Ziel-Endpunkt-PreFlow ausgeführt.
4	PostClientFlow (nur Proxy-Ablauf)	Ein Ablauf für das Logging von Nachrichten, nachdem eine Antwort an den Client zurückgegeben wurde.

Code mit einem PreFlow zuerst ausführen

Ein PreFlow ist hilfreich, wenn Sie dafür sorgen müssen, dass bestimmter Code ausgeführt wird, bevor irgendetwas anderes geschieht.

In einem Proxy-Endpunkt eignet sich ein PreFlow hervorragend für Code, mit dem ein Client authentifiziert und Traffic von Clients begrenzt wird. In einem Ziel-Endpunkt, wo die Vorbereitung zum Senden einer Anfrage an ein Back-End-Ziel beginnt, eignet sich ein PreFlow für die ersten Schritte zum Senden der Anfrage.

Beispielsweise möchten Sie normalerweise keinen Client bedienen, der sein Kontingent überschritten hat. Fügen Sie Sicherheits- und Kontingentrichtlinien in das PreFlow-Segment ein, um diese Anforderungen zu erfüllen. Auf diese Weise müssen Sie sich keine Gedanken darüber machen, dass eine Bedingung in einem späteren bedingten Ablauf nicht ausgewertet wird. Die Richtlinien in diesem Ablauf werden immer ausgeführt, bevor eine andere Verarbeitung stattfindet.

Im folgenden Beispiel werden SpikeArrest- und Kontingent-Richtlinien ausgeführt, bevor die Verarbeitung von bedingten Abläufen beginnt.

<PreFlow name="MyPreFlow">
    <Request>
        <Step>
            <Name>Spike-Arrest</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
</PreFlow>

Code mit einem bedingten Ablauf bedingt ausführen

Sie können zwischen einem PreFlow und einem PostFlow bedingte Abläufe ausführen. Dadurch haben Sie die Möglichkeit, mehrere Logiksequenzen zu konfigurieren, aber nur eine Logik basierend auf dem Proxy-Status auszuführen. Ein bedingter Ablauf ist optional, wenn Sie die gesamte Logik in PreFlow oder PostFlow ausführen können und keine Bedingungen erforderlich sind (mit anderen Worten, nur ein Pfad durch den Endpunkt wird unterstützt).

In jedem Ablauf wird eine Bedingung angegeben, mit der verschiedene Statuswerte getestet werden. Dies führt zu einer effizienten Ausführung auf der Grundlage von Bedingungen. Vielleicht möchten Sie XML nur in das JSON-Format konvertieren, wenn die Anfrage-App auf einem Mobilgerät ausgeführt wird.

Kontingentbeschränkungen werden nur dann umgesetzt, wenn die Anfrage eine GET-Anfrage mit dem URI-Muster /issue/** ist (/issue/ mit einem beliebigen Wert im URI nach dem letzten Schrägstrich).

<Flow name="MyFlow">
    <Description/>
    <Request>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/issue/**") and (request.verb = "GET")</Condition>
</Flow>

Bedingungen werden mit Ablaufvariablen angegeben. Weitere Informationen zur Verwendung von Variablen in Bedingungen finden Sie unter Bedingungen mit Ablaufvariablen.

Beispiele für die Verwendung eines Musterabgleichs in Bedingungen finden Sie unter Musterabgleich.

Code mit einem PostFlow nach der Kernlogik ausführen

Ein PostFlow ist ein guter Ausgangspunkt für Aktionen nach der Kernlogik des Endpunkts und vor Abschluss der Endpunktverarbeitung. PostFlow wird nach bedingten Abläufen und PreFlow ausgeführt.

Ein PostFlow ist eine gute Stelle, um einige Daten zu protokollieren, eine Benachrichtigung zu senden, dass etwas passiert ist, das Antwortnachrichtenformat umzuwandeln usw.

Im folgenden Beispiel legt eine AssignMessage-Richtlinie namens „SetResponseHeaders“ Header der Antwortnachricht fest, bevor Apigee die Antwort an den Client sendet.

<PostFlow>
    <Response>
        <Step>
            <Name>SetResponseHeaders</Name>
        </Step>
    </Response>
 </PostFlow>

Wenn Code ausgeführt wird, nachdem der Client die Antwort Ihres Proxys mit einem PostClientFlow empfangen hat

Ein PostClientFlow kann nur die folgenden Richtlinien enthalten: In der automatischen Vervollständigung können nur Strings verwendet werden:

^* Die FlowCallout-Richtlinie kann nur gemeinsam genutzte Abläufe aufrufen, die selbst die Kriterien für die Verwendung in PostClientFlow erfüllen (d. h. nur kompatible Richtlinien enthalten).

Würden Sie eine einbinden, wäre PostClientFlow der letzte auszuführende Ablauf, der nach dem Senden einer Antwort an den Client ausgeführt wird.

Ein PostClientFlow ist für das endgültige Logging geeignet. Außerdem können Sie die Start- und Endzeitstempel der Antwortnachricht protokollieren.

Hier ein Beispiel für einen PostClientFlow mit angehängter Nachrichten-Logging-Richtlinie:


  <ProxyEndpoint name="endpoint1">
    ...
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <PostClientFlow>
        <Response>
            <Step>
                <Name>Message-Logging-1</Name>
            </Step>
        </Response>
    </PostClientFlow>
    ...
  </ProxyEndpoint>

Weitere Informationen finden Sie unter Referenz zur API-Proxy-Konfiguration.

Logik zu Abläufen hinzufügen

Um Ihrem Proxy Logik hinzufügen, fügen Sie den Abläufen Ihres Proxys Richtlinien hinzu. Genau wie Abläufe in einer Sequenz ausgeführt werden (PreFlow, dann Flow, dann PostFlow, wie in diesem Thema beschrieben), wird der Inhalt eines Ablaufs in einer Sequenz ausgeführt.

Die folgende Beispielkonfiguration für einen Ablauf verweist auf drei Richtlinien, die an anderer Stelle in den dazugehörigen XML-Dateien konfiguriert sind. Die von Verify-API-Key referenzierte Richtlinie wird vor der von Assign-Message referenzierten Richtlinie ausgeführt. Auf beide folgt die Richtlinie, die durch Quota dargestellt ist.

<Flow name="Get Food Cart Menus">
  <Description>Get Food Cart Menus</Description>
  <Request>
    <Step>
      <Name>Verify-API-Key</Name>
    </Step>
    <Step>
      <Name>Assign-Message</Name>
    </Step>
    <Step>
      <Name>Quota</Name>
    </Step>
  </Request>
  <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

Hinweis: Im obigen Code ist die Pfadbedingung (proxy.pathsuffix MatchesPath "/") immer „true”, da "/" immer zugeordnet ist. Sie können es einfach aus dem Element Bedingung entfernen und die Verbbedingung verwenden:

    <Condition>request.verb = "GET"</Condition>

Debugging-Abläufe

Das Debugging-Tool bietet eine grafische Möglichkeit, um zu sehen, wie die Logik in Ihrem API-Proxy nach einer Anfrage ausgeführt wird. Das Tool veranschaulicht die Verarbeitung zwischen Anfrage und Antwort. Die Trennung zwischen PreFlow, bedingten Abläufen und PostFlow wird nicht extra veranschaulicht.

Weitere Informationen zu Debugging-Proxys finden Sie unter Debugging-Tool verwenden.

Fehler in Abläufen verarbeiten

Fehler können an verschiedenen Stellen in einem API-Proxy ausgelöst werden, auch in Abläufen.

Das folgende Beispiel zeigt die Antwort-Stanza von einem PreFlow in einem Zielendpunkt, also den Code, der sofort ausgeführt wird, nachdem die Antwort von einem Back-End-Ziel empfangen wurde. In diesem Beispiel wird ein Fehler ausgegeben, wenn die Antwort vom Ziel nicht 200 (erfolgreich) ist.

<PreFlow name="PreFlow">
    <Response>
        <Step>
            <Name>RaiseFault</Name>
            <Condition>(response.status.code GreaterThan "200")</Condition>
        </Step>
    </Response>
</PreFlow>

Weitere Informationen zur Fehlerbehandlung finden Sie unter Umgang mit Fehlern.