Steuern, wie ein Proxy mit Abläufen ausgeführt wird

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation
weitere Informationen

Jedes Anwendungsprogrammiermodell bietet eine Möglichkeit, den Verarbeitungsablauf zu steuern. In einem API-Proxy erfolgt der Vorgang mit Abläufen. Sie können Abläufen Logik, Bedingungsanweisungen, Fehlerbehandlungen usw. hinzufügen. Mithilfe von Abläufen können Sie steuern, was wann passiert.

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, if 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 unterteilt seinen Code in Code, der mit dem Client des Proxys (Proxyendpunkt) interagiert, und optionalem Code, der gegebenenfalls mit dem Back-End-Ziel des Proxys interagiert (Zielendpunkt).

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-Flows, die der Back-End-Ressource am nächsten sind. Stellt Stellen für die Logik bereit, um eine Anfrage vorzubereiten und dann die Antwort von einer Back-End-Ressource zu verarbeiten. 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:

Anfrage vom HTTP-Client, der über den Proxyendpunkt an den Zielendpunkt auf dem Back-End weitergeleitet wird, 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 wahr ist. 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 Zielendpunkt, an dem das Senden einer Anfrage an ein Back-End-Ziel vorbereitet wird, eignet sich ein PreFlow gut für erste Schritte zur Vorbereitung des Sendens 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.

Hier werden Kontingentbeschränkungen nur dann erzwungen, wenn es sich um eine GET-Anfrage mit dem URI-Muster /issue/** (/issue/ mit beliebigem Code im URI nach dem letzten Schrägstrich) handelt.

<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 AttributionMessage-Richtlinie namens SetResponseHeaders Header der Antwortnachricht fest, bevor Apigee Edge die Antwort an den Client zurücksendet.

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

Code ausführen zu lassen, nachdem der Client die Antwort Ihres Proxys mit einem PostClientFlow erhalten hat

Ein PostClientFlow kann die folgenden Richtlinien enthalten:

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

Wenn Sie einen angeben, wäre ein PostClientFlow der zuletzt auszuführende Fluss, der ausgeführt wird, nachdem eine Antwort an den Client gesendet wurde.

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:

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

Video:In diesem kurzen Video erfährst du, wie du mithilfe der MessageLogging-Richtlinie aus der 4MV4D-Serie (Four Minute Video For Developers) einen PostClientFlow erstellen kannst.

Weitere Informationen finden Sie unter:

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 Remove-API-Key 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>Remove-API-Key</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

Die Apigee Edge-Konsole stellt diese Richtliniensequenz als eine Reihe von Symbolen dar, wobei jedes Symbol eine Richtlinie repräsentiert.

Die Apigee Edge-Konsole stellt diese Richtliniensequenz als eine Reihe von Symbolen dar, wobei jedes Symbol eine Richtlinie repräsentiert. Zu den Symbolen im Anfragepfad gehören: Verify API Key, Remove API Key und Quota

Debugging-Abläufe

Das Apigee Edge Trace-Tool bietet eine grafische Möglichkeit, 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 Tracing-Proxys finden Sie unter Trace-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 ist die Antwort-Stanza von einem PreFlow in einem Zielendpunkt – mit anderen Worten, es ist der Code, der sofort nach Erhalt der Antwort von einem Back-End-Ziel ausgeführt wird. In diesem Beispiel wird ein Fehler ausgegeben, wenn die Antwort vom Ziel nicht 200 (Erfolg) 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.