SetIntegrationRequest policy

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

查看 Apigee Edge 說明文件。

您可以使用 SetIntegrationRequest 政策，為要執行的整合建立要求物件。在政策中，您必須設定 API 觸發條件的詳細資料，以及執行整合作業所需的輸入參數。執行 SetIntegrationRequest 政策時，系統會建立要求物件並儲存在流程變數中。要求物件包含執行整合作業所需的所有資訊。 此時整合項目仍未執行。如要執行整合，您必須呼叫 IntegrationCallout 政策，或設定 IntegrationEndpoint。IntegrationCallout 政策和 IntegrationEndpoint 都需要要求物件才能執行整合。

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

注意：

• 您只能執行具有 API 觸發程序的整合。
• 如要執行整合，您必須使用 SetIntegrationRequest 政策，以及 IntegrationCallout 政策或 IntegrationEndpoint。

<SetIntegrationRequest>

指定 SetIntegrationRequest 政策。

預設值	不適用
必填與否	必填
類型	複雜型別
父項元素	不適用
子元素	<ApiTrigger> <DisplayName> <IntegrationName> <IntegrationRegion> <Parameters> <ProjectId> <Request> <ScheduleTime>

下表提供 <SetIntegrationRequest> 元素子元素的高階說明：

子元素	是否必要	說明
<ApiTrigger>	必填	要在整合中呼叫的 API 觸發條件名稱。
<DisplayName>	選用	政策的自訂名稱。
<IntegrationName>	選用	要執行的整合作業名稱。
<IntegrationRegion>	必填	整合所在的區域名稱。
<Parameters>	選用	整合作業的輸入參數。
<ProjectId>	選用	要執行的整合所在的 Google Cloud 專案名稱。
<Request>	選用	要儲存要求物件的流程變數名稱。
<ScheduleTime>	選用	整合作業的執行時間。

SetIntegrationRequest 政策使用以下語法：

語法

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<SetIntegrationRequest continueOnError="[true|false]" enabled="[true|false]" name="Set-Integration-Request">
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  <ProjectId ref="FLOW_VARIABLE_NAME">GOOGLE_CLOUD_PROJECT_ID</ProjectId>
  <IntegrationName ref="FLOW_VARIABLE_NAME">INTEGRATION_NAME</IntegrationName>
  <IntegrationRegion ref="FLOW_VARIABLE_NAME">INTEGRATION_REGION</IntegrationRegion>
  <ApiTrigger ref="FLOW_VARIABLE_NAME">API_TRIGGER_NAME</ApiTrigger>
  <ScheduleTime>PARAMETER_VALUE</ScheduleTime>
  <Parameters>
    <Parameter name="PARAMETER_NAME" type="PARAMETER_DATATYPE" ref="FLOW_VARIABLE_NAME">PARAMETER_VALUE</Parameter>
    <ParameterArray name="ARRAY_NAME" type="ARRAY_DATATYPE" ref="FLOW_VARIABLE_NAME>
      <Value ref="FLOW_VARIABLE_NAME>PARAMETER_VALUE</Value>
      <Value ref="FLOW_VARIABLE_NAME>PARAMETER_VALUE</Value>
      <Value ref="FLOW_VARIABLE_NAME>PARAMETER_VALUE</Value>
    </ParameterArray>
  </Parameters>
  <Request>FLOW_VARIABLE_NAME</Request>
</SetIntegrationRequest>

範例

以下範例顯示 SetIntegrationRequest 政策定義：

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<SetIntegrationRequest continueOnError="false" enabled="true" name="Set-Integration-Request">
  <DisplayName>Set Integration Request Policy</DisplayName>
  <ProjectId ref="my_projectid_var">apigee_staging_1</ProjectId>
  <IntegrationName ref="my_integration_ref">integration_1</IntegrationName>
  <IntegrationRegion ref="my_integration_ref">asia-east1</IntegrationRegion>
  <ApiTrigger ref="my_api_trigger_ref">API-Trigger-2</ApiTrigger>
  <ScheduleTime>2022-01-15T01:30:15Z</ScheduleTime>
  <Parameters>
    <Parameter name="my_str_param" type="string" ref="flow_var_1">someText</Parameter>
    <ParameterArray name="my_array_param" type="integer" ref="flow_var_2">
      <Value ref="flow_var_3">1</Value>
      <Value ref="flow_var_4">2</Value>
      <Value ref="flow_var_5">3</Value>
    </ParameterArray>
  </Parameters>
  <Request>my_request_var</Request>
</SetIntegrationRequest>

這個元素包含下列所有政策都適用的屬性：

屬性	預設	是否必要？	說明
name	不適用	必要	政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。 您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
continueOnError	false	選用	將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱： 錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤
enabled	是	選用	設為 true 即可強制執行政策。設為 false 即可關閉政策。即使政策仍附加至流程，系統也不會強制執行這項政策。
async	false	已淘汰	此屬性已淘汰。

子元素參照

本節說明 <SetIntegrationRequest> 的子元素。

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value	N/A
Required?	Optional. If you omit <DisplayName>, the value of the policy's name attribute is used.
Type	String
Parent Element	<PolicyElement>
Child Elements	None

The <DisplayName> element uses the following syntax:

Syntax

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

Example

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

The <DisplayName> element has no attributes or child elements.

<ProjectId>

指定 Google Cloud 專案的名稱。

Apigee 會將您為這個元素指定的值指派給 integration.project.id 流程變數。

預設值	不適用
必填與否	選用
類型	字串
父項元素	<SetIntegrationRequest>
子元素	無

<ProjectId> 元素使用下列語法：

語法

<ProjectId ref="FLOW_VARIABLE_NAME">GOOGLE_CLOUD_PROJECT_ID</ProjectId>

範例

以下範例會將政策設定為使用 my_projectid_var 流程變數擷取專案 ID，如果流程變數在執行階段無法解析，則使用 apigee_staging_1 做為專案 ID：

<ProjectId ref="my_projectid_var">apigee_staging_1</ProjectId>

下表說明 <ProjectId> 的屬性：

屬性	是否必要	類型	說明
ref	選用	字串	指定 Apigee 應從哪個流程變數讀取 Google Cloud 專案 ID。您可以透過下列任一方式設定 <ProjectId> 元素： <ProjectId>val</ProjectId>：請使用 val 做為專案 ID。 <ProjectId ref="refval"/>：動態解析 refval，以判斷專案 ID。如果已解析的專案 ID 無效，或 refval 未解析，Apigee 會回報例外狀況。 <ProjectId ref="refval">val</ProjectId>：動態解析 refval，以判斷專案 ID。如果解析出的專案 ID 無效，Apigee 會回報例外狀況。 如果 refval 無法解析，請使用 val 做為專案 ID。

<IntegrationName>

指定要執行的整合。

Apigee 會將您為這個元素指定的值指派給 integration.name 流程變數。

整合作業名稱必須符合下列命名規定：

• 開頭和結尾必須為英文字母或數字。
• 不得包含空格。
• 不得連續使用兩個破折號或底線字元。

預設值	不適用
必填與否	選用
類型	字串
父項元素	<SetIntegrationRequest>
子元素	無

<IntegrationName> 元素使用下列語法：

語法

<IntegrationName ref="FLOW_VARIABLE_NAME">INTEGRATION_NAME</IntegrationName>

範例

以下範例會設定政策，使用 my_integration_ref 流程變數擷取整合名稱，如果流程變數在執行階段無法解析，則使用 integration_1 做為整合名稱：

<IntegrationName ref="my_integration_ref">integration_1</IntegrationName>

下表說明 <IntegrationName> 的屬性：

屬性	是否必要	類型	說明
ref	選用	字串	指定 Apigee 應從哪個流程變數讀取整合名稱。您可以透過下列任一方式設定 <IntegrationName> 元素： <IntegrationName>val</IntegrationName>：使用 val 做為整合名稱。 <IntegrationName ref="refval"/>：動態解析 refval，以判斷整合名稱。如果解析的整合名稱無效，或 refval 未解析，Apigee 會回報例外狀況。 <IntegrationName ref="refval">val</IntegrationName>：動態解析 refval，以判斷整合名稱。如果解析的整合名稱無效，Apigee 會回報例外狀況。如果 refval 無法解析，請使用 val 做為整合名稱。

<IntegrationRegion>

指定整合服務所在的區域。

在執行階段，Apigee 會將元素的值指派給 integration.region 流程變數，建立以區域為準的目標網址，並將該網址儲存在 integration.target.url 流程變數中。

以區域為準的目標網址格式如下： https://integration.region-integrations.googleapis.com

整合區域必須支援 Application Integration。如要瞭解 Application Integration 支援的區域，請參閱「支援的區域」。

預設值	不適用
必填與否	必填
類型	字串
父項元素	<SetIntegrationRequest>
子元素	無

<IntegrationRegion> 元素使用下列語法：

語法

<IntegrationRegion ref="FLOW_VARIABLE_NAME">INTEGRATION_REGION</IntegrationRegion>

範例

以下範例會將政策設定為使用 my_integration_region_ref 流程變數擷取整合區域，如果流程變數在執行階段無法解析，則會使用 asia-east1 做為整合區域：

<IntegrationRegion ref="my_integration_region_ref">asia-east1</IntegrationRegion>

下表說明 <IntegrationRegion> 的屬性：

屬性	是否必要	類型	說明
ref	選用	字串	指定 Apigee 應從哪個流程變數讀取整合區域。您可以透過下列任一方式設定 <IntegrationRegion> 元素： <IntegrationRegion>val</IntegrationRegion>：使用 val 做為整合區域。 <IntegrationRegion ref="refval"/>：動態解析 refval，以判斷整合區域。如果已解析的整合區域無效，或 refval 未解析，Apigee 會回報例外狀況。 <IntegrationRegion ref="refval">val</IntegrationRegion>：動態解析 refval，以判斷整合區域。如果已解決的整合區域無效，Apigee 會回報例外狀況。如果 refval 無法解析，請使用 val 做為整合區域。

<ApiTrigger>

指定要執行的 API 觸發程序。

您必須以 api_trigger/API_TRIGGER_NAME 格式指定 API 觸發程序名稱。

Apigee 會將您為這個元素指定的值指派給 integration.api.trigger 流程變數。

如果已指定 <IntegrationName>，系統只會執行該整合服務的 API 觸發條件。不過，如果您未指定 <IntegrationName>，系統會執行所有具有指定 API 觸發程序的整合。

預設值	不適用
必填與否	必填
類型	字串
父項元素	<SetIntegrationRequest>
子元素	無

<ApiTrigger> 元素使用下列語法：

語法

<ApiTrigger ref="FLOW_VARIABLE_NAME">API_TRIGGER_NAME</ApiTrigger>

範例

以下範例會將政策設為使用 my_api_trigger_ref 流程變數擷取 API 觸發程序名稱，如果流程變數在執行階段無法解析，則使用 api_trigger/API-Trigger-2 做為 API 觸發程序名稱：

<ApiTrigger ref="my_api_trigger_ref">api_trigger/API-Trigger-2</ApiTrigger>

下表說明 <ApiTrigger> 的屬性：

屬性	是否必要	類型	說明
ref	選用	字串	指定 Apigee 應從哪個流程變數讀取 API 觸發程序名稱。您可以透過下列任一方式設定 <ApiTrigger> 元素： <ApiTrigger>val</ApiTrigger>：使用 val 做為 API 觸發條件名稱。 <ApiTrigger ref="refval"/>：動態解析 refval，判斷觸發條件名稱。如果解析的 API 觸發程序名稱無效，或 refval 未解析，Apigee 會回報例外狀況。 <ApiTrigger ref="refval">val</ApiTrigger>：動態解析 refval，以判斷觸發條件名稱。如果解析的 API 觸發程序名稱無效，Apigee 會回報例外狀況。如果 refval 無法解析，請使用 val 做為觸發條件名稱。

<ScheduleTime>

指定整合作業的執行時間。

如果時間小於或等於目前時間，系統會立即執行整合。您必須以 yyyy-mm-ddThh:mm:ssZ 格式指定時間，其中 Z 是世界標準時間時區。舉例來說，如果您指定 2022-01-15T01:30:15Z，系統就會排定在 2022 年 1 月 15 日 1:30:15 (UTC) 執行整合作業。您也可以使用與世界標準時間的時差指定時區。 舉例來說，如果您指定 2022-01-15T01:30:15-08:00，系統就會排定在 2022 年 1 月 15 日太平洋時間下午 1:30:15 執行整合作業。如要進一步瞭解時間格式，請參閱 日期和時間的合併表示法。

注意：只有在非同步模式下執行整合時，才能安排時間。 如果您在同步模式下執行整合服務，且指定排程時間，整合服務的執行作業會失敗，並顯示執行階段錯誤。

預設值	不適用
必填與否	選用
類型	字串
父項元素	<SetIntegrationRequest>
子元素	無

<ScheduleTime> 元素使用下列語法：

語法

<ScheduleTime>PARAMETER_VALUE</ScheduleTime>

範例

以下範例會排定在 2022-01-15T01:30:15Z 執行整合作業：

<ScheduleTime>2022-01-15T01:30:15Z</ScheduleTime>

<Parameters>

指定執行整合作業所需的輸入參數。

您可以指定個別參數或參數陣列。

• 如要指定個別參數，請使用 <Parameter> 元素。
• 如要指定參數陣列，請使用 <ParameterArray> 元素。

預設值	不適用
必填與否	選用
類型	複雜型別
父項元素	<SetIntegrationRequest>
子元素	<Parameter> <ParameterArray>

下表說明 <Parameters> 的屬性：

屬性	是否必要	類型	說明
substitutionVariableChar	選用	Char	可讓您設定自訂分隔符，在 <Parameter> 子元素中將流程變數值做為範本引數傳遞。 注意： substitutionVariableChar 只能為 JSON 或 String 資料類型的參數，以及 String 陣列資料類型的參數陣列，傳遞範本引數。

<Parameters> 元素使用下列語法：

語法

<Parameters substitutionVariableChar="SUBSTITUTION_CHAR">
  <Parameter name="PARAMETER_NAME" type="PARAMETER_DATATYPE" ref="FLOW_VARIABLE_NAME" >PARAMETER_VALUE</Parameter>
  <Parameter name="PARAMETER_NAME" type="PARAMETER_DATATYPE">SUBSTITUTION_CHAR FLOW_VARIABLE_NAME SUBSTITUTION_CHAR</Parameter>
  <ParameterArray name="ARRAY_NAME" type="ARRAY_DATATYPE ref="FLOW_VARIABLE_NAME"">
    <Value>PARAMETER_VALUE</Value>
    <Value ref="FLOW_VARIABLE_NAME"/>
    <Value ref="FLOW_VARIABLE_NAME">PARAMETER_VALUE</Value>
  </ParameterArray>
</Parameters>

範例

以下範例會初始化 my_str_param 參數和 my_array_param 參數陣列：

<Parameters substitutionVariableChar="#">
  <Parameter name="my_str_param" type="string" ref="flow_var_1">someText</Parameter>
  <Parameter name="strVar" type="string">#flowvar1#</Parameter>
  <ParameterArray name="my_array_param" type="integer" ref="flow_var_2">
    <Value>1</Value>
    <Value ref="flow_var_3"/>
    <Value ref="flow_var_4">3</Value>
  </ParameterArray>
</Parameters>

Apigee 會將空白的 <Parameter> 和 <ParameterArray> 元素視為 null 值。舉例來說，<Parameter></Parameter> 和 <ParameterArray></ParameterArray> 等宣告會視為 null 值。

注意： 如果參數具有 JSON 值，請確認 JSON 有效。舉例來說，如果 JSON 酬載包含雙引號 (")，請使用反斜線 (\) 逸出每個雙引號。

<Parameter>

指定輸入參數。

預設值	不適用
必填與否	選用
類型	字串
父項元素	<Parameters>
子元素	無

您可以透過下列方式指定參數值：

• <Parameter name="my_param" type="string">val</Parameter>：使用 val 做為參數值。如果 val 無效，Apigee 會回報例外狀況。
• <Parameter name="my_param" type="string" ref="refval"/>：在執行階段解析 refval 流程變數，並使用其值。如果已解析的 refval 值無效，或 refval 未解析，Apigee 會回報例外狀況。
• <Parameter name="my_param" type="string" ref="refval">val</Parameter>：在執行階段解析 refval 流程變數，並使用其值。如果解析的 refval 值無效，Apigee 會回報例外狀況。如果 refval 無法解析，Apigee 會使用 val 做為參數值。
• <Parameter name="my_param" type="json">{"name":"$#flowval#$"}</Parameter>：使用 $#FLOW_VARIABLE_NAME#$ 將流程變數值做為參數中的範本引數傳遞。Apigee 會在執行階段解析 flowval 流程變數，並使用其值。如果已解析的 flowval 值無效，系統會回報例外狀況。
  注意：您只能為 JSON 或字串資料類型的參數，以及字串陣列資料類型的參數陣列，傳遞範本引數。
  警告：以 { 和 } 括住的範本引數不再視為流程變數。
• <Parameter name="my_param" type="json">{"name":"SUBSTITUTION_CHAR flowval SUBSTITUTION_CHAR"}</Parameter>：其中 SUBSTITUTION_CHAR 表示為 <Parameters> 父項元素的 substitutionVariableChar 屬性指定的值。Apigee 會在執行階段解析 flowval 流程變數，並使用其值。如果已解析的 flowval 值無效，系統會回報例外狀況。
  注意： substitutionVariableChar 只能傳遞範本引數，適用於 JSON 或字串資料型別的參數，以及字串陣列資料型別的參數陣列。
  重要事項：建議您在「設定整合要求」政策中，為任何現有的分隔符新增及更新 <Parameters> 父項元素中的 substitutionVariableChar 屬性。

<Parameter> 元素使用下列語法：

語法

<Parameters substitutionVariableChar="SUBSTITUTION_CHAR">
  <Parameter name="PARAMETER_NAME" type="PARAMETER_DATATYPE">PARAMETER_VALUE</Parameter>
  <Parameter name="PARAMETER_NAME" type="PARAMETER_DATATYPE" ref="FLOW_VARIABLE_NAME"/>
  <Parameter name="PARAMETER_NAME" type="PARAMETER_DATATYPE" ref="FLOW_VARIABLE_NAME">PARAMETER_VALUE</Parameter>
  <Parameter name="PARAMETER_NAME" type="json">$#FLOW_VARIABLE_NAME#$</Parameter>
  <Parameter name="PARAMETER_NAME" type="PARAMETER_DATATYPE">SUBSTITUTION_CHAR FLOW_VARIABLE_NAME SUBSTITUTION_CHAR</Parameter>
</Parameters>

範例 1

以下範例會將 my_str_param 參數宣告為字串，並將值設為 someText。

<Parameters>
  <Parameter name="my_str_param" type="string">someText</Parameter>
</Parameters>

範例 2

以下範例會將 my_double_param 參數宣告為 double，並將 flow_var 流程變數的值指派給該參數。

<Parameters>
  <Parameter name="my_double_param" type="double" ref="flow_var"/>
</Parameters>

範例 3

以下範例會將值設為 my_int_param_1 整數參數。

<Parameters>
  <Parameter name="my_int_param_1" type="integer" ref="flow_var_1">96</Parameter>
</Parameters>

在本範例中，如果 flow_var_1 流程變數成功解析，my_int_param_1 會設為流程變數的值。不過，如果 flow_var_1 無法解析，my_int_param_1 會設為 96。

範例 4

下列範例會為 my_json_param_1 和 my_json_param_2 JSON 參數設定值。

<Parameters>
  <Parameter name="my_json_param_1" type="json" ref="flow_var_1">{name:"Apple", color:"Red"}</Parameter>
  <Parameter name="my_json_param_2" type="json">{name:"Banana", color:"Yellow"}</Parameter>
</Parameters>

在本範例中，如果 flow_var_1 流程變數順利解析，my_json_param_1 會設為 flow_var_1 流程變數的值。不過，如果 flow_var_1 無法解析，my_json_param_1 會設為 {name:"Apple", color:"Red"}。由於未指定 ref 屬性，因此 my_json_param_2 參數設為 {name:"Banana", color:"Yellow"}。

範例 5

以下範例會使用預設範本中傳遞的流程變數值，設定 template_json_param JSON 參數的值。

  <Parameters>
    <Parameter name="template_json_param" type="json">{"name":"$#flow_var_1#$"}</Parameter>
</Parameters>
  

在本範例中，如果 flow_var_1 流程變數順利解析，template_json_param 會設為 flow_var_1 流程變數的值。不過，如果 flow_var_1 無法解析，Apigee 會擲回例外狀況。

範例 6

以下範例使用 substitutionVariableChar 屬性，為 template_json_param JSON 參數設定值。

<Parameters substitutionVariableChar="#">
    <Parameter name="template_json_param" type="json">{"name":"#flow_var_1#"}</Parameter>
</Parameters>
  

在本範例中，如果 flow_var_1 流程變數順利解析，template_json_param 會設為 flow_var_1 流程變數的值。不過，如果 flow_var_1 無法解析，Apigee 會擲回例外狀況。

下表說明 <Parameter> 的屬性：

屬性	是否必要	類型	說明
name	必填	字串	參數名稱。
type	必填	字串	參數的資料類型。支援的類型為 integer、string、boolean、double 和 json。
ref	選用	字串	指定 Apigee 應從哪個流程變數讀取參數值。Apigee 會根據下列條件設定參數值： 如果流程變數在執行階段解析且有效，Apigee 會使用流程變數的值。 如果流程變數在執行階段解析，但無效，Apigee 會回報例外狀況。 如果流程變數在執行階段無法解析，Apigee 會使用 <Parameter> 元素值。如果元素值無效，Apigee 會回報錯誤。

<ParameterArray>

指定輸入參數陣列。

預設值	不適用
必填與否	選用
類型	複雜型別
父項元素	<Parameters>
子元素	<Value>

<Parameters> 元素可包含多個 <ParameterArray> 元素。對於參數陣列，您可以指定實際值，或在 ref 屬性中指定流程變數，藉此設定陣列元素的值。如果您指定流程變數，陣列元素會設為流程變數的值。 本節中的範例說明設定 <ParameterArray> 元素的不同方式。

<ParameterArray> 元素使用下列語法：

語法

<Parameters>
  <ParameterArray name="ARRAY_NAME" type="ARRAY_DATATYPE" ref="FLOW_VARIABLE_NAME">
    <Value ref="FLOW_VARIABLE_NAME"/>
    <Value ref="FLOW_VARIABLE_NAME">PARAMETER_VALUE</Value>
    <Value>PARAMETER_VALUE</Value>
  </ParameterArray>
  <ParameterArray name="ARRAY_NAME" type="ARRAY_DATATYPE" ref="FLOW_VARIABLE_NAME"/>
  <ParameterArray name="ARRAY_NAME" type="ARRAY_DATATYPE">
    <Value ref="FLOW_VARIABLE_NAME"/>
    <Value ref="FLOW_VARIABLE_NAME">PARAMETER_VALUE</Value>
    <Value>PARAMETER_VALUE</Value>
  </ParameterArray>
<Parameters/>

Example-1

下列範例會將 my_array_param 宣告為整數陣列，並將陣列元素的值設為 1、2 和 3：

<Parameters>
  <ParameterArray name="my_array_param" type="integer">
    <Value>1</Value>
    <Value>2</Value>
    <Value>3</Value>
  </ParameterArray>
<Parameters/>

Example-2

下列範例會將 my_array_param 宣告為雙精度陣列，其中：

• 第一個元素會設為 flow_var_1 流程變數的值。
• 第二個元素設為 3.0。

<Parameters>
  <ParameterArray name="my_array_param" type="double">
    <Value ref="flow_var_1"/>
    <Value>3.0</Value>
  </ParameterArray>
<Parameters/>

Example-3

以下範例會將 my_array_param 宣告為布林值陣列，並將其設為 flow_var_1 流程變數的值。

<Parameters>
  <ParameterArray name="my_array_param" type="boolean" ref="flow_var_1">
    <Value>true</Value>
    <Value>false</Value>
    <Value>false</Value>
  </ParameterArray>
<Parameters/>

在本範例中，如果 flow_var_1 成功解析，my_array_param 會設為 flow_var_1 陣列的值。不過，如果 flow_var_1 無法解析，my_array_param 陣列會設為 Value 元素的值。

Example-4

以下範例會將 my_array_param 宣告為 JSON 陣列，並將其設為 flow_var_1 流程變數的值。

<Parameters>
  <ParameterArray name="my_array_param" type="json" ref="flow_var_1"/>
<Parameters/>

在本範例中，如果 flow_var_1 成功解析，my_array_param 會設為 flow_var_1 陣列的值。不過，如果 flow_var_1 無法解析，Apigee 會回報例外狀況。

Example-5

以下範例會將 my_array_param 宣告為字串陣列，並將其設為 flow_var_1 流程變數的值。

<Parameters>
  <ParameterArray name="my_array_param" type="string" ref="flow_var_1">
    <Value ref="flow_var_2"/>
    <Value>test_string</Value>
  </ParameterArray>
<Parameters/>

在本範例中，如果 flow_var_1 成功解析，my_array_param 會設為 flow_var_1 陣列的值。只有在 flow_var_1 無法解析時，my_array_param 才會設為 <Value> 元素中指定的值。

下表說明 <ParameterArray> 的屬性：

屬性	是否必要	類型	說明
name	必填	字串	參數陣列的名稱。
type	必填	字串	參數陣列的資料類型。支援的類型為 integer、string、boolean 和 double。
ref	選用	字串	指定 Apigee 應從哪個流程變數讀取陣列值。Apigee 會根據下列條件設定參數值： 如果流程變數在執行階段解析且有效，Apigee 會使用流程變數的值。 如果流程變數在執行階段解析，但無效，Apigee 會回報例外狀況。 如果流程變數在執行階段無法解析，Apigee 會使用 <Value> 元素中指定的值。

<Value>

指定陣列元素的值。

預設值	不適用
必填與否	選用
類型	字串
父項元素	<ParameterArray>
子元素	無

陣列的每個元素都必須是個別的 <Value> 元素。您可以透過下列方式指定值：

• <Value>val</Value>：使用 val 做為元素值。如果 val 無效，Apigee 會回報例外狀況。
• <Value ref="refval"/>：在執行階段解析 refval 流程變數，並使用其值。如果已解析的 refval 值無效，或 refval 未解析，Apigee 會回報例外狀況。
• <Value ref="refval">val</Value>：在執行階段解析 refval 流程變數，並使用其值。如果解析的 refval 值無效，Apigee 會回報例外狀況。如果 refval 無法解析，Apigee 會使用 val 做為元素值。
• <Value>val1 $#flowval#$</Value>：使用 $#FLOW_VARIABLE_NAME#$ 將流程變數值做為範本引數傳遞至 Value。Apigee 會在執行階段解析 flowval 流程變數，並使用其值。如果已解析的 flowval 值無效，系統會回報例外狀況。
  注意： 您只能將範本引數指定為字串資料類型參數陣列的值。
  警告：以 { 和 } 括住的範本引數不再視為流程變數。

<Value> 元素使用下列語法：

語法

<ParameterArray name="ARRAY_NAME" type="ARRAY_DATATYPE" ref="FLOW_VARIABLE_NAME">
  <Value>PARAMETER_VALUE</Value>
  <Value ref="FLOW_VARIABLE_NAME"/>
  <Value ref="FLOW_VARIABLE_NAME">PARAMETER_VALUE</Value>
</ParameterArray>

範例 1

以下範例會將 my_array_param 宣告為整數參數陣列，並帶有 1、2 和 3 值：

<ParameterArray name="my_array_param" type="integer">
  <Value>1</Value>
  <Value>2</Value>
  <Value>3</Value>
</ParameterArray>

範例 2

以下範例會將 my_array_param 宣告為字串參數陣列，並使用 flow_var_1 和 flow_var_2 流程變數的值：

<ParameterArray name="my_array_param" type="string">
  <Value ref="flow_var_1"/>
  <Value ref="flow_var_2"/>
</ParameterArray>

範例 3

下列範例會將 my_array_param 宣告為字串參數陣列：

<ParameterArray name="my_array_param" type="string">
   <Value ref="flow_var_1">string_1</Value>
   <Value ref="flow_var_2">string_2</Value>
</ParameterArray>

在本範例中，如果流程變數成功解析，陣列元素值會設為 flow_var_1 流程變數的值。不過，如果 flow_var_1 無法解析，陣列元素值會設為 string_1。

範例 4

以下範例會使用範本中傳遞的流程變數值，為 template_strArray_param 字串陣列參數設定值。

  <Parameters>
    <ParameterArray name="template_strArray_param" type="string">
    <Value>apple $#flow_var_1#$</Value>
    </ParameterArray>
  </Parameters>
  

在本範例中，如果流程變數成功解析，陣列元素值會設為 flow_var_1 流程變數的值。不過，如果 flow_var_1 無法解析，Apigee 會擲回例外狀況。

下表說明 <Value> 的屬性：

屬性	是否必要	類型	說明
ref	選用	字串	指定 Apigee 應從哪個流程變數讀取參數值。Apigee 會根據下列條件設定參數值： 如果流程變數在執行階段解析且有效，Apigee 會使用流程變數的值。 如果流程變數在執行階段解析，但無效，Apigee 會回報例外狀況。 如果流程變數在執行階段無法解析，Apigee 會使用 <Value> 元素的值。如果元素值無效，Apigee 會回報錯誤。

注意：<Value> 元素不得為空。

<Request>

指定用於儲存要求的流程變數名稱。

注意：如果您使用整合端點，而非IntegrationCallout 政策，請勿在 SetIntegrationRequest 政策中指定 <Request> 元素。

政策執行後，會建立新的要求訊息物件，並將該物件儲存在 FLOW_VARIABLE_NAME 變數中，您可以查詢該變數來讀取要求。

如未指定流程變數名稱，政策會將要求儲存在要求訊息中，並覆寫現有的要求訊息 (如有)。

預設值	要求
必填與否	選用
類型	字串
父項元素	<SetIntegrationRequest>
子元素	無

<Request> 元素使用下列語法：

語法

<Request>FLOW_VARIABLE_NAME</Request>

範例

以下範例會將要求物件儲存在 my_request_var 流程變數中：

<Request>my_request_var</Request>

錯誤代碼

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
steps.setintegrationrequest.EmptyParameterArray	500	This error occurs when the <ParameterArray> element has the name and type attributes, but doesn't have the ref attribute or a <Value> element.
steps.setintegrationrequest.EmptyParameterArrayValue	500	This error occurs when the <Value> element is empty and the ref attribute is not set.
steps.setintegrationrequest.InvalidResolvedFlowVariable	500	This error occurs when the flow variable specified in the ref attribute of an element fails to resolve to a valid value. For the ProjectId, IntegrationName, or the ApiTrigger elements, this error occurs if the flow variable resolves to a null, an empty string, or an invalid data type. A valid value for these elements is as follows: ProjectId: See the naming requirements for Project ID in the Before you begin section. IntegrationName: See the naming requirements for the IntegrationName element. ApiTrigger: The name should start with api_trigger/. For the ParameterArray element, this error occurs if the flow variable resolves to an empty string.
steps.setintegrationrequest.MismatchedTypeAndResolvedRef	500	This error occurs when the flow variable specified in the ref attribute of the <Parameter> element resolves, but the flow variable value's data type doesn't match the data type specified in the type attribute.
steps.setintegrationrequest.MismatchedTypeAndResolvedRefOfParameterArray	500	This error occurs when the flow variable specified in the ref attribute of the <ParameterArray> element resolves, but the flow variable value's data type doesn't match with the data type specified in the type attribute.
steps.setintegrationrequest.MismatchedTypeAndResolvedRefOfParameterArrayValue	500	This error occurs when the flow variable specified in the ref attribute of the <Value> element resolves, but the flow variable value's data type doesn't match with the data type specified in the type attribute of its parent element (<ParameterArray>).
steps.setintegrationrequest.RequestVariableNotMessageType	500	This error occurs when the flow variable specified by the Request element is not of message type.
steps.setintegrationrequest.RequestVariableNotRequestMessageType	500	This error occurs when the flow variable specified by the Request element is not of Request message type.
steps.setintegrationrequest.UnresolvedVariable	500	This error occurs when Apigee can't resolve the flow variables specified in the <Parameter>, <ParameterArray>, or the <Value> elements.

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"
SetIntegrationRequest.POLICY_NAME.failed	POLICY_NAME is the user-specified name of the policy that threw the fault.	SetIntegrationRequest.set-integration-request-1.failed = true

For more information about policy errors, see What you need to know about policy errors.

相關主題

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