Política IntegrationCallout

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

A política IntegrationCallout permite-lhe executar uma integração de aplicações que tenha um acionador de API. No entanto, antes de executar uma integração, tem de executar a política SetIntegrationRequest. A política SetIntegrationRequest cria um objeto de pedido e disponibiliza o objeto à política IntegrationCallout como uma variável de fluxo. O objeto de pedido tem os detalhes de integração, como o nome do acionador da API, o ID do projeto de integração, o nome da integração e outros detalhes configurados na política SetIntegrationRequest. A política IntegrationCallout usa a variável de fluxo do objeto de pedido para executar a integração. Pode configurar a política IntegrationCallout para guardar a resposta de execução da integração numa variável de fluxo.

A política IntegrationCallout é útil se quiser executar a integração no meio do fluxo do proxy. Em alternativa, em vez de configurar a política IntegrationCallout, também pode executar uma integração especificando um ponto final de integração como o ponto final de destino. Para mais informações, consulte o artigo IntegrationEndpoint.

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

<IntegrationCallout>

Especifica a política IntegrationCallout.

Valor predefinido N/A
Obrigatório? Obrigatória
Tipo Tipo complexo
Elemento principal N/A
Elementos subordinados <DisplayName>
<AsyncExecution>
<Request>
<Response>

A tabela seguinte apresenta uma descrição geral dos elementos subordinados de <IntegrationCallout>:

Elemento secundário Obrigatório? Descrição
<DisplayName> Opcional Um nome personalizado para a política.
<AsyncExecution> Opcional Especifica se a integração tem de ser executada no modo síncrono ou no modo assíncrono.
<Request> Obrigatória A variável de fluxo que tem o objeto de pedido criado pela política SetIntegrationRequest.
<Response> Opcional A variável de fluxo para guardar a resposta da integração.

O elemento <IntegrationCallout> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

O exemplo seguinte mostra a definição da 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 tem os seguintes atributos comuns a todas as políticas:

Atributo Predefinição Obrigatório? Descrição
name N/A Obrigatório

O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres.

Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.
continueOnError falso Opcional Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também:
enabled verdadeiro Opcional Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça anexada a um fluxo.
async   falso Descontinuado Este atributo foi descontinuado.

Referência de elemento secundário

Esta secção descreve os elementos subordinados de <IntegrationCallout>.

<DisplayName>

Use além do atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de som diferente e mais natural.

O elemento <DisplayName> é comum a todas as políticas.

Valor padrão N/A
Obrigatório? Opcional. Se você omitir <DisplayName>, o valor do atributo name da política será usado
Tipo String
Elemento pai <PolicyElement>
Elemento filho Nenhum

O elemento <DisplayName> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

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

O elemento <DisplayName> não tem atributos ou elementos filhos.

<AsyncExecution>

Especifica o modo de execução da integração. Pode executar a integração de forma síncrona ou assíncrona.

Se estiver definido como true, a integração é executada de forma assíncrona. Se estiver definido como false, a integração é executada de forma síncrona.

  • Modo assíncrono: quando o pedido de execução da integração atinge o ponto final, este devolve imediatamente os IDs de execução da integração, mas inicia a execução da integração na hora especificada pelo elemento <ScheduleTime>. Se não tiver definido o elemento <ScheduleTime>, a integração é agendada para ser executada imediatamente. Embora a integração esteja agendada para ser executada imediatamente, a respetiva execução pode começar após alguns segundos. Quando a integração começa a ser executada, ocorrem as duas seguintes situações:
    • A integração devolve o Código de estado HTTP 200 OK para que o autor da chamada possa continuar o processamento.
    • A política IntegrationCallout é concluída.
    Depois de iniciada, a integração tem um limite de tempo máximo de 50 minutos para concluir a execução.
  • Modo síncrono: quando o pedido de execução da integração atinge o ponto final, este inicia imediatamente a execução da integração e aguarda a resposta. O limite de tempo máximo para concluir a execução é de 2 minutos. Após a conclusão da execução, o endpoint devolve uma resposta com os IDs de execução e outros dados de resposta.
Valor predefinido falso
Obrigatório? Opcional
Tipo Booleano
Elemento principal <IntegrationCallout>
Elementos subordinados Nenhum

O elemento <AsyncExecution> usa a seguinte sintaxe:

Sintaxe

<AsyncExecution>BOOLEAN</AsyncExecution>

Exemplo

O exemplo seguinte define a execução assíncrona como true:

<AsyncExecution>true</AsyncExecution>

<Request>

Especifica a variável de fluxo que tem o objeto de pedido criado pela política SetIntegrationRequest. A política IntegrationCallout envia este objeto de pedido para a solução Application Integration para executar a integração.

Valor predefinido N/A
Obrigatório? Obrigatória
Tipo String
Elemento principal <IntegrationCallout>
Elementos subordinados Nenhum

O elemento <Request> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

O exemplo seguinte especifica que o objeto de pedido está disponível na variável de fluxo my_request_flow_var:

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

A tabela seguinte descreve os atributos de <Request>:

Atributo Obrigatório? Tipo Descrição
clearPayload Opcional booleano

Especifica se o objeto de pedido deve ser limpo da memória após o envio do pedido para executar a integração.

  • Se estiver definido como true, o Apigee limpa o objeto de pedido.
  • Se estiver definido como false, o Apigee não limpa o objeto de pedido.

Se não especificar este atributo, o valor predefinido é true e o objeto de pedido é limpo da memória.

<Response>

Especifica a variável de fluxo para guardar a resposta da integração.

Se não especificar este elemento, a política guarda a resposta na variável de fluxo integration.response.

Valor predefinido integration.response
Obrigatório? Opcional
Tipo String
Elemento principal <IntegrationCallout>
Elementos subordinados Nenhum

O resultado da integração pode ser acedido pelo integration.response.content ou flow_variable.content. O elemento <Response> usa a seguinte sintaxe:

Sintaxe

<Response>FLOW_VARIABLE_NAME</Response>

Exemplo

O exemplo seguinte guarda a resposta da execução da integração na variável de fluxo my_response_flow_var:

<Response>my_response_flow_var</Response>

Códigos de erro

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.

Tópicos relacionados

Se quiser saber mais sobre a funcionalidade Application Integration, consulte o artigo Vista geral da Application Integration