Política IntegrationCallout

Esta página se aplica a Apigee y Apigee Hybrid.

ícono de política

Descripción general

La política IntegrationCallout te permite ejecutar una integración de Apigee que tiene un activador de API. Sin embargo, antes de ejecutar una integración, debes ejecutar la política SetIntegrationRequest. La política SetIntegrationRequest crea un objeto de solicitud y hace que el objeto esté disponible para la política IntegrationCallout como una variable de flujo. El objeto de solicitud tiene los detalles de la integración, como el nombre del activador de la API, el ID del proyecto de integración, el nombre de la integración y otros detalles configurados en la política SetIntegrationRequest. La política IntegrationCallout usa la variable de flujo del objeto de solicitud para ejecutar la integración. Puedes configurar la política IntegrationCallout para guardar la respuesta de ejecución de la integración en una variable de flujo.

La política IntegrationCallout es útil si deseas ejecutar la integración en medio de tu flujo de proxy. Como alternativa, en lugar de configurar la política IntegrationCallout, también puedes ejecutar una integración si especificas un extremo de integración como tu extremo de destino. Para obtener más información, consulta IntegrationEndpoint.

Esta política es una política extensible, y el uso de esta puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

Nota: necesitas un token de autenticación para ejecutar la política IntegrationCallout. Sin embargo, no hay un elemento Authentication explícito en la definición de la política. Apigee agrega un token de autenticación a la solicitud de forma interna. Para que la política IntegrationCallout se autentique con éxito, debes implementar el proxy de API con una cuenta de servicio que tenga los roles de IAM necesarios a fin de ejecutar una integración. Si deseas obtener información sobre las funciones necesarias, consulta Funciones de IAM para integraciones. Si deseas obtener más detalles sobre cómo implementar un proxy de API, consulta Implementa en Apigee.

`<IntegrationCallout>`

Especifica la política IntegrationCallout.

Valor predeterminado	N/A
¿Es obligatorio?	Obligatorio
Tipo	Tipo complejo
Elemento principal	N/A
Elementos secundarios	`<DisplayName>` `<AsyncExecution>` `<Request>` `<Response>`

En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <IntegrationCallout>.

Elemento secundario	¿Es obligatorio?	Descripción
`<DisplayName>`	Opcional	Un nombre personalizado para la política
`<AsyncExecution>`	Opcional	Especifica si la integración debe ejecutarse en modo síncrono o asíncrono.
`<Request>`	Obligatorio	La variable de flujo que tiene el objeto de solicitud creado por la política SetIntegrationRequest.
`<Response>`	Opcional	La variable de flujo para guardar la respuesta de la integración.

El elemento <IntegrationCallout> usa la siguiente sintaxis:

Sintaxis

<?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>

Ejemplo

En el siguiente ejemplo, se muestra la definición de la política IntegrationCallout:

<?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>

Este elemento tiene los siguientes atributos que son comunes a todas las políticas:

Atributo	Predeterminada	(obligatorio)	Descripción
`name`	N/A	Obligatorio	El nombre interno de la política. El valor del atributo `name` puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres. De forma opcional, usa el elemento `<DisplayName>` para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.
`continueOnError`	falso	Opcional	Configúralo como `false` para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como `true` para continuar con la ejecución del flujo incluso después de que una política falle. También consulta: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual
`enabled`	true	Opcional	Configúralo como `true` para aplicar la política. Configúralo como `false` para desactivar la política. La política no se aplicará, incluso si permanece conectada a un flujo.
`async`	falso	Obsoleta	Este atributo dejó de estar disponible.

Referencia del elemento secundario

En esta sección, se describen los elementos secundarios de <IntegrationCallout>.

`<DisplayName>`

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

El elemento <DisplayName> es común a todas las políticas.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional. Si omites `<DisplayName>`, se usa el valor del atributo `name` de la política.
Tipo	String
Elemento principal	<`PolicyElement`>
Elementos secundarios	Ninguna

El elemento <DisplayName> usa la siguiente sintaxis:

Sintaxis

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

Ejemplo

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

El elemento <DisplayName> no tiene atributos ni elementos secundarios.

`<AsyncExecution>`

Especifica el modo para ejecutar la integración. Puedes ejecutar la integración de forma síncrona o asíncrona.

Si se configura como true, la integración se ejecuta de forma asíncrona. Si se configura como false, la integración se ejecuta de forma síncrona.

Modo asíncrono: Cuando la solicitud para ejecutar la integración llega al extremo, este muestra de inmediato los ID de ejecución de integración, pero comienza la ejecución de la integración en el momento especificado por el elemento <ScheduleTime>. Si no configuraste el elemento <ScheduleTime>, la integración está programada para ejecutarse de inmediato. Aunque la integración está programada para ejecutarse de inmediato, su ejecución puede comenzar después de unos segundos. Cuando la integración comienza a ejecutarse, se realizan estas dos acciones:
- La integración muestra el código de estado HTTP 200 OK para que el emisor pueda continuar con el procesamiento.
- Se completa la política IntegrationCallout.
Una vez iniciada, la integración tendrá un límite de tiempo máximo de 50 minutos para completar la ejecución.
Modo síncrono: Cuando la solicitud para ejecutar la integración llega al extremo, este comienza de inmediato la ejecución de la integración y espera la respuesta. El límite máximo de tiempo para completar la ejecución es de 2 minutos. Después de terminar la ejecución, el extremo muestra una respuesta con los ID de ejecución y otros datos de respuesta.

Valor predeterminado	falso
¿Es obligatorio?	Opcional
Tipo	Booleano
Elemento principal	`<IntegrationCallout>`
Elementos secundarios	Ninguna

El elemento <AsyncExecution> usa la siguiente sintaxis:

Sintaxis

<AsyncExecution>BOOLEAN</AsyncExecution>

Ejemplo

En el siguiente ejemplo, se establece la ejecución asíncrona en true:

<AsyncExecution>true</AsyncExecution>

`<Request>`

Especifica la variable de flujo que tiene el objeto de solicitud creado por la política SetIntegrationRequest. La política IntegrationCallout envía este objeto de solicitud a Apigee Integration para ejecutar la integración.

Valor predeterminado	N/A
¿Es obligatorio?	Obligatorio
Tipo	String
Elemento principal	`<IntegrationCallout>`
Elementos secundarios	Ninguna

El elemento <Request> usa la siguiente sintaxis:

Sintaxis

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

Ejemplo

En el siguiente ejemplo, se especifica que el objeto de solicitud está disponible en la variable de flujo my_request_flow_var:

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

En la siguiente tabla, se describen los atributos de <Request>:

Atributo ¿Es obligatorio? Tipo Descripción

Atributo	¿Es obligatorio?	Tipo	Descripción
`clearPayload`	Opcional	Booleano	Especifica si el objeto de solicitud debe borrarse de la memoria después de enviar la solicitud para ejecutar la integración. Si se configura como `true`, Apigee borra el objeto de solicitud. Si se configura como `false`, Apigee no borra el objeto de solicitud. Si no especificas este atributo, el valor predeterminado es `true` y el objeto de solicitud se borra de la memoria.

clearPayload

Opcional

Booleano

Especifica si el objeto de solicitud debe borrarse de la memoria después de enviar la solicitud para ejecutar la integración.

Si se configura como true, Apigee borra el objeto de solicitud.
Si se configura como false, Apigee no borra el objeto de solicitud.

Si no especificas este atributo, el valor predeterminado es true y el objeto de solicitud se borra de la memoria.

`<Response>`

Especifica la variable de flujo para guardar la respuesta de la integración.

Si no especificas este elemento, la política guarda la respuesta en la variable de flujo integration.response.

Valor predeterminado	integration.response
¿Es obligatorio?	Opcional
Tipo	String
Elemento principal	`<IntegrationCallout>`
Elementos secundarios	Ninguna

El elemento <Response> usa la siguiente sintaxis:

Sintaxis

<Response>FLOW_VARIABLE_NAME</Response>

Ejemplo

En el siguiente ejemplo, se guarda la respuesta de la integración ejecutada en la variable de flujo my_response_flow_var:

<Response>my_response_flow_var</Response>

Códigos de error

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. Apigee Integrations 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.

Temas relacionados

Si deseas obtener más información sobre la función de integración de Apigee, consulta ¿Qué es la integración de Apigee?