IntegrationCallout-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Richtliniensymbol

Übersicht

Mit der IntegrationCallout-Richtlinie können Sie eine Application 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>

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError false Optional Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also:
enabled true Optional Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

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 Keine

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 false
Erforderlich? Optional
Typ Boolesch
Übergeordnetes Element <IntegrationCallout>
Untergeordnete Elemente Keine

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

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

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? Typ Beschreibung
clearPayload Optional boolean

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 Keine

Auf die Ausgabe der Integration kann über integration.response.content oder flow_variable.content zugegriffen werden. 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

This section describes the fault codes, error messages, and the fault variables set by Apigee when this policy triggers an error. This information is essential 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.

Fault code HTTP status Cause
entities.UnresolvedVariable 500 This error occurs if Apigee cannot resolve the integration.project.id or the integration.name variables.
steps.integrationcallout.ExecutionFailed 500

This error can occur if the backend target service returns an HTTP error status such as 4xx or 5xx. The possible causes include:

  • The service account deployed with the proxy has the incorrect permissions to run the integration.
  • The integration or the API trigger does not exist.
  • Application Integration is not enabled for your Google Cloud project.
  • You have configured the <ScheduleTime> element in your SetIntegrationRequest policy and the IntegrationCallout policy has the AsyncExecution set to false.
steps.integrationcallout.NullRequestVariable 500 This error occurs if the flow variable specified in the <Request> is null.
steps.integrationcallout.RequestVariableNotMessageType 500 This error occurs when the flow variable specified by the Request element is not of message type.
steps.integrationcallout.RequestVariableNotRequestMessageType 500 This error occurs when the flow variable specified by the Request element is not of Request message type.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500

This error can occur because of an incorrect service account configuration. The possible causes include:

  • The service account deployed with the proxy does not exist in your project.
  • The service account deployed with the proxy is disabled.

Fault variables

Whenever there are execution errors in a policy, Apigee generates error messages. You can view these error messages in the error response. Many a time, system generated error messages might not be relevant in the context of your product. You might want to customize the error messages based on the type of error to make the messages more meaningful.

To customize the error messages, you can use either fault rules or the RaiseFault policy. For information about differences between fault rules and the RaiseFault policy, see FaultRules vs. the RaiseFault policy. You must check for conditions using the Condition element in both the fault rules and the RaiseFault policy. Apigee provides fault variables unique to each policy and the values of the fault variables are set when a policy triggers runtime errors. By using these variables, you can check for specific error conditions and take appropriate actions. For more information about checking error conditions, see Building conditions.

The following table describes the fault variables specific to this policy.

Variables Where Example
fault.name The fault.name can match to any of the faults listed in the Runtime errors table. The fault name is the last part of the fault code. fault.name Matches "UnresolvedVariable"
IntegrationCallout.POLICY_NAME.failed POLICY_NAME is the user-specified name of the policy that threw the fault. IntegrationCallout.integration-callout-1.failed = true
For more information about policy errors, see What you need to know about policy errors.

Weitere Informationen

Weitere Informationen zur Application Integration finden Sie unter Übersicht über Application Integration.