IntegrationCallout 政策

本页面适用于 Apigee 和 Apigee Hybrid。

政策图标

概览

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

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

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 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，即使在政策失败后，仍可以继续执行流。另请参阅：
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 和其他响应数据的响应。
默认值 否
是否必需？ 可选
类型 布尔值
父元素 <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 可选 布尔值

指定在发送运行集成的请求之后，是否应从内存中清除请求对象。

  • 如果此特性设置为 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>

错误代码

本部分介绍当此政策触发错误时的故障代码、错误消息以及由 Apigee 设置的故障变量。在您要开发故障规则来处理故障时，此信息非常重要。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码 HTTP 状态 原因
entities.UnresolvedVariable 500 如果 Apigee 无法解析 integration.project.id 或 integration.name 变量，则会发生此错误。
steps.integrationcallout.ExecutionFailed 500

如果后端目标服务返回 HTTP 错误状态，例如 4xx 或 5xx，则可能会发生此错误。可能的原因包括：

  • 使用代理部署的服务账号用于运行集成的权限不正确。
  • 集成或 API 触发器不存在。
  • 您的 Google Cloud 项目未启用 Apigee Integration。
  • 您在 SetIntegrationRequest 政策中配置了 <ScheduleTime> 元素，并且 IntegrationCallout 政策将 AsyncExecution 设置为 false。
steps.integrationcallout.NullRequestVariable 500 如果在 <Request> 中指定的流变量为 null，则会发生此错误。
steps.integrationcallout.RequestVariableNotMessageType 500 当 Request 元素指定的流变量不是消息类型时，会发生此错误。
steps.integrationcallout.RequestVariableNotRequestMessageType 500 当 Request 元素指定的流变量不是请求消息类型时，会发生此错误。
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500

此错误可能是由服务账号配置错误造成的。可能的原因包括：

  • 您的项目中不存在使用代理部署的服务账号。
  • 使用代理部署的服务账号已停用。

故障变量

只要政策中存在执行错误，Apigee 就会生成错误消息。您可以在错误响应中查看这些错误消息。很多时候，系统生成的错误消息可能与您的产品上下文无关。您可能希望根据错误类型自定义错误消息，以使消息更有意义。

如需自定义错误消息，可以使用故障规则或 RaiseFault 政策。如需了解故障规则与 RaiseFault 政策之间的差异，请参阅 FaultRule 与 RaiseFault 政策。您必须使用故障规则和 RaiseFault 政策中的 Condition 元素来检查条件。Apigee 提供每个政策独有的故障变量，并在政策触发运行时错误时设置故障变量的值。通过使用这些变量，您可以检查特定的错误情况并采取适当的操作。如需详细了解如何检查错误条件，请参阅构建条件。

下表介绍了特定于此政策的故障变量。

变量 其中 示例
fault.name fault.name 可以匹配运行时错误表中列出的任何故障。故障名称是故障代码的最后一部分。 fault.name Matches "UnresolvedVariable"
IntegrationCallout.POLICY_NAME.failed POLICY_NAME 是抛出故障的政策的用户指定名称。 IntegrationCallout.integration-callout-1.failed = true
如需详细了解政策错误，请参阅您需要了解的政策错误相关信息。

相关主题

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