IntegrationCallout-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Richtliniensymbol

Überblick

Mit der IntegrationCallout-Richtlinie können Sie eine Apigee-Integration ausführen, die einen API-Trigger hat. Bevor Sie eine Integration ausführen, müssen Sie jedoch die SetIntegrationRequest-Richtlinie ausführen. Die SetIntegrationRequest-Richtlinie erstellt ein Anfrageobjekt und stellt das Objekt der IntegrationCallout-Richtlinie als Ablaufvariable zur Verfügung. Das Anfrageobjekt enthält Integrationsdetails wie den API-Triggernamen, die Integrations-Projekt-ID, den Integrationsnamen und weitere Details, die in der SetIntegrationRequest-Richtlinie konfiguriert sind. Die IntegrationCallout-Richtlinie verwendet die Ablaufvariable des Anfrageobjekts, um die Integration auszuführen. Sie können die IntegrationCallout-Richtlinie so konfigurieren, dass die Integrationslaufantwort in einer Ablaufvariable gespeichert wird.

Die IntegrationCallout-Richtlinie ist hilfreich, wenn Sie die Integration in der Mitte Ihres Proxyablaufs ausführen möchten. Alternativ können Sie anstelle der IntegrationCallout-Richtlinie auch eine Integration ausführen. Geben Sie dazu einen Integrationsendpunkt als Zielendpunkt an. Weitere Informationen finden Sie unter IntegrationEndpoint.

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

<IntegrationCallout>

Gibt die IntegrationCallout-Richtlinie an.

Standardwert –
Erforderlich? Erforderlich
Typ Komplexer Typ
Übergeordnetes Element –
Untergeordnete Elemente <DisplayName>
<AsyncExecution>
<Request>
<Response>

Die folgende Tabelle enthält eine allgemeine Beschreibung der untergeordneten Elemente von <IntegrationCallout>:

Untergeordnetes Element Erforderlich? Beschreibung
<DisplayName> Optional Ein benutzerdefinierter Name für die Richtlinie.
<AsyncExecution> Optional Gibt an, ob die Integration im synchronen oder asynchronen Modus ausgeführt werden muss.
<Request> Erforderlich Die Ablaufvariable, die das Anfrageobjekt enthält, das von der SetIntegrationRequest-Richtlinie erstellt wurde.
<Response> Optional Die Ablaufvariable zum Speichern der Antwort der Integration.

Das <IntegrationCallout>-Element verwendet die folgende Syntax:

Syntax

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<IntegrationCallout continueOnError="[true|false]" enabled="[true|false]" name=POLICY_NAME>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  <AsyncExecution>BOOLEAN_ASYNC_EXECUTION</AsyncExecution>
  <Request clearPayload="[true|false]">REQUEST_FLOW_VARIABLE_NAME</Request>
  <Response>RESPONSE_FLOW_VARIABLE_NAME</Response>
</IntegrationCallout>

Beispiel

Das folgende Beispiel zeigt die Definition der IntegrationCallout-Richtlinie:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<IntegrationCallout continueOnError="false" enabled="true" name="Integration-Callout">
  <DisplayName>Integration-Callout-1</DisplayName>
  <AsyncExecution>true</AsyncExecution>
  <Request clearPayload="true">my_request_flow_var</Request>
  <Response>my_response_flow_var</Response>
</IntegrationCallout>

Dieses Element hat folgende Attribute, die allen Richtlinien gemeinsam sind:

Attribut Standard Erforderlich? Beschreibung
name - Erforderlich

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.
continueOnError false Optional 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. Weitere Informationen:
enabled wahr Optional Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen. Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht durchgesetzt, selbst wenn sie mit einem Ablauf verknüpft ist.
async   false Verworfen Dieses Attribut wurde verworfen.

Verweis auf untergeordnetes Element

In diesem Abschnitt werden die untergeordneten Elemente von <IntegrationCallout> beschrieben.

<DisplayName>

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

Das Element <DisplayName> ist für alle Richtlinien gleich.

Standardwert –
Erforderlich? Optional. Wenn Sie <DisplayName> weglassen, wird der Wert des Attributs name der Richtlinie verwendet.
Typ String
Übergeordnetes Element <PolicyElement>
Untergeordnete Elemente –

Das <DisplayName>-Element verwendet die folgende Syntax:

Syntax

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Beispiel

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

Das <DisplayName>-Element hat keine Attribute oder untergeordneten Elemente.

<AsyncExecution>

Gibt den Modus an, in dem die Integration ausgeführt werden soll. Sie können die Integration synchron oder asynchron ausführen.

Wenn true festgelegt ist, wird die Integration asynchron ausgeführt. Wenn false festgelegt ist, wird die Integration synchron ausgeführt.

  • Asynchroner Modus: Wenn die Anfrage zum Ausführen der Integration den Endpunkt erreicht, gibt der Endpunkt sofort die Ausführungs-IDs der Integration zurück, startet jedoch die Ausführung der Integration zu dem durch das Element <ScheduleTime> angegebenen Zeitpunkt. Wenn Sie das Element <ScheduleTime> nicht festgelegt haben, wird die Integration sofort ausgeführt. Obwohl die Integration so geplant ist, dass sie sofort ausgeführt wird, kann ihre Ausführung erst nach einigen Sekunden beginnen. Wenn die Integration ausgeführt wird, geschieht Folgendes:
    • Die Integration gibt den HTTP-Statuscode 200 OK zurück, damit der Aufrufer die Verarbeitung fortsetzen kann.
    • Die IntegrationCallout-Richtlinie ist abgeschlossen.
    Nach dem Start hat die Integration ein maximales Zeitlimit von 50 Minuten, um die Ausführung abzuschließen.
  • Synchroner Modus: Wenn die Anfrage zum Ausführen der Integration den Endpunkt erreicht, startet der Endpunkt sofort die Ausführung der Integration und wartet auf die Antwort. Das maximal zulässige Zeitlimit für die Ausführung beträgt 2 Minuten. Nach Abschluss der Ausführung gibt der Endpunkt eine Antwort mit den Ausführungs-IDs und anderen Antwortdaten zurück.
Standardwert falsch
Erforderlich? Optional
Typ Boolesch
Übergeordnetes Element <IntegrationCallout>
Untergeordnete Elemente –

Das <AsyncExecution>-Element verwendet die folgende Syntax:

Syntax

<AsyncExecution>BOOLEAN</AsyncExecution>

Beispiel

Im folgenden Beispiel wird die asynchrone Ausführung auf true gesetzt:

<AsyncExecution>true</AsyncExecution>

<Request>

Gibt die Ablaufvariable an, die das von der SetIntegrationRequest-Richtlinie erstellte Anfrageobjekt hat. Die IntegrationCallout-Richtlinie sendet dieses Anfrageobjekt zum Ausführen der Einbindung an Apigee Integration.

Standardwert –
Erforderlich? Erforderlich
Typ String
Übergeordnetes Element <IntegrationCallout>
Untergeordnete Elemente –

Das <Request>-Element verwendet die folgende Syntax:

Syntax

<Request clearPayload="true">FLOW_VARIABLE_NAME</Request>

Beispiel

Im folgenden Beispiel wird angegeben, dass das Anfrageobjekt in der Ablaufvariable my_request_flow_var verfügbar ist:

<Request clearPayload="true">my_request_flow_var</Request>

In der folgenden Tabelle werden die Attribute von <Request> beschrieben:

Attribut Erforderlich/Optional? Typ Beschreibung
clearPayload Optional Boolesch

Gibt an, ob das Anfrageobjekt aus dem Speicher gelöscht werden soll, nachdem die Anfrage zum Ausführen der Integration gesendet wurde.

  • Wenn true festgelegt ist, löscht Apigee das Anfrageobjekt.
  • Wenn false festgelegt ist, löscht Apigee das Anfrageobjekt nicht.

Wenn Sie dieses Attribut nicht angeben, ist der Standardwert true und das Anfrageobjekt wird aus dem Speicher gelöscht.

<Response>

Gibt die Ablaufvariable zum Speichern der Integrationsantwort an.

Wenn Sie dieses Element nicht angeben, speichert die Richtlinie die Antwort in der Ablaufvariable integration.response.

Standardwert integration.response
Erforderlich? Optional
Typ String
Übergeordnetes Element <IntegrationCallout>
Untergeordnete Elemente –

Das <Response>-Element verwendet die folgende Syntax:

Syntax

<Response>FLOW_VARIABLE_NAME</Response>

Beispiel

Im folgenden Beispiel wird die Antwort der Integrationsausführung in der Ablaufvariable my_response_flow_var gespeichert:

<Response>my_response_flow_var</Response>

Fehlercodes

In diesem Abschnitt werden die Fehlercodes, die Fehlermeldungen sowie die Fehlervariablen beschrieben, die von Apigee festgelegt werden, wenn diese Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

Diese Fehler können bei Ausführung der Richtlinie auftreten.

Fehlercode HTTP-Status Ursache
entities.UnresolvedVariable 500 Dieser Fehler tritt auf, wenn Apigee die Variablen integration.project.id oder integration.name nicht auflösen kann.
steps.integrationcallout.ExecutionFailed 500

Dieser Fehler kann auftreten, wenn der Backend-Zieldienst einen HTTP-Fehlerstatus wie 4xx oder 5xx zurückgibt. Mögliche Gründe:

  • Das mit dem Proxy bereitgestellte Dienstkonto hat die falschen Berechtigungen zum Ausführen der Integration.
  • Die Integration oder der API-Trigger ist nicht vorhanden.
  • Apigee Integrations ist für das Google Cloud-Projekt nicht aktiviert.
  • Sie haben das Element <ScheduleTime> in Ihrer SetIntegrationRequest-Richtlinie konfiguriert und für die IntegrationCallout-Richtlinie ist AsyncExecution auf false festgelegt.
steps.integrationcallout.NullRequestVariable 500 Dieser Fehler tritt auf, wenn die im <Request> angegebene Ablaufvariable null ist.
steps.integrationcallout.RequestVariableNotMessageType 500 Dieser Fehler tritt auf, wenn die vom Request-Element angegebene Ablaufvariable nicht vom Typ Nachricht ist.
steps.integrationcallout.RequestVariableNotRequestMessageType 500 Dieser Fehler tritt auf, wenn die vom Element Request angegebene Ablaufvariable nicht vom Typ Anfragenachricht ist.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500

Dieser Fehler kann aufgrund einer falschen Dienstkontokonfiguration auftreten. Mögliche Gründe:

  • Das mit dem Proxy bereitgestellte Dienstkonto ist in Ihrem Projekt nicht vorhanden.
  • Das mit dem Proxy bereitgestellte Dienstkonto ist deaktiviert.

Fehlervariablen

Wenn in einer Richtlinie Ausführungsfehler auftreten, generiert Apigee Fehlermeldungen. Sie können sich diese Fehlermeldungen in der Fehlerantwort ansehen. Häufig sind vom System generierte Fehlermeldungen im Kontext Ihres Produkts möglicherweise nicht relevant. Sie können die Fehlermeldungen basierend auf dem Fehlertyp anpassen, um die Nachrichten aussagekräftiger zu machen.

Zum Anpassen der Fehlermeldungen können Sie entweder Fehlerregeln oder die RaiseFault-Richtlinie verwenden. Informationen zu Unterschieden zwischen Fehlerregeln und der RaiseFault-Richtlinie finden Sie unter FaultRules-Richtlinie im Vergleich zur RaiseFault-Richtlinie. Prüfen Sie, ob Bedingungen mit dem Element Condition in den Fehlerregeln und in der RaiseFault-Richtlinie verwendet werden. Apigee stellt Fehlervariablen bereit, die für jede Richtlinie eindeutig sind. Die Werte der Fehlervariablen werden festgelegt, wenn eine Richtlinie Laufzeitfehler auslöst. Mit diesen Variablen können Sie nach bestimmten Fehlerbedingungen suchen und entsprechende Maßnahmen ergreifen. Weitere Informationen zum Prüfen von Fehlerbedingungen finden Sie unter Bedingungen erstellen.

In der folgenden Tabelle werden die für diese Richtlinie spezifischen Fehlervariablen beschrieben.

Variablen Wo Beispiel
fault.name Der fault.name kann mit einem der Fehler übereinstimmen, die in der Tabelle Laufzeitfehler aufgeführt sind. Der Fehlername ist der letzte Teil des Fehlercodes. fault.name Matches "UnresolvedVariable"
IntegrationCallout.POLICY_NAME.failed POLICY_NAME ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. IntegrationCallout.integration-callout-1.failed = true
Weitere Informationen zu Richtlinienfehlern finden Sie unter Was Sie über Richtlinienfehler wissen müssen.

Weitere Informationen

Weitere Informationen zum Integrationsfeature von Apigee finden Sie unter Was ist Apigee-Integration?