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 integração com a Apigee 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 Padrão Obrigatório? Descrição
name N/A Valor

O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres.

Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.
continueOnError falso Opcional Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado para a maioria das políticas. Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar. Consulte também:
enabled true Opcional Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo que permaneça vinculada a um fluxo.
async   falso Obsoleto Esse atributo está obsoleto.

Referência a elementos filhos

Esta seção descreve os elementos filhos 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 Nenhuma

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 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 falso
Obrigatório? Opcional
Tipo Booleanos
Elemento pai <IntegrationCallout>
Elemento filho Nenhuma

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 integração da Apigee para executar a integração.

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

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 Nenhuma

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

Nesta seção, descrevemos códigos, mensagens de erro e variáveis de falha definidos pela Apigee quando essa política aciona um erro. Essas informações são essenciais se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

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

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

Esse erro pode ocorrer se o serviço de destino de back-end retornar um status de erro HTTP, como 4xx ou 5xx. Estas são as possíveis causas:

  • A conta de serviço implantada com o proxy tem permissões incorretas para executar a integração.
  • A integração ou o acionador da API não existe.
  • As integrações da Apigee não estão ativadas para o projeto do Google Cloud.
  • Você configurou o elemento <ScheduleTime> na sua política SetIntegrationRequest, e a política IntegrationCallout tem o AsyncExecution definido como false.
steps.integrationcallout.NullRequestVariable 500 Esse erro ocorre se a variável de fluxo especificada no <Request> for nula.
steps.integrationcallout.RequestVariableNotMessageType 500 Esse erro ocorre quando a variável de fluxo especificada pelo elemento Request não é do tipo mensagem.
steps.integrationcallout.RequestVariableNotRequestMessageType 500 Esse erro ocorre quando a variável de fluxo especificada pelo elemento Request não é do tipo Mensagem de solicitação.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500

Esse erro pode ocorrer devido a uma configuração incorreta da conta de serviço. Estas são as possíveis causas:

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

Variáveis de falha

Sempre que houver erros de execução em uma política, a Apigee gerará mensagens de erro. Essas mensagens de erro podem ser visualizadas na resposta de erro. Muitas vezes, as mensagens de erro geradas pelo sistema podem não ser relevantes no contexto do produto. Personalize as mensagens de erro com base no tipo específico para torná-las mais úteis.

Para personalizar as mensagens de erro, use regras de falha ou a política RaiseFault. Para informações sobre as diferenças entre as regras de falha e a política RaiseFault, consulte FaultRules vs. a política RaiseFault. Verifique as condições usando o elemento Condition nas regras de falha e na política RaiseFault. A Apigee fornece variáveis de falha exclusivas para cada política, e os valores das variáveis de falha são definidos quando uma política aciona erros de ambiente de execução. Ao usar essas variáveis, é possível verificar se há condições de erro específicas e agir conforme adequado. Para mais informações sobre como verificar condições de erro, consulte Como criar condições.

A tabela a seguir descreve as variáveis de falha específicas da política.

Variáveis Onde Exemplo
fault.name O fault.name pode corresponder a qualquer uma das falhas listadas na tabela Erros de ambiente 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 da política especificada pelo usuário que gerou a falha. IntegrationCallout.integration-callout-1.failed = true
Para mais informações sobre erros de política, consulte O que você precisa saber sobre erros de política.

Temas relacionados

Para saber mais sobre o recurso de integração da Apigee, consulte O que é integração da Apigee?.