IntegrationCallout 政策

本页面适用于 Apigee 和 Apigee Hybrid。

概览

借助 IntegrationCallout 政策，您可以运行具有 API 触发器的 Apigee 集成。但是，在运行集成之前，您必须先运行 SetIntegrationRequest 政策。SetIntegrationRequest 政策会创建一个请求对象，并将该对象作为流变量提供给 IntegrationCallout 政策。请求对象具有集成详细信息，例如 API 触发器名称、集成项目 ID、集成名称以及 SetIntegrationRequest 政策中配置的其他详细信息。IntegrationCallout 政策使用请求对象的流变量来运行集成。您可以配置 IntegrationCallout 政策，将集成运行响应保存在流变量中。

如果您要在代理流中间运行集成，则 IntegrationCallout 政策非常有用。或者，您也可以通过将集成端点指定为目标端点来运行集成，而不是配置 IntegrationCallout 政策。如需了解详情，请参阅 IntegrationEndpoint。

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

注意：您需要身份验证令牌才能运行 IntegrationCallout 政策。但是，政策定义中没有显式的 Authentication 元素。Apigee 会在后台为请求添加身份验证令牌。要使 IntegrationCallout 政策成功进行身份验证，您必须使用具有运行集成所需的 IAM 角色的服务账号部署 API 代理。如需了解所需角色，请参阅集成的 IAM 角色。如需详细了解如何部署 API 代理，请参阅在 Apigee 上部署。

<IntegrationCallout>

指定 IntegrationCallout 政策。

默认值	不适用
是否必需？	必需
类型	复杂类型
父元素	不适用
子元素	<DisplayName> <AsyncExecution> <Request> <Response>

下表提供了 <IntegrationCallout> 的子元素的简要说明：

子元素	是否必需？	说明
<DisplayName>	可选	政策的自定义名称。
<AsyncExecution>	可选	指定集成必须以同步模式还是异步模式运行。
<Request>	必需	具有 SetIntegrationRequest 政策创建的请求对象的流变量。
<Response>	可选	用于保存集成响应的流变量。

<IntegrationCallout> 元素使用以下语法：

语法

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

示例

以下示例展示了 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>

此元素具有所有政策中常见的以下属性：

属性	默认	是否必需？	说明
name	无	必需	政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。 （可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。
continueOnError	否	可选	设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 true，即使在政策失败后，仍可以继续执行流。另请参阅： 故障规则仅在错误状态下触发（关于 continueOnError） 处理当前流中的故障
enabled	true	可选	设置为 true 可实施政策。 设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。
async	否	已弃用	此属性已弃用。

子元素参考

本部分介绍 <IntegrationCallout> 的子元素。

<DisplayName>

除了用于 name 属性之外，还可用于在管理界面代理编辑器中使用其他更加自然的名称标记政策。

<DisplayName> 元素适用于所有政策。

默认值	不适用
是否必需？	可选。如果省略 <DisplayName>，则会使用政策的 name 属性的值
类型	字符串
父元素	<PolicyElement>
子元素	无

<DisplayName> 元素使用以下语法：

语法

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

示例

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

<DisplayName> 元素没有属性或子元素。

<AsyncExecution>

指定用于运行集成的模式。您可以同步或异步运行集成。

如果设置为 true，则集成会异步运行。如果设置为 false，则集成会同步运行。

• 异步模式：当运行集成的请求到达端点时，端点会立即返回集成执行 ID，但会在 <ScheduleTime> 元素指定的时间开始执行集成。如果您尚未设置 <ScheduleTime> 元素，则安排立即运行集成。即使计划立即运行，其集成也可能在几秒钟后开始。集成开始执行时，会发生以下两种情况：
  • 集成会返回 HTTP 200 OK 状态代码，以便调用方可以继续处理。
  • IntegrationCallout 政策完成。
  开始后，集成的完成时间上限不能超过 50 分钟。
• 同步模式：当运行集成的请求到达端点时，端点会立即开始执行集成并等待响应。完成执行的时间上限为 2 分钟。执行完成后，该端点会返回包含执行 ID 和其他响应数据的响应。

默认值	false
是否必需？	可选
类型	布尔值
父元素	<IntegrationCallout>
子元素	无

<AsyncExecution> 元素使用以下语法：

语法

<AsyncExecution>BOOLEAN</AsyncExecution>

示例

以下示例将异步执行设置为 true：

<AsyncExecution>true</AsyncExecution>

<Request>

指定具有 SetIntegrationRequest 政策创建的请求对象的流变量。 IntegrationCallout 政策会将此请求对象发送给 Apigee Integration 以运行集成。

默认值	不适用
是否必需？	必需
类型	字符串
父元素	<IntegrationCallout>
子元素	无

<Request> 元素使用以下语法：

语法

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

示例

以下示例指定请求对象在 my_request_flow_var 流变量中可用：

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

下表介绍 <Request> 的特性：

特性	是否必需？	类型	说明
clearPayload	可选	boolean	指定在发送运行集成的请求之后，是否应从内存中清除请求对象。 如果此特性设置为 true，Apigee 会清除请求对象。 如果此特性设置为 false，Apigee 不会清除请求对象。 如果您未指定此特性，则默认值为 true，请求对象会从内存中清除。

<Response>

指定用于保存集成响应的流变量。

如果未指定此元素，则该政策会将响应保存在 integration.response 流变量中。

默认值	integration.response
是否必需？	可选
类型	字符串
父元素	<IntegrationCallout>
子元素	无

<Response> 元素使用以下语法：

语法

<Response>FLOW_VARIABLE_NAME</Response>

示例

以下示例将集成运行的响应保存在 my_response_flow_var 流变量中：

<Response>my_response_flow_var</Response>

错误代码

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.

相关主题

如需详细了解 Apigee 的集成功能，请参阅什么是 Apigee Integration？