IntegrationCallout policy

本頁內容適用於 Apigee 和 Apigee Hybrid。

政策圖示

總覽

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

如果您想在 Proxy 流程中執行整合作業，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> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
continueOnError false 選用 將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：
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>

錯誤代碼

本節說明這項政策觸發錯誤時，Apigee 設定的錯誤代碼、錯誤訊息和錯誤變數。如果您要開發錯誤處理規則，則必須提供這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。

錯誤代碼 HTTP 狀態 原因
entities.UnresolvedVariable 500 如果 Apigee 無法解析 integration.project.id 或 integration.name 變數，就會發生這個錯誤。
steps.integrationcallout.ExecutionFailed 500

如果後端目標服務傳回 HTTP 錯誤狀態 (例如 4xx 或 5xx)，就可能發生這個錯誤。可能的原因包括：

  • 透過 Proxy 部署的服務帳戶具備執行整合項目的錯誤權限。
  • 整合或 API 觸發條件不存在。
  • 您的 Google Cloud 專案未啟用應用程式整合功能。
  • 您已在 SetIntegrationRequest 政策中設定 <ScheduleTime> 元素，且 IntegrationCallout 政策已將 AsyncExecution 設為 false。
steps.integrationcallout.NullRequestVariable 500 如果 <Request> 中指定的流程變數為空值，就會發生此錯誤。
steps.integrationcallout.RequestVariableNotMessageType 500 如果 Request 元素指定的資料流變數不是 message 類型，就會發生這項錯誤。
steps.integrationcallout.RequestVariableNotRequestMessageType 500 如果 Request 元素指定的資料流變數不是「Request message」類型，就會發生這項錯誤。
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500

這類錯誤可能會因服務帳戶設定錯誤而發生。可能的原因包括：

  • 專案中沒有透過 Proxy 部署的服務帳戶。
  • 透過 Proxy 部署的服務帳戶已停用。

錯誤變數

每當政策發生執行錯誤時，Apigee 就會產生錯誤訊息。您可以在錯誤回應中查看這些錯誤訊息。很多時候，系統產生的錯誤訊息可能與產品情境無關。您可能會根據錯誤類型自訂錯誤訊息，讓訊息更有意義。

如要自訂錯誤訊息，您可以使用錯誤規則或 RaiseFault 政策。如要瞭解錯誤規則和 RaiseFault 政策的差異，請參閱 FaultRules 與 RaiseFault 政策。您必須在錯誤規則和 RaiseFault 政策中使用 Condition 元素檢查條件。Apigee 會提供每項政策專屬的錯誤變數，而錯誤變數的值會在政策觸發執行階段錯誤時設定。您可以使用這些變數，檢查特定錯誤情況並採取適當行動。如要進一步瞭解如何檢查錯誤條件，請參閱「建構條件」。

下表說明這項政策的特定錯誤變數。

變數 地點 範例
fault.name fault.name 可與「執行階段錯誤」表格中列出的任何錯誤相符。 錯誤名稱是錯誤代碼的最後一個部分。 fault.name Matches "UnresolvedVariable"
IntegrationCallout.POLICY_NAME.failed POLICY_NAME 是擲回錯誤的政策的使用者指定名稱。 IntegrationCallout.integration-callout-1.failed = true
如要進一步瞭解政策錯誤，請參閱「關於政策錯誤的相關資訊」。

相關主題

如要進一步瞭解 Application Integration 功能，請參閱「Application Integration 總覽」一文。