FlowCallout-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Verwenden Sie die FlowCallout-Richtlinie, um einen freigegebenen Ablauf von einem API-Proxy oder einem anderen freigegebenen Ablauf aus aufzurufen.

In einem freigegebenen Ablauf erstellen Sie eine Reihe von Schritten, die Sie bei der Ausführung an verschiedenen Orten wiederverwenden können. Diese Schritte werden wie Richtlinien als API-Proxy implementiert. Mit der FlowCallout-Richtlinie können Sie den freigegebenen Ablauf von API-Proxys und anderen freigegebenen Abläufen aufrufen. Sie funktioniert wie Funktionsaufrufe in einer herkömmlichen Programmiersprache.

• Angenommen, Sie haben einen freigegebenen Ablauf mit Sicherheitsfunktionen wie API-Schlüsselüberprüfung, OAuth-Token-Validierung und Schutz vor regulären Ausdrücken erstellt. Dieser gemeinsame Ablauf stellt die Konvention dar, mit der eingehende Anfragen geprüft werden können. Mit den FlowCallout-Richtlinien können Sie diesen freigegebenen Ablauf von mehreren API-Proxys aufrufen.
• Sie können einen freigegebenen Ablauf von einem anderen aufrufen. Dazu implementieren Sie innerhalb eines freigegebenen Ablaufs eine FlowCallout-Richtlinie.

Diese Richtlinie ist eine erweiterbare Richtlinie, deren Verwendung je nach Apigee-Lizenz Auswirkungen auf die Kosten oder die Nutzung haben kann. Informationen zu Richtlinientypen und Auswirkungen auf die Nutzung finden Sie unter Richtlinientypen.

Hinweis: Weitere Informationen zu freigegebenen Abläufen finden Sie unter Wiederverwendbare freigegebene Abläufe. Sie können auch einen freigegebenen Ablauf von außerhalb des API-Proxycodes aufrufen, um die Vorverarbeitung oder die Antwortverarbeitung für alle in einer Umgebung bereitgestellten API-Proxys zu erzwingen. Weitere Informationen finden Sie unter Freigegebene Daten mithilfe eines Ablauf-Hooks anhängen.

Beispiele

API-Schlüssel im freigegebenen Ablauf prüfen

In diesem Beispiel wird ein freigegebener Ablauf verwendet, um allgemeine sicherheitsbezogene Aufgaben auszuführen. Hier wird der API-Schlüssel durch den freigegebenen Ablauf validiert. API-Proxys und andere freigegebene Abläufe können mit der FlowCallout-Richtlinie Aufrufe an diesen freigegebenen Ablauf senden.

Die folgende Definition eines freigegebenen Ablaufs enthält eine Verify-API-Key-Richtlinie, die ausgeführt wird, wenn der freigegebene Ablauf über eine FlowCallout-Richtlinie in einem API-Proxy aufgerufen wird.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SharedFlow name="default">
    <Step>
        <Name>Verify-API-Key</Name>
    </Step>
</SharedFlow>

Die VerifyAPIKey-Richtlinie im vorherigen freigegebenen Ablauf ruft den Schlüsselwert ab und überprüft ihn.

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
    <DisplayName>Verify API Key</DisplayName>
    <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

Die folgende FlowCallout-Richtlinie, die in einem API-Proxy verwendet wird, ruft den vorherigen freigegebenen Ablauf auf, um den API-Schlüssel zu verifizieren. Das freigegebene verify-apikey-shared-Ablauf-Bundle (hier nicht gezeigt) konfiguriert den freigegebenen Ablauf so, wie ein API-Proxy-Bundle einen Proxy konfiguriert.

<FlowCallout async="false" continueOnError="false" enabled="true" name="Auth-Flow-Callout">
    <DisplayName>Auth Flow Callout</DisplayName>
    <SharedFlowBundle>verify-apikey-shared</SharedFlowBundle>
</FlowCallout>

Übergeben Sie Parameter an einen freigegebenen Ablauf

In diesem Beispiel wird veranschaulicht, wie Sie Parameter aus einer FlowCallout-Richtlinie an einen freigegebenen Ablauf übergeben. Dabei ruft eine FlowCallout-Richtlinie einen gemeinsam genutzten Ablauf auf, der zur Ausführung gängiger Stringverarbeitungsfunktionen erforderlich ist. Der freigegebene Ablauf umfasst JavaScript, das seine Eingabe verkettet, seine Eingabe in Kleinbuchstaben einschränkt oder beides. Die FlowCallout-Richtlinie definiert Parameter, die die Eingabe, Ausgabe und die möglichen Aktionen für die Eingabe festlegen.

1. Die Richtlinie String-Handler FlowCallout ruft den freigegebenen Ablauf auf. Dabei werden Parameter übergeben, mit denen die Variable zum Speichern der Ausgabe des freigegebenen Ablaufs, der zu verwendenden freigegebenen Ablaufvorgang und die zu verwendende Eingabe angegeben wird (hier ein String). Literal, kann aber auch eine Ablaufvariable sein. Die Parameter-Elemente geben die Namen und Werte der Variablen an, um die Laufzeit zu erstellen. Der freigegebene Ablauf kann diese Variablen zur Verwendung in ihrem eigenen Code abrufen.

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <FlowCallout async="false" continueOnError="false" enabled="true" name="String-Handler">
     <DisplayName>String Handler</DisplayName>
     <Parameters>
       <Parameter name="input">Gladys Kravitz</Parameter>
       <Parameter name="operations">concatenate tolowercase</Parameter>
       <Parameter name="outputVariable">string.handler.output</Parameter>
     </Parameters>
     <SharedFlowBundle>StringHandler</SharedFlowBundle>
   </FlowCallout>

2. Der folgende freigegebene Ablauf default enthält eine JavaScript-Richtlinie vom Typ SharedStringFunctions, die ausgeführt wird, wenn der freigegebene Ablauf über eine FlowCallout-Richtlinie aufgerufen wird.

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <SharedFlow name="default">
     <Step>
       <Name>SharedStringFunctions</Name>
     </Step>
   </SharedFlow>

3. Die folgende SharedStringFunctions-JavaScript-Richtlinie gibt im freigegebenen Ablauf die SharedStringFunctions.js-JavaScript-Datei mit dem auszuführenden Code an.

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="SharedStringFunctions">
     <DisplayName>SharedStringFunctions</DisplayName> <Properties/>
     <ResourceURL>jsc://SharedStringFunctions.js</ResourceURL>
   </Javascript>

4. Die folgende SharedStringFunctions.js-JavaScript-Datei wird von der SharedStringFunctions-JavaScript-Richtlinie ausgeführt. Dieses Skript ruft Werte aus Variablen ab, die aus FlowCallout-Elementen des Typs Parameter erstellt wurden.

   // Input value from the calling API proxy.
   var handledString = context.getVariable("input");
   // Variable to use for output from this script.
   var outputVariable = context.getVariable("outputVariable");
   // A space-separated list of things to do to the input string.
   // Convert to lower case to handle unintentional capitals in configuration.
   var operation = context.getVariable("operations").toLowerCase();
   
   // If "lowercase" was given as an operation, convert the input to lowercase.
   if (operation.includes("tolowercase")) {
       handledString = handledString.toLowerCase();
   }
   
   // If "concatenate" was given as an operation, concatenate the input.
   if (operation.includes("concatenate")) {
       handledString = handledString.replace(/\s+/g, '');
   }
   // Assign the resulting string to the output variable specified by
   // the calling API proxy.
   context.setVariable(outputVariable, handledString);

5. Die Ausführung fließt von der JavaScript-Richtlinie zurück zum freigegebenen Ablauf und dann zur FlowCallout-Richtlinie im ursprünglichen API-Proxy.

Elementverweis

Die folgenden Elemente und Attribute können Sie für diese Richtlinie konfigurieren:

<FlowCallout async="false" continueOnError="false" enabled="true" name="Flow-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <SharedFlowBundle>thereferencedsharedflowbundle</SharedFlowBundle>
</FlowCallout>

<FlowCallout>-Attribute

<FlowCallout async="false" continueOnError="false" enabled="true" name="Flow-Callout-1">

In der folgenden Tabelle werden Attribute beschrieben, die für alle übergeordneten Richtlinienelemente gelten:

Attribut	Beschreibung	Standard	Presence
name	Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten. Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.	–	Erforderlich
continueOnError	Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten. Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Siehe auch: Fehlerregeln werden NUR im Fehlerzustand ausgelöst (über continueOnError) Umgang mit Fehlern im aktuellen Ablauf	false	Optional
enabled	Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen. Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht erzwungen, selbst wenn sie mit einem Ablauf verknüpft ist.	true	Optional
async	Dieses Attribut wurde verworfen.	false	Verworfen

<DisplayName>-Element

Wird zusätzlich zum Attribut name verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

<DisplayName>Policy Display Name</DisplayName>

Standard	– Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs name der Richtlinie verwendet.
Presence	Optional
Typ	String

<SharedFlowBundle> -Element

Gibt den Namen des gemeinsamen Aufrufs an, der aufgerufen werden soll. Der Wert dieses Elements sollte mit dem Wert des Namensattributs des <SharedFlowBundle>-Elements übereinstimmen.

<SharedFlowBundle/>

Im einfachsten Beispiel geben Sie den Namen des freigegebenen Ablaufs als Wert für dieses Element an. Das heißt, der Wert dieses Elements muss mit dem Attributwert name des freigegebenen Ablaufs übereinstimmen.

<SharedFlowBundle>Shared-Flow-Name</SharedFlowBundle>

Standard	–
Presence	Erforderlich
Typ	–

Attribute

–

<Parameter>-Element

Gibt einen Parameter und einen Wert (oder eine Wertquelle) an, die als Variable an den gemeinsamen Ablauf übergeben werden sollen, der von dieser Richtlinie aufgerufen wird.

Mit einem Parameter können Sie einen Wert (oder eine Variable mit einem Wert) festlegen, die an den von der Richtlinie aufgerufenen freigegebenen Ablauf übergeben wird. Dies ist konzeptionell ähnlich wie die Angabe eines Parameters in einem Funktionsaufruf. Wie bei einem Funktionsparameter kann der Wert eines FlowCallout-Parameters abhängig vom Kontext des freigegebenen Ablaufaufrufs variieren.

FlowCallout-Parameter sind nur während der Ausführung des freigegebenen Ablaufs sichtbar.

Syntax

Sie können dieses Element mit einem der folgenden Syntaxformen verwenden. Wenn Sie einen Literalwert verwenden, hängt das Format des angegebenen Werts vom Code ab, der ihn verwendet.

<!- A literal value in an attribute. --/>
<Parameter name="parameter-name" value='parameter-value' />
<!- A reference to a variable in an attribute. --/>
<Parameter name="parameter-name" ref='source-variable-name' />
<!- A literal value in the element content. --/>
<Parameter name="parameter-name">parameter-value</Parameter>
<!- An reference to an attribute in the element content. --/>
<Parameter name="parameter-name">{source-variable-name}</Parameter>

Beispiel

Richtlinie des Typs String-Handler FlowCallout, die Parameter übergibt, mit denen festgelegt wird, wo die Ausgabe des freigegebenen Ablaufs gespeichert und welche Eingabe verwendet werden soll. Die Parameter-Elemente geben die Namen und Werte der Variablen an, um die Laufzeit zu erstellen. Der freigegebene Ablauf kann diese Variablen zur Verwendung in ihrem eigenen Code abrufen.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<FlowCallout async="false" continueOnError="false" enabled="true" name="String-Handler">
  <DisplayName>String Handler</DisplayName>
  <Parameters>
    <Parameter name="input">Gladys Kravitz</Parameter>
    <Parameter name="outputVariable">string.handler.output</Parameter>
  </Parameters>
  <SharedFlowBundle>StringHandler</SharedFlowBundle>
</FlowCallout>

Standard	–
Presence	Erforderlich
Typ	–

Attribute

Attribut	Beschreibung	Standard	Presence	Typ
name	Der Name der Laufzeitvariable, die mit diesem Parameter erstellt werden soll.	–	Erforderlich	String
ref	Die Variable, die den zur Laufzeit zu verwendenden Wert enthält. Lassen Sie dieses Attribut weg, wenn Sie einen Literalwert angeben, der verwendet werden soll.	–	Optional	String
value	Der Wert, der in der Laufzeitvariable, die mit diesem Parameter erstellt wurde, verwendet werden soll. Lassen Sie dieses Attribut weg, wenn Sie den Namen einer Variable angeben, die die Wertquelle sein soll.	–	Optional	String

<Parameter>-Element

Gibt den Satz von <Parameter>-Elementen an, die als Variablen in den von dieser Richtlinie aufgerufenen freigegebenen Ablauf übergeben werden sollen.

Syntax

<Parameters>
  <Parameter name="parameter-name" value='parameter-value' />
</Parameters>

Standard	–
Presence	Optional
Typ	–

Attribute

–

Schemas

Beispiel: Die neuesten Schemas finden Sie in unseren GitHub-Repository-Beispielen.

Ablaufvariablen

Ablaufvariablen ermöglichen ein dynamisches Verhalten von Richtlinien und Abläufen zur Laufzeit, basierend auf HTTP-Headern, Nachrichteninhalten oder dem Ablaufkontext. Weitere Informationen zu Ablaufvariablen finden Sie in der Variablenreferenz.

Variable	Beschreibung
apigee.edge.sharedflow.name	Umfang: Bei der Ausführung des freigegebenen Ablaufs Typ: String Berechtigung: Lesen Wert des Namensattributs des freigegebenen Ablaufs
apigee.edge.flowhook.name	Bereich: Während der Ausführung des freigegebenen Ablaufs, der an den Ablauf-Hook angehängt ist. Typ: String Berechtigung: Lesen Der Name des Ablauf-Hooks.

Fehlerreferenz

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Use API Monitoring to investigate fault codes and diagnose issues faster.

Fault code	HTTP status	Cause	Fix
flow.SharedFlowNotFound	500	Either the shared flow does not exist, or the shared flow exists but is not deployed.

Deployment errors

N/A

Weitere Informationen

• Gemeinsame Abläufe erstellen: Wiederverwendbare freigegebene Abläufe
• Gemeinsame Abläufe über mehrere Proxys hinweg ausführen: Gemeinsamen Ablauf mit einem Ablauf-Hook anhängen