IntegrationCallout policy

本頁適用於 Apigee 和 Apigee Hybrid。

總覽

IntegrationCallout 政策可讓您執行具有 API 觸發條件的應用程式整合。不過，您必須先執行 SetIntegrationRequest 政策，才能執行整合作業。SetIntegrationRequest 政策會建立要求物件，並將該物件做為流程變數提供給 IntegrationCallout 政策。要求物件包含整合詳細資料，例如 API 觸發器名稱、整合專案 ID、整合名稱，以及在 SetIntegrationRequest 政策中設定的其他詳細資料。IntegrationCallout 政策會使用要求物件的流程變數來執行整合作業。您可以設定 IntegrationCallout 政策，將整合執行回應儲存在流程變數中。

如果您想在 Proxy 流程中執行整合，IntegrationCallout 政策就很實用。或者，您也可以指定整合端點做為目標端點，藉此執行整合，而無需設定 IntegrationCallout 政策。詳情請參閱 IntegrationEndpoint。

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

注意：您需要驗證權杖才能執行「IntegrationCallout」政策。不過，政策定義中並未明確提供 Authentication 元素。Apigee 會在幕後將驗證權杖新增至要求。如要讓 IntegrationCallout 政策順利驗證，您必須使用具有執行整合作業所需 IAM 角色的服務帳戶，部署 API 代理程式。如要瞭解必要角色，請參閱「整合的 IAM 角色」。如要進一步瞭解如何部署 API Proxy，請參閱「在 Apigee 上部署」。

<IntegrationCallout>

指定 IntegrationCallout 政策。

預設值	不適用
是否必要？	必填
類型	複雜類型
上層元素	N/A
子元素	<DisplayName> <AsyncExecution> <Request> <Response>

下表概略說明 <IntegrationCallout> 的子元素：

子元素	是否必要	說明
<DisplayName>	選用	政策的自訂名稱。
<AsyncExecution>	選用	指定整合作業是否必須以同步或非同步模式執行。
<Request>	必填	包含由 SetIntegrationRequest 政策建立的 request 物件的流程變數。
<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> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
continueOnError	false	選用	將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱： 錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤
enabled	是	選用	設為 true 即可強制執行政策。設為 false 即可關閉政策。即使政策仍附加至流程，系統也不會強制執行這項政策。
async	false	已淘汰	此屬性已淘汰。

子元素參照

本節將說明 <IntegrationCallout> 的子元素。

<DisplayName>

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用其他更自然的名稱標記政策。

<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 政策會將這個要求物件傳送至 Application 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>
子元素	無

您可以透過 integration.response.content 或 flow_variable.content 存取整合作業的輸出內容。<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. Application Integration 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.

相關主題

如要進一步瞭解應用程式整合功能，請參閱「應用程式整合功能總覽」