Esta página se aplica à Apigee e à Apigee híbrida.
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 Opcionalmente, use o elemento |
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.
- A integração retorna o código de status HTTP
- 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 você não especificar esse atributo, o valor padrão será |
<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
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
|
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:
|
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 |
Temas relacionados
Para saber mais sobre o recurso de integração da Apigee, consulte O que é integração da Apigee?.