Política IntegrationCallout

Esta página se aplica à Apigee e à Apigee híbrida.

Ícone da política

Visão geral

Com a política IntegrationCallout, você executa uma Application Integration que tem um gatilho de API. No entanto, antes de realizar uma integração, é preciso executar a política SetIntegrationRequest. A política SetIntegrationRequest cria um objeto de solicitação e disponibiliza o objeto como uma variável de fluxo. O objeto de solicitação tem os detalhes da 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 solicitação para executar a integração. É possível configurar a política IntegrationCallout para salvar a resposta de execução de integração em uma variável de fluxo.

A política IntegrationCallout é útil se você quiser executar a integração no meio do seu fluxo de proxy. Em vez de configurar a política IntegrationCallout, outra possibilidade para executar uma integração é especificar seu endpoint de destino como um endpoint de integração. Para mais informações, consulte IntegrationEndpoint.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

<IntegrationCallout>

Especifica a política IntegrationCallout.

Valor padrão N/A
Obrigatório? Obrigatório
Tipo Tipo complexo
Elemento pai N/A
Elemento filho <DisplayName>
<AsyncExecution>
<Request>
<Response>

A tabela a seguir fornece uma descrição de alto nível dos elementos-filhos de <IntegrationCallout>:

Elemento filho Obrigatório? Descrição
<DisplayName> Opcional Um nome personalizado para a política.
<AsyncExecution> Opcional Especifica se a integração precisa ser executada no modo síncrono ou assíncrono.
<Request> Obrigatório A variável de fluxo que tem o objeto de solicitação criado pela política SetIntegrationRequest.
<Response> Opcional A variável de fluxo para salvar 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

No exemplo a seguir, é mostrada 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 a elementos filhos

Esta seção descreve os elementos filhos de <IntegrationCallout>.

<DisplayName>

Use em conjunto com o atributo name para etiquetar a política no editor de proxy da IU de gestão com um nome diferente e mais natural.

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

Valor predefinido N/A
Obrigatório? Opcional. Se omitir <DisplayName>, é usado o valor do atributo name da política.
Tipo String
Elemento principal <PolicyElement>
Elementos subordinados 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 nem elementos subordinados.

<AsyncExecution>

Especifica o modo para executar a integração. Execute a integração de maneira síncrona ou assíncrona.

Se definido como true, a integração será executada de maneira assíncrona. E se definido como false, a integração será executada de maneira síncrona.

  • Modo assíncrono: quando a solicitação para executar a integração chega ao endpoint, ele retorna imediatamente os IDs de execução da integração, mas inicia a execução da integração no momento especificado pelo elemento <ScheduleTime>. Se você não tiver definido o elemento <ScheduleTime>, a integração será programada para ser executada imediatamente. Mesmo que a integração esteja programada para ser executada imediatamente, a execução pode começar após alguns segundos. Quando a integração começar a ser executada, acontecerá o seguinte:
    • A integração retorna o código de status HTTP 200 OK para que o autor da chamada possa continuar processando.
    • A política IntegrationCallout é concluída.
    Depois de iniciada, a integração terá um limite de tempo máximo de 50 minutos para concluir a execução.
  • Modo síncrono: quando a solicitação para executar a integração atinge o endpoint, ele imediatamente inicia a integração e aguarda a resposta. O tempo máximo para concluir a execução é de dois minutos. Depois de concluir a execução, o endpoint retorna uma resposta com os IDs de execução e outros dados.
Valor padrão false
Obrigatório? Opcional
Tipo Booleano
Elemento pai <IntegrationCallout>
Elemento filho Nenhum

O elemento <AsyncExecution> usa a seguinte sintaxe:

Sintaxe

<AsyncExecution>BOOLEAN</AsyncExecution>

Exemplo

No exemplo a seguir, a execução assíncrona é definida como true:

<AsyncExecution>true</AsyncExecution>

<Request>

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

Valor padrão N/A
Obrigatório? Obrigatório
Tipo String
Elemento pai <IntegrationCallout>
Elemento filho Nenhum

O elemento <Request> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

No exemplo a seguir, o objeto de solicitação é especificado como disponível na variável de fluxo my_request_flow_var:

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

A tabela a seguir descreve os atributos de <Request>:

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

Especifica se o objeto de solicitação precisa ser apagado da memória depois de enviar a solicitação para executar a integração.

  • Se definido como true, a Apigee limpa o objeto de solicitação.
  • Se definido como false, a Apigee não limpa o objeto de solicitação.

Se você não especificar esse atributo, o valor padrão será true e o objeto de solicitação será apagado da memória.

<Response>

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

Se você não especificar esse elemento, a política salvará a resposta na variável de fluxo integration.response.

Valor padrão integration.response
Obrigatório? Opcional
Tipo String
Elemento pai <IntegrationCallout>
Elemento filho Nenhum

A saída da integração pode ser acessada por integration.response.content ou flow_variable.content. O elemento <Response> usa a seguinte sintaxe:

Sintaxe

<Response>FLOW_VARIABLE_NAME</Response>

Exemplo

No exemplo a seguir, a resposta da execução da integração é salva na variável de fluxo my_response_flow_var:

<Response>my_response_flow_var</Response>

Códigos de erro

Esta secção descreve os códigos de falhas, as mensagens de erro e as variáveis de falhas definidas pelo Apigee quando esta política aciona um erro. Estas informações são essenciais se estiver a desenvolver regras de falhas para resolver falhas. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e o artigo Processamento de falhas.

Erros de tempo de execução

Estes erros podem ocorrer quando a política é executada.

Código de falha Estado de HTTP Causa
entities.UnresolvedVariable 500 Este erro ocorre se o Apigee não conseguir resolver as variáveis integration.project.id ou integration.name.
steps.integrationcallout.ExecutionFailed 500

Este erro pode ocorrer se o serviço de destino de back-end devolver um estado de erro HTTP, como 4xx ou 5xx. As causas possíveis incluem:

  • A conta de serviço implementada com o proxy tem as autorizações incorretas para executar a integração.
  • A integração ou o acionador da API não existe.
  • A integração de aplicações não está ativada para o seu projeto do Google Cloud.
  • Configurou o elemento <ScheduleTime> na sua política SetIntegrationRequest e a política IntegrationCallout tem o elemento AsyncExecution definido como false.
steps.integrationcallout.NullRequestVariable 500 Este erro ocorre se a variável de fluxo especificada em <Request> for nula.
steps.integrationcallout.RequestVariableNotMessageType 500 Este erro ocorre quando a variável de fluxo especificada pelo elemento Request não é do tipo message.
steps.integrationcallout.RequestVariableNotRequestMessageType 500 Este erro ocorre quando a variável de fluxo especificada pelo elemento Request não é do tipo mensagem de pedido.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500

Este erro pode ocorrer devido a uma configuração incorreta da conta de serviço. As causas possíveis incluem:

  • A conta de serviço implementada com o proxy não existe no seu projeto.
  • A conta de serviço implementada com o proxy está desativada.

Variáveis de falha

Sempre que existem erros de execução numa política, o Apigee gera mensagens de erro. Pode ver estas mensagens de erro na resposta de erro. Muitas vezes, as mensagens de erro geradas pelo sistema podem não ser relevantes no contexto do seu produto. Pode personalizar as mensagens de erro com base no tipo de erro para tornar as mensagens mais significativas.

Para personalizar as mensagens de erro, pode usar regras de falhas ou a política RaiseFault. Para informações sobre as diferenças entre as regras de falhas e a política RaiseFault, consulte Regras de falhas vs. a política RaiseFault. Tem de verificar as condições através do elemento Condition nas regras de falhas e na política RaiseFault. O Apigee fornece variáveis de falhas exclusivas para cada política, e os valores das variáveis de falhas são definidos quando uma política aciona erros de tempo de execução. Ao usar estas variáveis, pode verificar condições de erro específicas e tomar as medidas adequadas. Para mais informações sobre a verificação das condições de erro, consulte o artigo Criar condições.

A tabela seguinte descreve as variáveis de falha específicas desta política.

Variáveis Onde Exemplo
fault.name O fault.name pode corresponder a qualquer uma das falhas indicadas na tabela Erros de tempo de execução. O nome da falha é a última parte do código de falha. fault.name Matches "UnresolvedVariable"
IntegrationCallout.POLICY_NAME.failed POLICY_NAME é o nome especificado pelo utilizador da política que gerou a falha. IntegrationCallout.integration-callout-1.failed = true
Para mais informações sobre erros de políticas, consulte o artigo O que precisa de saber sobre erros de políticas.

Temas relacionados

Para saber mais sobre o recurso de integração de aplicativos, consulte Visão geral da integração de aplicativos.