ReadPropertySet 政策

ReadPropertySet 政策會讀取屬性集，並以結果填入流程變數。

這項政策是標準政策，可部署至任何環境類型。如要瞭解各環境類型適用的政策類型和可用性，請參閱「政策類型」。

<ReadPropertySet> 元素

定義 ReadPropertySet 政策。

預設值 請參閱下方的「預設政策」分頁
必填與否 必填
類型 複雜物件
父項元素 不適用
子元素 <Read>

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

語法

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

<ReadPropertySet name="read-property-set">
  <Read>
    <Name ref="set-ref">property-set-name</Name>
    <Key ref="key-ref">key-name</Key>
    <AssignTo>var1</AssignTo>
    <DefaultValue>default-value</DefaultValue>
  </Read>
  ...
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ReadPropertySet>

預設政策

以下範例顯示在 Apigee UI 中將 ReadPropertySet 政策新增至流程時的預設設定：

<ReadPropertySet name="read-property-set">
  <Read>
    <Name ref="set-ref">property-set-name</Name>
    <Key ref="key-ref">key-name</Key>
    <AssignTo>var1</AssignTo>
    <DefaultValue>default-value</DefaultValue>
  </Read>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ReadPropertySet>

在 Apigee UI 中插入新的 ReadPropertySet 政策時，範本會包含所有可能作業的存根。請參閱下文，瞭解必要元素。

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

屬性 預設 是否必要？ 說明
name 不適用 必要

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。

您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
continueOnError false 選用 將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：
enabled 是 選用 設為 true 即可強制執行政策。設為 false 即可關閉政策。即使政策仍附加至流程，系統也不會強制執行這項政策。
async   false 已淘汰 此屬性已淘汰。

下表簡要說明 <ReadPropertySet> 的子元素：

子元素 是否必要 說明
<Read> 必填 讀取及解析屬性集變數，並設為指定流程變數。
<IgnoreUnresolvedVariables> 選用 決定在屬性集未解析時是否停止處理。

範例

本節提供使用 <ReadPropertySet> 的範例。

範例

本範例使用 <ReadPropertySet> 取得 propertyset.environment.name.request.headers.api-version，並將其指派給 target_url。如果無法取得屬性集值，則會改用 https://httpbin.org/get。

<ReadPropertySet name="read-property-set">
  <Read>
    <Name ref="set-ref">environment.name</Name>
    <Key ref="key-ref">request.headers.api-version</Key>
    <AssignTo>target_url</AssignTo>
    <DefaultValue>https://httpbin.org/get</DefaultValue>
  </Read>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</ReadPropertySet>

子元素參照

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

<Read>

解析屬性集變數，並在流程變數中設定結果。

<Read> 元素會指定要解析的屬性集變數，以及要將該值設為的流程變數。此外，這個函式也包含選用的預設值，用於未解析的屬性集。您可以在單一 <ReadPropertySet> 政策中加入多個 <Read> 元素。

預設值 不適用
必填與否 選用
類型 複雜型別
父項元素 <ReadPropertySet>
子元素 <Name>
<Key>
<AssignTo>
<DefaultValue>

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

語法

<Read>
  <Name ref="set-ref">property-set-name</Name>
  <Key ref="key-ref">key-name</Key>
  <AssignTo>var1</AssignTo>
  <DefaultValue>default-value</DefaultValue>
</Read>

範例

本範例使用 <ReadPropertySet> 取得 propertyset.environment.name.request.headers.api-version，並將其指派給 target_url。如果無法取得屬性集值，則會改用 https://httpbin.org/get。

<ReadPropertySet name="read-property-set">
  <Read>
    <Name ref="environment.name">my-property-set-name</Name>
    <Key ref="request.headers.api-version">my-property-set-key</Key>
    <AssignTo>target_url</AssignTo>
    <DefaultValue>https://httpbin.org/get</DefaultValue>
  </Read>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</ReadPropertySet>

下表提供 <Read> 子元素的高階說明。

子元素 是否必要 說明
<Name> 必填 字串

要讀取的屬性。提供 ref、值或兩者。

Apigee 會先嘗試根據 ref 解析 Name，然後解析值。如果無法解析這兩者，則會套用 <DefaultValue> (如有提供)。

<Name> 和 <Key> 會合併為 propertyset.{value_resolved_from_Name}.{value_resolved_from_Key}。
<Key> 必填 字串

解析變數時使用的屬性集鍵。 提供 ref、值或兩者。

Apigee 會先嘗試根據 ref 解析 Key，然後解析值。如果無法解析這兩者，則會套用 <DefaultValue> (如有提供)。

<Name> 和 <Key> 會合併為 propertyset.{value_resolved_from_Name}.{value_resolved_from_Key}。
<AssignTo> 必填 字串

指定要將已解析變數指派給哪個流程變數。
<DefaultValue> 選用 字串

指定無法解析變數時要使用的預設值。

<IgnoreUnresolvedVariables>

決定在屬性集未解析時是否停止處理。設為 true 可忽略未解析的變數，並繼續處理。

提供 <DefaultValue> 時，不適用 IgnoreUnresolvedVariables。

預設值 否
必填與否 選用
類型 布林值
父項元素 <ReadPropertySet>
子元素 無

錯誤參考資料

本節說明 Apigee 針對 <ReadPropertySet> 政策傳回的錯誤代碼和錯誤訊息，以及設定的錯誤變數。如果您要開發用來處理錯誤的錯誤規則，請務必瞭解這項資訊。如要瞭解詳情，請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

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

錯誤代碼 HTTP 狀態 原因
steps.readpropertyset.UnresolvedVariable 500

如果 ReadPropertySet 政策中指定的變數符合下列任一條件，就會發生這個錯誤：

  • 超出範圍 (無法在執行政策的特定流程中使用)
    • 或
  • 無法解析 (未定義)。

如果 <IgnoreUnresolvedVariables> 為 false 且未指定 <DefaultValue>，解析作業就會失敗。

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

錯誤名稱 原因
steps.readpropertyset.EmptyReads 政策沒有 <Read> 子元素。
steps.readpropertyset.FieldUnset 如果出現以下任何一個情況，系統就會傳回這個代碼：

錯誤變數

當這項政策在執行階段觸發錯誤時，系統會設定這些變數。詳情請參閱「政策錯誤須知」。

變數 地點 範例
fault.name="FAULT_NAME" FAULT_NAME 是故障名稱，如上方的「執行階段錯誤」表格所示。錯誤名稱是錯誤代碼的最後一部分。 fault.name Matches "UnresolvedVariable"
readpropertyset.POLICY_NAME.failed POLICY_NAME 是使用者指定的政策名稱，該政策擲回了錯誤。 readpropertyset.RPS-SetResponse.failed = true

錯誤回應範例

  {
    "fault": {
      "faultstring": "ReadPropertySet[RPS-SetResponse]: unable to resolve variable [variable_name]",
      "detail": {
        "errorcode": "steps.readpropertyset.UnresolvedVariable"
      }
    }
  }

錯誤規則範例

  <FaultRule name="ReadPropertySet Faults">
      <Step>
          <Name>RPS-CustomSetVariableErrorResponse</Name>
          <Condition>(fault.name = "SetVariableFailed")</Condition>
      </Step>
      <Condition>(readpropertyset.failed = true)</Condition>
  </FaultRule>

結構定義

每種政策類型都由 XML 架構 (.xsd) 定義。如需參考，請前往 GitHub 查看政策架構。