ReadPropertySet 政策

總覽

ReadPropertySet 政策會讀取資源集，並使用結果填入流程變數。

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

<ReadPropertySet> 元素

定義 ReadPropertySet 政策。

預設值 請參閱下方的「Default Policy」分頁
是否必要？ 必填
類型 複雜物件
上層元素 N/A
子元素 <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 政策時，範本會包含所有可能作業的 Stub。請參閱下方資訊，瞭解必要元素。

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

屬性 預設 是否必要？ 說明
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> 必填 String

要讀取的屬性集。提供 ref 或值，或同時提供兩者。

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

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

用於解析變數的屬性集合鍵。提供 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 查看政策架構。