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>

新しい ReadPropertySet ポリシーを Apigee UI に挿入すると、テンプレートには使用可能なオペレーションすべてのスタブが含まれます。必須要素の詳細については、下記をご覧ください。

この要素には、すべてのポリシーに共通する次の属性があります。

属性 デフォルト 必須かどうか 説明
name なし 必須

ポリシーの内部名。name 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。

管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。
continueOnError false 省略可 ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連情報:
enabled true 省略可 ポリシーを適用するには、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> 要素では、解決するプロパティ セット変数と、その値を設定するフロー変数を指定します。これにはデフォルト値（省略可）が含まれ、未解決のプロパティ セットがある場合に使用されます。1 つの <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>
子要素 なし

エラー リファレンス

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードおよびエラー メッセージと、<ReadPropertySet> ポリシーに固有の Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード HTTP ステータス 原因
steps.readpropertyset.UnresolvedVariable 500

このエラーは、ReadPropertySet ポリシーで指定された変数が次のいずれかの場合に発生します。

  • 範囲外（ポリシーが実行されている特定のフローで使用できない）
    • または
  • 解決不能（未定義）

<IgnoreUnresolvedVariables> が false で、<DefaultValue> が指定されていない場合、解決は失敗します。

デプロイエラー

以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。

エラー名 原因
steps.readpropertyset.EmptyReads ポリシーに <Read> の子要素がありません。
steps.readpropertyset.FieldUnset 次のいずれかに該当する場合、以下のコードが返されます。
  • <Name> に参照も名前も設定されていません
  • <Key> に参照も名前も設定されていません
  • <AssignTo> に値が指定されていません

障害変数

次の変数は、このポリシーでランタイム エラーが発生したときに設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

変数 説明 例
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 から入手できます。