本頁面由 Cloud Translation API 翻譯而成。

SetIntegrationRequest policy

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

政策圖示

總覽

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

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

`<SetIntegrationRequest>`

指定 SetIntegrationRequest 政策。

預設值	不適用
是否必要？	必填
類型	複雜類型
上層元素	N/A
子元素	`<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>`

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

<DisplayName> 元素適用於所有政策。

預設值	不適用
是否必要？	(非必要) 如果省略 `<DisplayName>`，系統會使用政策的 `name` 屬性值。
類型	字串
上層元素	<`PolicyElement`>
子元素	無

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

語法

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

範例

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

<DisplayName> 元素沒有屬性或子項元素。

`<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 支援的區域，請參閱「支援的區域」。

預設值	不適用
是否必要？	必填
類型	字串
上層元素	`<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 或字串資料類型的參數，以及字串陣列資料類型的參數陣列。

<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 值。

`<Parameter>`

指定輸入參數。

預設值	不適用
是否必要？	選用
類型	字串
上層元素	`<Parameters>`
子元素	無

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

<參數名稱="my_param" 類型="字串">val</參數>：使用 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 或字串資料類型的參數，以及字串陣列資料類型的參數陣列。

重要事項：建議您在 Set Integration Request 政策中，針對任何現有的分隔符，在 <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 參數宣告為雙精度浮點數，並將 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>

下表說明 <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 policy 政策，請勿在 SetIntegrationRequest 政策中指定 <Request> 元素。

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

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

預設值	要求
是否必要？	選用
類型	字串
上層元素	`<SetIntegrationRequest>`
子元素	無

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

語法

<Request>FLOW_VARIABLE_NAME</Request>

範例

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

<Request>my_request_var</Request>

錯誤代碼

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

執行階段錯誤

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

錯誤代碼	HTTP 狀態	原因
`steps.setintegrationrequest.EmptyParameterArray`	`500`	如果 `<ParameterArray>` 元素含有 `name` 和 `type` 屬性，但沒有 `ref` 屬性或 `<Value>` 元素，就會發生這項錯誤。
`steps.setintegrationrequest.EmptyParameterArrayValue`	`500`	當 `<Value>` 元素為空白且未設定 `ref` 屬性時，就會發生這個錯誤。
`steps.setintegrationrequest.InvalidResolvedFlowVariable`	`500`	如果元素 `ref` 屬性中指定的流程變數無法解析為有效值，就會發生這個錯誤。如果流程變數解析為空值、空字串或無效資料類型，就會針對 `ProjectId`、`IntegrationName` 或 `ApiTrigger` 元素發生這個錯誤。這些元素的有效值如下： ProjectId：請參閱「事前準備」一節中 `Project ID` 的命名規定。 IntegrationName：請參閱 IntegrationName 元素的命名規定。 ApiTrigger：名稱應以 `api_trigger/` 開頭。如果流程變數解析為空字串，就會發生此錯誤。`ParameterArray`
`steps.setintegrationrequest.MismatchedTypeAndResolvedRef`	`500`	當 `<Parameter>` 元素的 `ref` 屬性中指定的流程變數解析時，如果流程變數值的資料類型與 `type` 屬性中指定的資料類型不符，就會發生這項錯誤。
`steps.setintegrationrequest.MismatchedTypeAndResolvedRefOfParameterArray`	`500`	當 `<ParameterArray>` 元素的 `ref` 屬性中指定的流程變數解析後，但流程變數值的資料類型與 `type` 屬性中指定的資料類型不符時，就會發生此錯誤。
`steps.setintegrationrequest.MismatchedTypeAndResolvedRefOfParameterArrayValue`	`500`	如果 `<Value>` 元素的 `ref` 屬性中指定的流程變數已解析，但流程變數值的資料類型與其父項元素 (`<ParameterArray>`) 的 `type` 屬性中指定的資料類型不符，就會發生這項錯誤。
`steps.setintegrationrequest.RequestVariableNotMessageType`	`500`	如果 `Request` 元素指定的資料流變數不是 message 類型，就會發生這項錯誤。
`steps.setintegrationrequest.RequestVariableNotRequestMessageType`	`500`	如果 `Request` 元素指定的資料流變數不是「Request message」類型，就會發生這項錯誤。
`steps.setintegrationrequest.UnresolvedVariable`	`500`	當 Apigee 無法解析 `<Parameter>`、`<ParameterArray>` 或 `<Value>` 元素中指定的流程變數時，就會發生這項錯誤。

錯誤變數

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

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

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

變數	地點	範例
`fault.name`	`fault.name` 可與「執行階段錯誤」表格中列出的任何錯誤相符。錯誤名稱是錯誤代碼的最後一個部分。	`fault.name Matches "UnresolvedVariable"`
`SetIntegrationRequest.POLICY_NAME.failed`	`POLICY_NAME` 是擲回錯誤的政策的使用者指定名稱。	`SetIntegrationRequest.set-integration-request-1.failed = true`

如要進一步瞭解政策錯誤，請參閱「關於政策錯誤的相關資訊」。

SetIntegrationRequest policy 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

<SetIntegrationRequest>

語法

範例

子元素參照

<DisplayName>

語法

範例

<ProjectId>

語法

範例

<IntegrationName>

語法

範例

<IntegrationRegion>

語法

範例

<ApiTrigger>

語法

範例

<ScheduleTime>

語法

範例

<Parameters>

語法

範例

<Parameter>

語法

範例 1

範例 2

範例 3

範例 4

範例 5

範例 6

<ParameterArray>

語法

Example-1

Example-2

Example-3

Example-4

Example-5

<Value>

語法

範例 1

範例 2

範例 3

範例 4

<Request>

語法

範例

錯誤代碼

執行階段錯誤

錯誤變數

相關主題

SetIntegrationRequest policy

`<SetIntegrationRequest>`

`<DisplayName>`

`<ProjectId>`

`<IntegrationName>`

`<IntegrationRegion>`

`<ApiTrigger>`

`<ScheduleTime>`

`<Parameters>`

`<Parameter>`

`<ParameterArray>`

`<Value>`

`<Request>`