ExtractVariables ポリシー

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge のドキュメントを表示する。

概要

ExtractVariables ポリシーは、リクエストまたはレスポンスからコンテンツを抽出し、そのコンテンツに変数の値を設定します。ヘッダー、URI パス、JSON ペイロード、XML ペイロード、フォーム パラメータ、クエリ パラメータなど、メッセージの任意の部分を抽出できます。このポリシーは、メッセージ コンテンツにテキスト パターンを適用し、一致を検出すると、指定したメッセージ コンテンツに変数を設定します。

ExtractVariables ポリシーはリクエストやレスポンスのメッセージから情報を抽出するためによく使用されますが、AccessEntity ポリシー、XML オブジェクト、または JSON オブジェクトで作成されたエンティティを含めて、他のソースから情報を抽出するためにも使用できます。

指定されたメッセージ コンテンツを抽出すると、他のポリシーでリクエストとレスポンスの処理の一部としてこの変数を参照できます。

サービス コールアウトに関する注意: サービス コールアウトから変数を抽出するために、このポリシーを使用する必要はありません。ServiceCallout ポリシーには、AssignMessage ポリシーなどに、直接使用できる独自のリクエスト変数とレスポンス変数があります。

このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

動画

注: 次の動画では、Apigee UI の従来のプロキシ エディタについて説明します。Apigee では、プロキシ エディタの新しいバージョンが導入されています。新しいバージョンは、動画に表示される従来のバージョンとは異なります。

ExtractVariables ポリシーの詳細については、次の動画をご覧ください。

動画	説明
XML ペイロードから変数を抽出する	Extract Variable ポリシーを使用して、XML ペイロードから変数を抽出します。
JSON ペイロードから変数を抽出する	Extract Variable ポリシーを使用して、JSON ペイロードから変数を抽出します。
パラメータから変数を抽出する	クエリ、ヘッダー、フォーム、URI パラメータなどのパラメータから、変数を抽出します。
複数の値を持つパラメータから変数を抽出する	複数の値を持つパラメータから変数を抽出します。

サンプル

次の種類のアーティファクトから変数を抽出する方法を、ポリシーのコードサンプルで示します。

URI

<ExtractVariables name="ExtractVariables-1">
   <DisplayName>Extract a portion of the url path</DisplayName>
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/accounts/{id}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

上記のサンプル ポリシーコードについて考えてみましょう。<URIPath> 要素は、ExtractVariables ポリシーに URI パスから情報を抽出するように指示します。<Pattern> 要素は、URI パスに適用するパターンを指定します。パターンは単純なテンプレートとして扱われ、中かっこは URI パスの可変部を示します。

設定する変数の名前は、<VariablePrefix> 要素で指定した値と、<Pattern> 要素の中かっこ {} で囲まれた値によって決まります。2 つの値は、間にあるドットで結合され、たとえば urirequest.id の変数名になります。<VariablePrefix> 要素がない場合、変数名は中かっこで囲まれた値になります。

上記のサンプル ポリシーコードが次の受信リクエストに適用されるとどうなるか考えてみましょう。

GET http://example.com/svc1/accounts/12797282

API プロキシのベースパスが /svc1 であるとします。Apigee は、この受信リクエストに上記の ExtractVariables ポリシーコードを適用するときに、変数 urirequest.id を 12797282 に設定します。Apigee がポリシーを実行した後、処理フロー内の後続のポリシーまたはコードで、urirequest.id という名前の変数を参照して文字列値 12797282 を取得できます。

たとえば、次の AssignMessage ポリシーは、その変数の値を新しいリクエスト メッセージのペイロードに埋め込みます。

<AssignMessage async="false" continueOnError="false" enabled="true" name="AssignPayload">
  <DisplayName>AssignPayload</DisplayName>
    <Set>
      <Payload contentType="text/xml">
        <IdExtractedFromURI>{urirequest.id}</IdExtractedFromURI>
      </Payload>
    </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="true" transport="http" type="request">newRequest</AssignTo>
</AssignMessage>

クエリ パラメータ

<ExtractVariables name="ExtractVariables-2">
   <DisplayName>Extract a value from a query parameter</DisplayName>
   <Source>request</Source>
   <QueryParam name="code">
      <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
   </QueryParam>
   <VariablePrefix>queryinfo</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

上記のサンプル ポリシーコードが次の受信リクエストに適用されるとどうなるか考えてみましょう。

GET http://example.com/accounts/12797282?code=DBN88271

Apigee で、この受信リクエストに上記の ExtractVariables ポリシーコードを適用すると、変数 queryinfo.dbncode が 88271 に設定されます。Apigee でこのポリシーを実行すると、処理フロー内の後続のポリシーまたはコードによって、queryinfo.dbncode という名前の変数が参照され、文字列値 88271 が取得されます。

これで、プロキシの変数 queryinfo.dbncode にアクセスできるようになりました。たとえば、次の AssignMessage ポリシーは、変数値をリクエストのペイロードにコピーします。

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetQP</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <ExtractQP>{queryinfo.dbncode}</ExtractQP>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

複数のパラメータ

<ExtractVariables name="ExtractVariables-2">
  <DisplayName>Extract a value from a query parameter</DisplayName>
  <Source>request</Source>
  <QueryParam name="w">
    <Pattern ignoreCase="true">{firstWeather}</Pattern>
  </QueryParam>
  <QueryParam name="w.2">
    <Pattern ignoreCase="true">{secondWeather}</Pattern>
  </QueryParam>
  <VariablePrefix>queryinfo</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

同じ名前のクエリ パラメータを複数指定できるように API を設計した場合、ExtractVariables ポリシーを使用すると、クエリ パラメータの複数のインスタンスの値を抽出できます。ポリシー内の同じ名前のクエリ パラメータを参照するには、クエリ パラメータの最初のインスタンスはインデックスなし、2 番目は 2、3 番目は 3 などと順に追加したインデックスを使用します。

上記のサンプル ポリシーコードが次の受信リクエストに適用されるとどうなるか考えてみましょう。

GET http://example.com/weather?w=Boston&w=Chicago

Apigee で、この受信リクエストに上記の ExtractVariables ポリシーコードを適用すると、変数 queryinfo.firstWeather が Boston に、変数 queryInfo.secondWeather が Chicago に設定されます。

これで、プロキシで変数 queryinfo.firstWeather と queryinfo.secondWeather にアクセスできるようになりました。たとえば次の AssignMessage ポリシーは、これをリクエストのペイロードにコピーします。

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetQP</DisplayName>
  <Set>
    <Payload contentType="text/xml">
      <ExtractQP1>{queryinfo.firstWeather}</ExtractQP1>
      <ExtractQP2>{queryinfo.secondWeather}</ExtractQP2>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

ヘッダー

<ExtractVariables name='ExtractVariable-OauthToken'>
  <Source>request</Source>
  <Header name="Authorization">
    <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
  </Header>
  <VariablePrefix>clientrequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

API で OAuth v2.0 署名なしトークンを使用しているとします。上記のサンプル ポリシー コードで、Authorization: Bearer TU08xptfFfeM7aS0xHqlxTgEAdAM. のようなヘッダーが含まれる OAuth v2.0 トークンを送信するリクエストを考えてみましょう。

API の設計者は、キャッシュ ルックアップのキーに、ヘッダー全体ではなくトークン値を使用したいとします。上記の ExtractVariables ポリシーコードを使用するとトークンを抽出できます。

Apigee で、このヘッダーに上記の ExtractVariables ポリシーコードを適用すると、変数 clientrequest.oauthtoken が TU08xptfFfeM7aS0xHqlxTgEAdAM に設定されます。

これで、プロキシで変数 clientrequest.oauthtoken にアクセスできるようになりました。たとえば次の AssignMessage ポリシーは、これをリクエストのペイロードにコピーします。

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetHeader</DisplayName>
  <Set>
    <Payload contentType="text/xml">
      <ExtractHeader>{clientrequest.oauthtoken}</ExtractHeader>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

JSON

<ExtractVariables name="ExtractVariables-3">
  <Source>response</Source>
  <JSONPayload>
    <Variable name="latitude" type="float">
      <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude" type="float">
      <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
  <VariablePrefix>geocoderesponse</VariablePrefix>
</ExtractVariables>

次の JSON レスポンス ペイロードについて考えます。

{
  "results": [{
    "geometry": {
      "location": {
        "lat": 37.42291810,
        "lng": -122.08542120
      },
      "location_type": "ROOFTOP",
      "viewport": {
        "northeast": {
          "lat": 37.42426708029149,
          "lng": -122.0840722197085
        },
        "southwest": {
          "lat": 37.42156911970850,
          "lng": -122.0867701802915
        }
      }
    }
  }]
}

Apigee で、この JSON メッセージに上記の ExtractVariables ポリシーコードを適用すると、geocoderesponse.latitude と geocoderesponse.longitude の 2 つの変数が設定されます。どちらの変数も、同じ変数の接頭辞 geocoderesponse を使用します。これらの変数の接尾辞は、<Variable> 要素の name 属性によって明示的に指定されます。

変数 geocoderesponse.latitude は値 37.42291810 を取得します。変数 geocoderesponse.longitude は値 -122.08542120 を取得します。

これで、プロキシで変数 geocoderesponse.latitude にアクセスできるようになりました。たとえば、次の AssignMessage ポリシーは、レスポンス内の latitude という名前のヘッダーにこの変数をコピーします。

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetJSONVar</DisplayName>
  <Add>
    <Headers>
      <Header name="latitude">{geocoderesponse.latitude}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/> 
</AssignMessage>

XML

<ExtractVariables name="ExtractVariables-4">
   <Source>response</Source>
   <XMLPayload>
      <Namespaces>
         <Namespace prefix="dir">urn:43BFF88D-D204-4427-B6BA-140AF393142F</Namespace>
      </Namespaces>
      <Variable name="travelmode" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/@mode</XPath>
      </Variable>
      <Variable name="duration" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/dir:duration/dir:value</XPath>
      </Variable>
      <Variable name="timeunit" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/dir:duration/dir:text</XPath>
      </Variable>
   </XMLPayload>
   <VariablePrefix>directionsresponse</VariablePrefix>
</ExtractVariables>

次の XML レスポンス ペイロードを見てください。

<Directions xmlns="urn:43BFF88D-D204-4427-B6BA-140AF393142F">
   <status>OK</status>
   <route>
      <summary>I-40 W</summary>
      <leg>
         <step mode="DRIVING">
            <start_location>
               <lat>41.8507300</lat>
               <lng>-87.6512600</lng>
            </start_location>
            <end_location>
               <lat>41.8525800</lat>
               <lng>-87.6514100</lng>
            </end_location>
            <duration>
                <value>19</value>
                <text>minutes</text>
            </duration>
         </step>
      </leg>
   </route>
</Directions>

Apigee で、この XML メッセージに上記の ExtractVariables ポリシーコードを適用すると、次の 3 つの変数が設定されます。

• directionsresponse.travelmode: 値 DRIVING を取得します。
• directionsresponse.duration: 値 19 を取得します。
• directionsresponse.timeunit: 値 minutes を取得します。

すべての変数で、同じ変数接頭辞 directionsresponse を使用します。これらの変数の接尾辞は、<Variable> 要素の name 属性によって明示的に指定されます。

これで、プロキシで変数 directionresponse.travelmode にアクセスできるようになりました。たとえば、次の AssignMessage ポリシーは、レスポンス内の tmode という名前のヘッダーにこの変数をコピーします。

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetXMLVar</DisplayName>
  <Add>
    <Headers>
      <Header name="tmode">{directionsresponse.travelmode}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

注: Content-Type の設定: XML メッセージ（SOAP を含む）から変数を抽出する場合、Content-Type がメッセージ ヘッダー（または SOAP ヘッダー）に設定されている場合にのみ変数の抽出が行われます。（例: application/xml）

ExtractVariables ポリシーについて

API デベロッパーは、ヘッダー、URI パス、ペイロード、クエリ パラメータなどのメッセージ コンテンツに基づいて異なる動作をする API プロキシを構築します。多くの場合、プロキシはこのコンテンツの一部を抽出し、条件文で使用します。抽出するために使われるのが ExtractVariables ポリシーです。

ExtractVariables ポリシーを定義する場合、次のいずれかを選択できます。

• 設定する変数の名前
• 変数のソース
• 抽出と設定を行う変数の数

ポリシーが実行されると、コンテンツにテキスト パターンが適用され、一致するものが見つかると、指定された変数の値がそのコンテンツに設定されます。他のポリシーやコードはこれらの変数を使用して、動的な動作を有効にすることや、ビジネスデータを Apigee API Analytics に送信することができます。

警告: Apigee では、リクエストの処理中に多数の変数が自動的に設定されます。フロー変数のリファレンスをご覧ください。他の変数の設定には ExtractVariables ポリシーを使用してください。

スコープ

ExtractVariables ポリシーで設定された変数には、グローバル スコープがあります。つまり、ExtractVariables ポリシーで新しい変数が定義されると、フローの任意のステージ（ExtractVariables ポリシーの後に実行される）で、任意のポリシーまたはコードでその変数にアクセスできます。次の変数が含まれます。

• PreFlow: ProxyEndpoint と TargetEndpoint（リクエストとレスポンス）
• PostFlow: ProxyEndpoint と TargetEndpoint（リクエストとレスポンス）
• PostClientFlow: ProxyEndpoint（レスポンスのみ。MessageLogging ポリシーを使用）
• エラーフロー

ヒント: 新しく抽出された変数がデバッグツールに表示されない場合、<VariablePrefix> 要素を追加したのであれば、削除してみてください。詳細については、ExtractVariables がトレースに表示されないをご覧ください。

照合と変数の作成について

ExtractVariables ポリシーは、リクエストまたはレスポンスから情報を抽出し、その情報を変数に書き込みます。URI パスや XML データなど、抽出できる情報の種類ごとに、照合するパターンと、抽出された情報の保持に使用する変数の名前を指定します。

ただし、パターン マッチングの方法は抽出する情報の種類によって異なります。次のセクションでは、抽出できる情報の 2 つの基本的なカテゴリについて説明します。

URI パス、クエリ パラメータ、ヘッダー、フォーム パラメータ、変数の照合

URI パス、クエリ パラメータ、ヘッダー、フォーム パラメータ、変数から情報を抽出する場合、<Pattern> タグを使用して、照合する 1 つ以上のパターンを指定します。たとえば次のポリシー サンプルは、URI パスの照合パターンを 1 つ示しています。

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

この例では urirequest.pathSeg 変数が、proxy.pathsuffix の /a/ の後ろの部分にあるものに設定されます。たとえば、API プロキシのベースパスが /basepath/v1 であるとすると、http://myCo.com/basepath/v1/a/b へのインバウンド リクエストでは変数が b に設定されます。

複数のパターンを指定する

照合の複数のパターンを、<Pattern> タグに対応して次のように指定できます。

• すべてのパターンが照合される。
• 一致するパターンがない場合、ポリシーは何もせず、変数も作成されない。
• 複数のパターンが一致する場合、最長のパスセグメントを持つパターンが抽出に使用される。
• 一致したパターンの 2 つのパターンが同じ長いパスセグメントを持つ場合、ポリシー内で最初に指定されたパターンが抽出に使用される。

次の例では、URI パスに対して 3 つの照合パターンを含むポリシーを作成します。

<ExtractVariables name="ExtractVariables-1">
  <Source>request</Source>
  <URIPath>
    <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
    <Pattern ignoreCase="true">/a/b/{pathSeg}</Pattern>
    <Pattern ignoreCase="true">/a/b/c/{pathSeg}</Pattern>
  </URIPath>
  <VariablePrefix>urirequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

ベースパスが /basepath/v1 の API プロキシの場合、API プロキシへのインバウンド リクエスト URL は次のようになります。

http://myCo.com/basepath/v1/a/b

この例では、最初のパターンが URI と一致し、urirequest.pathSeg 変数が b に設定されます。

リクエスト URL が、

http://myCo.com/basepath/v1/a/b/c/d

の場合、3 つ目のパターンが一致し、urirequest.pathSeg 変数は d に設定されます。

複数の変数を含むパターンを指定する

マッチング パターンに複数の変数を指定できます。たとえば、照合パターンを 2 つの変数で指定します。

<ExtractVariables name="ExtractVariables-1">
  <Source>request</Source>
  <URIPath>
    <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
    <Pattern ignoreCase="true">/a/b/{pathSeg}</Pattern>
    <Pattern ignoreCase="true">/a/{pathSeg1}/c/{pathSeg2}</Pattern>
  </URIPath>
  <VariablePrefix>urirequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

次のインバウンド リクエスト URL で、API プロキシのベースパスがまた /basepath/v1 であるとします。

http://myCo.com/basepath/v1/a/b/c/d

urirequest.pathSeg1 変数は b に設定され、urirequest.pathSeg2 変数は d に設定されます。

パターンで複数のインスタンスを照合する

同じ名前を持つ項目のインスタンスが複数ある場合も、マッチング パターンを使用できます。たとえば、同じ名前を持つ、複数のクエリ パラメータや複数のヘッダーを含むリクエストを作成できます。次のリクエストには、「w」という名前のクエリ パラメータが 2 つ含まれています。

http://myCo.com/basepath/v1/a/b/c/d?w=1&w=2

この複数のクエリ パラメータを ExtractVariables ポリシーで参照するには、名前にインデックスを使用します。ここでは、クエリ パラメータの最初のインスタンスはインデックスなし、2 番目は 2、3 番目は 3 のようにインデックスを追加します。たとえば、次のポリシーは、リクエスト内で 2 番目にある「w」という名前のクエリ パラメータの値を抽出します。

<ExtractVariables name="ExtractVariables-1">
  <Source>request</Source>
  <QueryParam name="w.2">
    <Pattern ignoreCase="true">{secondW}</Pattern>
  </QueryParam>
  <VariablePrefix>urirequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

urirequest.secondW 変数は「2」に設定されます。2 番目のクエリ パラメータがリクエストから除外されている場合、urirequest.secondW 変数は空になります。リクエストに同じ名前の項目が複数ある場合は、常にインデックスを使用します。

パターンに特殊文字を使用する

URI パスのマッチングでは、パターンにワイルドカード文字 * と ** を使用できます。ここで、

• * はパスの任意の 1 つのセグメントに一致します
• 「**」はパスの複数のセグメントに一致します

たとえば、次のように <URIPath> 要素にパターンを指定します。

<URIPath>
  <Pattern ignoreCase="true">/a/*/{id}</Pattern>
  <Pattern ignoreCase="true">/a/**/{id}</Pattern>
</URIPath>

最初のパターンは、「/a/b/c」、「/a/foo/bar」など、パスの接尾辞（ベースパスに続く URI パスの一部）を持つリクエストに一致します。2 つ目のパターンは、「/a/」に続く任意の数のパスセグメント（「/a/foo/bar/baz/c」、「/a/b/c」、「/a/foo/bar」など）に一致します。

クエリ パラメータ、ヘッダー、フォーム パラメータに対してパターンを指定する場合、* 文字は任意の数の文字と一致することを意味します。たとえばヘッダーの照合でパターンを次のように指定すると、

*;charset={encoding}

このパターンは、「text/xml;charset=UTF-16」と「application/xml;charset=ASCII」という値と一致します。

ExtractVariables ポリシーに渡す値に「{」などの特殊文字が含まれている場合は、「%」の文字を使用してエスケープします。次の例では、クエリ パラメータの値で「{」と「}」がリテラル文字として使用されているため、パターンの中ではこれらの文字をエスケープしています。

<QueryParam>
  <Pattern ignoreCase="true">%{user%} {name}</Pattern>
</QueryParam>

この場合、パターンは値「{user} Steve」に一致しますが、値「user Steve」には一致しません。

JSON と XML の照合

JSON と XML からデータを抽出するときは、ポリシーに 1 つ以上の <Variable> タグを指定します。<Variable> タグにより、抽出された情報を保存する宛先変数の名前、および抽出された情報への JsonPath（JSON）または XPATH（XML）が指定されます。

ポリシー内のすべての <Variable> タグが評価されるため、1 つのポリシーから複数の変数を入力できます。<Variable> タグが JSON または XML の有効なフィールドに評価されない場合、対応する変数は作成されません。

レスポンスの JSON 本文から 2 つの変数に値を入力する ExtractVariables ポリシーの例を次に示します。

<ExtractVariables name="ExtractVariables-3">
   <Source>response</Source>
   <JSONPayload>
      <Variable name="latitude" type="float">
         <JSONPath>$.results[0].geometry.location.lat</JSONPath>
      </Variable>
      <Variable name="longitude" type="float">
         <JSONPath>$.results[0].geometry.location.lng</JSONPath>
      </Variable>
   </JSONPayload>
   <VariablePrefix>geocoderesponse</VariablePrefix>
</ExtractVariables>

複数の場所で同じ変数に書き込む

設定する変数の名前を選択するときは注意が必要です。ポリシーは、最初の抽出パターンから最後の抽出パターンまで、順番に実行されます。複数の場所から同じ変数に値を書き込むポリシーの場合、変数の値はポリシーの最後の書き込みで決まります（これがユーザーの意図どおりの場合もあります）。

次に示すポリシー サンプルは、クエリ パラメータにもヘッダーにも渡される可能性があるトークン値を抽出します。

<!-- If token only in query param, the query param determines the value. 
     If token is found in both the query param and header, header sets value. -->
<QueryParam name="token">
  <Pattern ignoreCase="true">{tokenValue}</Pattern>
</QueryParam>
 
<!-- Overwrite tokenValue even if it was found in query parameter. -->
<Header name="Token">
  <Pattern ignoreCase="true">{tokenValue}</Pattern>
</Header>

一致しない場合の処理を制御する

パターンが一致しない場合、対応する変数は作成されません。したがって、別のポリシーが変数を参照すると、エラーが発生するおそれがあります。

対策としては、変数を参照するポリシーで <IgnoreUnresolvedVariables> を true に設定し、解決できない変数を空の文字列（null）として処理します。

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

要素リファレンス

要素リファレンスでは、ExtractVariables ポリシーの要素と属性について説明します。

<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">
   <DisplayName> 1</DisplayName>
   <Source clearPayload="true|false">request</Source>
   <VariablePrefix>myprefix</VariablePrefix>
   <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
   <URIPath>
      <Pattern ignoreCase="false">/accounts/{id}</Pattern>
   </URIPath>
   <QueryParam name="code">
      <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
   </QueryParam>
   <Header name="Authorization">
      <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
   </Header>
   <FormParam name="greeting">
      <Pattern>hello {user}</Pattern>
   </FormParam>
   <Variable name="request.content">
       <Pattern>hello {user}</Pattern>
   </Variable>
   <JSONPayload>
      <Variable name="name">
         <JSONPath>{example}</JSONPath>
      </Variable>
   </JSONPayload>
   <XMLPayload stopPayloadProcessing="false">
      <Namespaces/>
      <Variable name="name" type="boolean">
         <XPath>/test/example</XPath>
      </Variable>
   </XMLPayload>
</ExtractVariables>

<ExtractVariables> 属性

<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">

次の表に、すべてのポリシーの親要素に共通する属性を示します。

属性	説明	デフォルト	要否
name	ポリシーの内部名。name 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。 管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。	なし	必須
continueOnError	ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。 ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連項目: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について） 現在のフローにおける障害処理	false	省略可
enabled	ポリシーを適用するには、true に設定します。 ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。	true	省略可
async	この属性は非推奨となりました。	false	非推奨

<DisplayName> 要素

管理 UI プロキシ エディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

<DisplayName>Policy Display Name</DisplayName>

デフォルト	なし この要素を省略した場合、ポリシーの name 属性の値が使用されます。
要否	省略可
タイプ	文字列

<Source> 要素

（省略可）解析する変数を指定します。<Source> の値がデフォルトの message に設定されます。message 値はコンテキストに依存します。リクエスト フローで、message がリクエスト メッセージに解決されます。レスポンス フローの中では、message はレスポンス メッセージになります。

このポリシーはリクエストやレスポンスのメッセージから情報を抽出するためによく使用されますが、任意の変数から情報を抽出するためにも使用できます。たとえば、このエンティティを使用すると、AccessEntity ポリシーによって作成されたエンティティ、ServiceCallout ポリシーによって返されたデータ、XML や JSON オブジェクトから抽出された情報などから情報を抽出できます。

<Source> を解決できない場合、またはメッセージ以外のタイプに解決される場合、ポリシーはレスポンスを返しません。

<Source clearPayload="true|false">request</Source>

デフォルト:	message
要否:	省略可
型:	文字列

属性

属性	説明	デフォルト	要否	型
clearPayload	<Source> で指定されたペイロードをデータの抽出後にクリアする場合は、true に設定します。 <clearPayload> オプションは、ExtractVariables の実行後にソース メッセージが不要な場合にのみ使用します。true に設定すると、メッセージに使用されていたメモリが解放されます。	false	省略可	ブール値

<VariablePrefix> 要素

（省略可）<VariablePrefix>、ドット、中括弧 {} で定義されている名前、<Pattern> 要素や <Variable> 要素を接続して完全な変数名が作られます。たとえば、myprefix.id、myprefix.dbncode、myprefix.oauthtoken. などです。

<VariablePrefix>myprefix</VariablePrefix>

たとえば、名前に「user」という値を指定した場合、

• <VariablePrefix> が指定されていない場合、抽出された値は user という名前の変数に割り当てられます。
• <VariablePrefix> が myprefix として指定されている場合、抽出された値は myprefix.user という名前の変数に割り当てられます。

デフォルト:	なし
要否:	省略可
型:	文字列

<IgnoreUnresolvedVariables> 要素

（省略可）true に設定すると、解決できない変数を空の文字列（null）として扱います。参照される変数を解決できない場合にポリシーがエラーをスローするようにするには、false に設定します。

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

デフォルト:	False
要否:	省略可
型:	ブール値

<URIPath> 要素

（省略可。ただし、詳細については、下表の「要否」の行をご覧ください。）request ソース メッセージの proxy.pathsuffix から値を抽出します。パターンに適用されるパスは proxy.pathsuffix で、API プロキシのベースパスは含まれません。ソース メッセージが response のメッセージ タイプに解決される場合、この要素は何もしません。

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
</URIPath>

複数の <Pattern> 要素を使用できます。

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
   <Pattern ignoreCase="false">/accounts/{id}/transactions/{index}</Pattern>
</URIPath>

デフォルト:	なし
要否:	省略可。ただし、<URIPath>、<QueryParam>、<Header>、<FormParam>、<JSONPayload>、<XMLPayload>. のうち少なくとも 1 つを含める必要があります。
型:	なし

属性

属性	説明	デフォルト	要否	型
ignoreCase	大文字小文字を無視してパターン マッチングを行うかどうか指定します。	false	省略可	ブール値

<QueryParam> 要素

（省略可。ただし、詳細については、下表の「要否」の行をご覧ください。）request ソース メッセージの指定されたクエリ パラメータから値を抽出します。ソース メッセージが response のメッセージ タイプに解決される場合、この要素では何も行われません。

<QueryParam name="code">
   <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
</QueryParam>

同じ名前のクエリ パラメータが複数ある場合は、インデックスを使用してパラメータを参照します。

<QueryParam name="w.2">
   <Pattern ignoreCase="true">{secondW}</Pattern>
</QueryParam>

デフォルト:	なし
要否:	省略可。ただし、<URIPath>、<QueryParam>、<Header>、<FormParam>、<JSONPayload>、<XMLPayload>. のうち少なくとも 1 つを含める必要があります。
型:	なし

属性

属性	説明	デフォルト	要否	型
name	クエリ パラメータの名前を指定します。複数のクエリ パラメータの名前が同じ場合、インデックス付きの参照を使用し、クエリ パラメータの最初のインスタンスはインデックスなし、2 番目は 2、3 番目は 3 のようにインデックスを追加します。	なし	必須	文字列

<Header> 要素

（省略可。ただし、詳細については、下表の「要否」の行をご覧ください。）指定された request メッセージまたは response メッセージにある、指定された HTTP ヘッダーから値を抽出します。複数のヘッダーの名前が同じ場合、その値は配列形式で格納されます。

<!-- The name is the actual header name. -->
<Header name="Authorization">
<!-- Provide a name for your new custom variable here. -->
   <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
</Header>

複数のヘッダーの名前が同じ場合、インデックスを使用して配列内の個々のヘッダーを参照します。

<Header name="myHeader.2">
   <Pattern ignoreCase="true">{secondHeader}</Pattern>
</Header>

または次のようにして、配列内のすべてのヘッダーを一覧表示します。

<Header name="myHeader.values">
   <Pattern ignoreCase="true">{myHeaders}</Pattern>
</Header>

デフォルト:	なし
要否:	省略可。ただし、<URIPath>、<QueryParam>、<Header>、<FormParam>、<JSONPayload>、<XMLPayload>. のうち少なくとも 1 つを含める必要があります。
型:	なし

属性

属性	説明	デフォルト	要否	型
name	値を抽出するヘッダーの名前を指定します。複数のヘッダーの名前が同じ場合、インデックス付きの参照を使用し、ヘッダーの最初のインスタンスはインデックスなし、2 番目は 2、3 番目は 3 のようにインデックスを追加します。配列内のすべてのヘッダーを取得するには、.values を使用します。	なし	必須	文字列

<FormParam> 要素

（省略可。ただし、詳細については、下表の「要否」の行をご覧ください。）指定された request または response メッセージにある、指定されたフォーム パラメータから値を抽出します。フォーム パラメータは、指定したメッセージの Content-Type ヘッダーが application/x-www-form-urlencoded の場合にのみ抽出できます。

<FormParam name="greeting">
    <Pattern>hello {user}</Pattern>
</FormParam>

デフォルト:	なし
要否:	省略可。ただし、<URIPath>、<QueryParam>、<Header>、<FormParam>、<JSONPayload>、<XMLPayload>. のうち少なくとも 1 つを含める必要があります。
型:	なし

属性

属性	説明	デフォルト	要否	型
name	値を抽出するフォーム パラメータの名前。	なし	必須	文字列

<Variable> 要素

（省略可。詳細は下記の表の「要否」行をご覧ください）値を抽出する変数の名前を指定します。

<Variable name="myVar">
    <Pattern>hello {user}</Pattern>
</Variable>

変数から 2 つの値を抽出するには、次のようにします。

<Variable name="myVar">
   <Pattern>hello {firstName} {lastName}</Pattern>
</Variable>

デフォルト:	なし
要否:	省略可。ただし、<URIPath>、<QueryParam>、<Header>、<FormParam>、<JSONPayload>、<XMLPayload>. のうち少なくとも 1 つを含める必要があります。
型:	なし

属性

属性	説明	デフォルト	要否	型
name	値を抽出する変数の名前。	なし	必須	文字列

<JSONPayload> 要素

（省略可。詳細は下記の表の「要否」行をご覧ください）変数の値を抽出する JSON 形式のメッセージを指定します。JSON 抽出は、メッセージの Content-Type ヘッダーが application/json の場合にのみ実行されます。

<JSONPayload>
   <Variable name="name" type="string">
      <JSONPath>{example}</JSONPath>
   </Variable>
</JSONPayload>

デフォルト:	なし
要否:	省略可。ただし、<URIPath>、<QueryParam>、<Header>、<FormParam>、<JSONPayload>、<XMLPayload>. のうち少なくとも 1 つを含める必要があります。
型:	なし

<JSONPayload> / <Variable> 要素

（JSONPayload 要素内で必須）抽出された値が割り当てられる変数を指定します。<JSONPayload> 要素に複数の <Variable> タグを含めると、複数の変数を入力できます。

<Variable name="name" type="string">
   <JSONPath>{example}</JSONPath>
</Variable>

デフォルト:	なし
要否:	JSONPayload 要素内で必須
型:	なし

属性

属性	説明	デフォルト	要否	型
name	抽出された値を割り当てる変数の名前を指定します。	name	必須	文字列
type	変数値のデータ型を指定します。	なし	省略可	文字列。次から選択: string boolean integer long float double nodeset（JSON フラグメントを返します）

<JSONPayload> / <Variable> / <JSONPath> 要素

（JSONPayload: Variable 要素内で必須）JSON 形式のメッセージから値を抽出するために使用される、JSON パスを指定します。

注: <JSONPath> 要素は、メッセージ テンプレートと呼ばれる動的な文字列置換機能をサポートしています。

<Variable name="name">
  <JSONPath>$.rss.channel.title</JSONPath>
</Variable>

デフォルト:	なし
要否:	必須
型:	文字列

<XMLPayload> 要素

（省略可。詳細は下記の表の「要否」行をご覧ください）変数の値を抽出する XML 形式のメッセージを指定します。XML ペイロードは、メッセージの Content-Type ヘッダーが text/xml、application/xml、application/*+xml の場合にのみ抽出されます。

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
    <Namespace prefix="apigee">http://www.apigee.com</Namespace>
    <Namespace prefix="gmail">http://mail.google.com</Namespace>
  </Namespaces>
  <Variable name="name" type="boolean">
    <XPath>/apigee:test/apigee:example</XPath>
  </Variable>
</XMLPayload>

デフォルト:	なし
要否:	省略可。ただし、<URIPath>、<QueryParam>、<Header>、<FormParam>、<JSONPayload>、<XMLPayload>. のうち少なくとも 1 つを含める必要があります。
型:	なし

属性

属性	説明	デフォルト	要否	型
stopPayloadProcessing	1 つの変数が入力された後に XPath 評価を停止するには、true に設定します。つまり、ポリシーによって代入される変数は 1 つのみです。	false	省略可	ブール値

<XMLPayload> / <Namespaces> 要素

（省略可）XPath 評価で使用する名前空間を指定します。XPath 式で名前空間を使用している場合、次の例に示すように、ここで名前空間を宣言する必要があります。

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
     <Namespace prefix="gmail">http://mail.google.com</Namespace>
  </Namespaces>
  <Variable name="legName" type="string">
    <XPath>/apigee:Directions/apigee:route/apigee:leg/apigee:name</XPath>
  </Variable>
</XMLPayload>

XPath 式で名前空間を使用しない場合は、次の例のように <Namespaces> 要素を省略またはコメントアウトできます。

<XMLPayload stopPayloadProcessing="false">
  <!-- <Namespaces/> -->
  <Variable name="legName" type="string">
    <XPath>/Directions/route/leg/name</XPath>
  </Variable>
</XMLPayload>

デフォルト:	なし
要否:	省略可
型:	文字列

属性

属性	説明	デフォルト	要否	型
prefix	名前空間の接頭辞。	なし	必須	文字列

<XMLPayload> / <Variable> 要素

（省略可）抽出された値を割り当てる変数を指定します。

<Variable name="name" type="boolean">
   <XPath>/test/example</XPath>
</Variable>

デフォルト:	なし
要否:	省略可
型:	なし

属性

属性	説明	デフォルト	要否	型
name	抽出された値を割り当てる変数の名前を指定します。	name	必須	文字列
type	変数値のデータ型を指定します。	ブール値	省略可	文字列。次から選択: string boolean integer long float double nodeset（XML フラグメントを返します）

<XMLPayload> / <Variable> / <XPath> 要素

（XMLPayload: Variable 要素内で必須）変数に定義された XPath を指定します。XPath 1.0 式のみがサポートされています。

<XPath> 要素は、メッセージ テンプレートをサポートしていません。

<Variable name="name" type="boolean">
   <XPath>/test/example</XPath>
</Variable>

名前空間を伴う例は次のとおりです。XPath 式で名前空間を使用する場合、ポリシーの <XMLPayload><Namespaces> セクションで名前空間を宣言する必要があります。

<Variable name="name" type="boolean">
   <XPath>/foo:test/foo:example</XPath>
</Variable>

デフォルト:	なし
要否:	必須
型:	文字列

注: XPath 式で parent、ancestor、following、preceding を使用することは、Apigee ではサポートされていません。同じ一致結果を得るには、明示的なノード名の一致またはインデックスによる方法を試してください。次に例を示します。

• <XPath>/Attributes/Attribute[@Name=’foo_attribute']/Value</XPath>
  は foo_attribute の値を取得します。
• <XPath>/Attributes/Attribute[4]/Value</XPath>
  は 4 番目の属性の値を取得します。

エラー リファレンス

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

ランタイム エラー

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

ヒント: エラーの解決にサポートが必要な場合は、「修正」列の をクリックして、詳しいトラブルシューティング情報をご覧ください。

障害コード	HTTP ステータス	原因	修正
steps.extractvariables.ExecutionFailed	500	このエラーは、次の場合に発生します。 入力ペイロード（JSON、XML）が空になっている。 ポリシーに渡された入力（JSON、XML など）が無効か、不正な形式になっている。
steps.extractvariables.ImmutableVariable	500	ポリシーで使用されている変数は不変です。ポリシーでこの変数を設定できませんでした。	なし
steps.extractvariables.InvalidJSONPath	500	このエラーは、ポリシーの JSONPath 要素で無効な JSON パスが使用されている場合に発生します。たとえば、JSON ペイロードにオブジェクト Name がない場合、ポリシー内のパスとして Name を指定すると、このエラーが発生します。
steps.extractvariables.JsonPathParsingFailure	500	このエラーは、ポリシーが JSON パスを解析できず、Source 要素で指定されたフロー変数からデータを抽出できない場合に発生します。これは通常、Source 要素で指定されたフロー変数が現在のフローに存在しない場合に発生します。
steps.extractvariables.SetVariableFailed	500	このエラーは、ポリシーが変数に値を設定できなかった場合に発生します。このエラーは通常、名前が同じ単語で始まる複数の変数に、ネストされたドット区切り形式の値を割り当てようとすると発生します。
steps.extractvariables.SourceMessageNotAvailable	500	このエラーは、ポリシーの Source 要素で指定された message 変数が、次のいずれかである場合に発生します。 範囲外（ポリシーが実行されている特定のフローで使用できない） 解決不能（未定義）
steps.extractvariables.UnableToCast	500	このエラーは、ポリシーが抽出された値を変数にキャストできなかった場合に発生します。これは通常、あるデータ型の値を別のデータ型の変数に設定しようとすると発生します。

デプロイエラー

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

ヒント: エラーの解決にサポートが必要な場合は、エラーの原因の説明の横にある をクリックして、トラブルシューティング ページに移動してください。

エラー名	原因	修正
NothingToExtract	ポリシーに URIPath、QueryParam、Header、FormParam、XMLPayload、JSONPayload のいずれの要素も含まれていない場合、抽出するものがないため、API プロキシのデプロイに失敗します。
NONEmptyPrefixMappedToEmptyURI	このエラーは、ポリシーで XMLPayload 要素の下の Namespace 要素に接頭辞が定義されていても URI が定義されていない場合に発生します。
DuplicatePrefix	このエラーは、ポリシーで、XMLPayload 要素の下の Namespace 要素で同じ接頭辞が複数回定義されている場合に発生します。
NoXPathsToEvaluate	ポリシーの XMLPayload 要素内に XPath 要素がない場合、API プロキシのデプロイがこのエラーで失敗します。 XML ペイロードから変数を抽出する場合は、XPath 子要素を指定する必要があります。
EmptyXPathExpression	ポリシーの XMLPayload 要素内に空の XPath 式があると、API プロキシのデプロイが失敗します。
NoJSONPathsToEvaluate	ポリシーの JSONPayload 要素内に JSONPath 要素がない場合、API プロキシのデプロイがこのエラーで失敗します。
EmptyJSONPathExpression	ポリシーの XMLPayload 要素内に空の XPath 式があると、API プロキシのデプロイが失敗します。
MissingName	ポリシーの QueryParam、Header、FormParam、Variable などのポリシー要素のいずれかに、必要な name 属性が含まれていない場合、API プロキシのデプロイが失敗します。
PatternWithoutVariable	ポリシーの Pattern 要素内に変数が指定されていない場合、API プロキシのデプロイが失敗します。Pattern 要素には、抽出されたデータを格納するための変数の名前が必要です。
CannotBeConvertedToNodeset	ポリシーに、Variable 型が nodeset として定義されている XPath 式があるが、式を nodeset に変換できない場合、API プロキシのデプロイが失敗します。
JSONPathCompilationFailed	ポリシーが指定の JSON パスをコンパイルできませんでした。	なし
InstantiationFailed	ポリシーをインスタンス化できませんでした。	なし
XPathCompilationFailed	XPath 要素で使用される接頭辞や値がポリシーで宣言された名前空間の一部でない場合、API プロキシのデプロイが失敗します。
InvalidPattern	Pattern 要素の定義が、ポリシー内の URIPath、QueryParam、Header、FormParam、XMLPayload、JSONPayload などの要素のいずれかで無効である場合、API プロキシのデプロイが失敗します。 Pattern 要素は、変数を含まない場合、無効と見なされます。パターン照合の詳細については、マッチングと変数の作成についてをご覧ください。

障害変数

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

変数	説明	例
fault.name="fault_name"	fault_name は、上記のランタイム エラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。	fault.name = "SourceMessageNotAvailable"
extractvariables.policy_name.failed	policy_name は、障害が発生したポリシーのユーザー指定の名前です。	extractvariables.EV-ParseJsonResponse.failed = true

エラー レスポンスの例

注: ベスト プラクティスとして、エラー処理でエラー レスポンスの errorcode の部分をトラップすることをおすすめします。faultstring のテキストには依存しないでください。この部分は変更される可能性があります。

{
   "fault":{
      "detail":{
         "errorcode":"steps.extractvariables.SourceMessageNotAvailable"
      },
      "faultstring":"request message is not available for ExtractVariable: EV-ParseJsonResponse"
   }
}

障害ルールの例

<FaultRule name="Extract Variable Faults">
    <Step>
        <Name>AM-CustomErrorMessage</Name>
        <Condition>(fault.name = "SourceMessageNotAvailable") </Condition>
    </Step>
    <Condition>(extractvariables.EM-ParseJsonResponse.failed = true) </Condition>
</FaultRule>

スキーマ

サンプル: 最新のスキーマについては、GitHub リポジトリのサンプルをご覧ください。

関連トピック

フロー変数のリファレンス