ExtractVariables ポリシー

概要

Extract Variables ポリシーは、リクエストまたはレスポンスからコンテンツを抽出し、そのコンテンツに変数の値を設定します。ヘッダー、URI パス、JSON / XML ペイロード、フォーム パラメータ、クエリ パラメータなど、メッセージの任意の部分を抽出できます。このポリシーは、メッセージ コンテンツにテキスト パターンを適用し、一致するものを見つけると、変数を設定し、指定されたメッセージ コンテンツを代入するという仕組みになっています。

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

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

動画

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

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

サンプル

これらのポリシーコードのサンプルは、次のタイプのアーティファクトから変数を抽出する方法を示しています。

GitHub

下記のリンクは、Edge でデプロイして実行できる API プロキシのサンプルを指しています。GitHub の Apigee の api-platform-samples リポジトリにあり、いずれも ExtractVariables を使用しています。README では、それぞれの場合に ExtractVariables がどのように使用されるか、また各サンプルをデプロイして実行する方法が説明されています。

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> 要素では、URI パスから情報を抽出するよう Extract Variables ポリシーに指示しています。URI パスに適用するパターンは <Pattern> 要素で指定しています。パターンは単純なテンプレートとして扱われ、中かっこは URI パスの可変部を示します。

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

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

GET http://org1-test.apigee.net/svc1/accounts/12797282

ここで、API プロキシのベースパスは /svc1 とします。Apigee Edge で上記の ExtractVariables ポリシーコードをこの受信リクエストに適用すると、変数 urirequest.id12797282 に設定されます。Apigee Edge でこのポリシーを実行すると、処理フロー内の後続のポリシーやコードで、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>
    
codecodeDBNXXXXXDBNXXXXX

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

GET http://org1-test.apigee.net/accounts/12797282?code=DBN88271

Apigee Edge で上記の Extract Variables ポリシーコードをこの受信リクエストに適用すると、変数 queryinfo.dbncode88271 に設定されます。Apigee Edge でこのポリシーを実行すると、処理フロー内の後続のポリシーやコードで、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 を設計した場合、このポリシーを使用すると、上のサンプルのようにクエリ パラメータ「w」の複数のインスタンスの値を抽出できます。複数のクエリ パラメータを Extract Variables ポリシーで参照するには、名前にインデックスを使用し、クエリ パラメータの最初のインスタンスはインデックスなし、2 番目は 2、3 番目は 3 のようにインデックスを追加します。

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

GET http://org1-test.apigee.net/weather?w=Boston&w=Chicago

Apigee Edge で上記の Extract Variables ポリシーコードをこの受信リクエストに適用すると、変数 queryinfo.firstWeatherBoston に、変数 queryInfo.secondWeatherChicago に設定されます。

これで、プロキシの変数 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 デザイナーは、上記の Extract Variables ポリシーコードを使用してトークンを抽出できます。

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

これで、プロキシの変数 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>
    
<JSONPayload>$

次の 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 Edge で上記の Extract Variables ポリシーコードをこの JSON メッセージに適用すると、geocoderesponse.latitudegeocoderesponse.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>
    
<XMLPayload>

次の 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>
    </DirectionsResponse>
    

Apigee Edge で上記の Extract Variables ポリシーコードをこの XML メッセージに適用すると、directionsresponse.travelmode,directionsresponse.durationdirectionsresponse.timeunit の 3 つの変数が設定されます。変数はすべて、同じ変数接頭辞 directionsresponse を使用しています。この変数の接尾辞は、<Variable> 要素の name 属性で明示的に指定されています。

変数 directionsresponse.travelmode は、値 DRIVING を取得します。変数 directionsresponse.duration は、値 19 を取得します。変数 directionsresponse.timeunit は、値 minutes を取得します。

これで、プロキシの変数 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>
    

Extract Variables ポリシーについて

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

Extract Variables ポリシーを定義するときは、次の選択が可能です。

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

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

コンテンツ ドリブン分析レポートの作成に Extract Variables を使用する方法については、カスタム分析を使用して API メッセージ コンテンツを分析するをご覧ください。

範囲

Extract Variables ポリシーで設定された変数には、グローバル スコープが与えられます。つまり、Extract Variables ポリシーで定義された新しい変数には、Extract Variables ポリシーが実行されたの処理フロー段階で実行される任意のポリシーやコードからアクセスできます。これには次のものが含まれます。

  • PreFlow: ProxyEndpoint と TargetEndpoint(リクエストとレスポンス)
  • PostFlow: ProxyEndpoint と TargetEndpoint(リクエストとレスポンス)
  • PostClientFlow: ProxyEndpoint(レスポンスのみ。Message Logging ポリシーを使用)
  • エラーフロー

マッチングと変数の作成について

Extract Variables ポリシーは、リクエストやレスポンスから情報を抽出し、その情報を変数に書き込みます。抽出できる情報の種類(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>
    

API プロキシのベースパスが /basepath/v1 で、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>
    

前述の例と同様に、API プロキシのベースパスが /basepath/v1 で、受信リクエスト URL が次の形式の場合、

    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
    

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

    <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/b/c」や「/a/foo/bar」に加え「/a/foo/bar/baz/c」など、/a/ に続くセグメントに一致します。

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

*;charset={encoding}

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

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

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

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

JSON と XML のマッチング

JSON と XML からデータを抽出するときは、ポリシーに <Variable> タグを 1 つ以上指定します。<Variable> タグでは、抽出した情報を格納する宛先変数の名前と、抽出する情報への JsonPath(JSON の場合)または XPATH(XML の場合)を指定します。

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

次のポリシー サンプルは、レスポンスの JSON 本文から 2 つの変数を代入する Extract Variables ポリシーを示しています。

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

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

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

選択肢の 1 つとして、変数を参照するポリシーで <IgnoreUnresolvedVariables> を true に設定し、解決できない変数を空の文字列(null)として扱うようにポリシーを構成することが挙げられます。

    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    

要素リファレンス

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

    <ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">
       <DisplayName>Extract Variables 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 に設定します。

false 省略可
enabled

ポリシーを適用するには true に設定します。

ポリシーを無効にするには false に設定します。その場合、ポリシーはフローに接続されていているとしても適用されません。

true 省略可
async

この属性は非推奨となりました。

false 非推奨

<DisplayName> 要素

name 属性に加えて、管理 UI プロキシ エディタのポリシーに別のわかりやすい名前でラベルを付けるために使います。

<DisplayName>Policy Display Name</DisplayName>
デフォルト:

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます

要否: 省略可
型: 文字列

<Source> 要素

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

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

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

    <Source clearPayload="true|false">request</Source>
    
デフォルト: message
要否: 省略可
型: String

属性

属性 説明 デフォルト 要否
clearPayload

true に設定すると、データを抽出した後に <Source> で指定されたペイロードが消去されます。

<clearPayload> オプションは、ExtractVariables の実行後にソース メッセージが不要な場合にのみ使用します。true に設定すると、メッセージによって使用されたメモリが解放されます。

false

省略可 ブール値

<VariablePrefix> 要素

(省略可)完全な変数名は、<VariablePrefix> とドットに続けて、<Pattern> 要素の中かっこ {} で囲まれた名前か、<Variable> 要素で定義された名前を結合することで生成されます。例: myprefix.idmyprefix.dbncodemyprefix.oauthtoken.

    <VariablePrefix>myprefix</VariablePrefix>
    

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

  • <VariablePrefix> が指定されていない場合、抽出された値は user という名前の変数に割り当てられます。
  • <VariablePrefix> が myprefix として指定されている場合、抽出された値は myprefix.user という名前の変数に割り当てられます。
デフォルト: なし
必須?: 省略可
型: 文字列

<IgnoreUnresolvedVariables> 要素

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

    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    
デフォルト: false
要否: 省略可
型: ブール値

<URIPath> 要素

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

    <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>
    
デフォルト: なし
要否: 省略可。ただし、次のうち少なくとも 1 つが含まれている必要があります。<URIPath><QueryParam><Header><FormParam><JSONPayload><XMLPayload>.
型: なし

属性

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

false

省略可 ブール値

<QueryParam> 要素

(省略可。詳細は下記の表の「要否」行をご覧ください)リクエスト ソース メッセージの指定されたクエリ パラメータから値を抽出します。ソース メッセージがレスポンスのメッセージ タイプに解決された場合、この要素は何もしません。

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

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

    <QueryParam name="w.2">
       <Pattern ignoreCase="true">{secondW}</Pattern>
    </QueryParam>
    
デフォルト: なし
要否: 省略可。ただし、次のうち少なくとも 1 つが含まれている必要があります。<URIPath><QueryParam><Header><FormParam><JSONPayload><XMLPayload>.
型: なし

属性

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

なし

必須 文字列

<Header> 要素

(省略可。詳細は下記の表の「要否」行をご覧ください)指定されたリクエスト メッセージやレスポンス メッセージの、指定された 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>
    
デフォルト: なし
要否: 省略可。ただし、次のうち少なくとも 1 つが含まれている必要があります。<URIPath><QueryParam><Header><FormParam><JSONPayload><XMLPayload>.
型: なし

属性

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

なし

必須 文字列

<FormParam> 要素

(省略可。詳細は下記の表の「要否」行をご覧ください)指定されたリクエスト メッセージやレスポンス メッセージの、指定されたフォーム パラメータから値を抽出します。フォーム パラメータは、指定されたメッセージの Content-Type ヘッダーが application/x-www-form-urlencoded の場合にのみ抽出できます。

    <FormParam name="greeting">
        <Pattern>hello {user}</Pattern>
    </FormParam>
    
デフォルト: なし
要否: 省略可。ただし、次のうち少なくとも 1 つが含まれている必要があります。<URIPath><QueryParam><Header><FormParam><JSONPayload><XMLPayload>.
型: なし

属性

属性 説明 デフォルト 要否
name 値を抽出するフォーム パラメータの名前。

なし

必須 文字列

<Variable> 要素

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

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

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

    <Variable name="myVar">
       <Pattern>hello {firstName} {lastName}</Pattern>
    </Variable>
    
デフォルト: なし
要否: 省略可。ただし、次のうち少なくとも 1 つが含まれている必要があります。<URIPath><QueryParam><Header><FormParam><JSONPayload><XMLPayload>.
型: なし

属性

属性 説明 デフォルト 要否
name 値を抽出する変数の名前。

なし

必須 文字列

<JSONPayload> 要素

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

    <JSONPayload>
       <Variable name="name" type="string">
          <JSONPath>{example}</JSONPath>
       </Variable>
    </JSONPayload>
    
デフォルト: なし
要否: 省略可。ただし、次のうち少なくとも 1 つが含まれている必要があります。<URIPath><QueryParam><Header><FormParam><JSONPayload><XMLPayload>.
型: なし

<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 パスを指定します。

    <Variable name="name">
       <JSONPath>$.rss.channel.title</JSONPath>
    </Variable>
    
デフォルト: なし
必須?: 必須
型: 文字列

<XMLPayload> 要素

(省略可。詳細は下記の表の「要否」行をご覧ください)変数の値を抽出する XML 形式のメッセージを指定します。XML ペイロードは、指定されたメッセージの Content-Type ヘッダーが text/xmlapplication/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>
    
デフォルト: なし
要否: 省略可。ただし、次のうち少なくとも 1 つが含まれている必要があります。<URIPath><QueryParam><Header><FormParam><JSONPayload><XMLPayload>.
型: なし

属性

属性 説明 デフォルト 要否
stopPayloadProcessing

true に設定した場合、変数が 1 つ代入された時点で XPath の評価を停止します。つまり、ポリシーによって代入される変数は 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>
    
デフォルト: なし
必須?: 省略可
型: String

属性

属性 説明 デフォルト 要否
prefix

名前空間の接頭辞。

なし

必須 文字列

<XMLPayload> / <Variable> 要素

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

    <Variable name="name" type="boolean">
       <XPath>/test/example</XPath>
    </Variable>
    
デフォルト: なし
必須?: 省略可
型: なし

属性

属性 説明 デフォルト 要否
name

抽出された値を割り当てる変数の名前を指定します。

name

必須 文字列
type 変数値のデータ型を指定します。 boolean 省略可

文字列。次から選択:

  • string
  • boolean
  • integer
  • long
  • float
  • double
  • nodeset(XML フラグメントを返します)

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

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

    <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>
    
デフォルト: なし
必須?: 必須
型: 文字列

エラー リファレンス

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

ランタイム エラー

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

障害コード HTTP ステータス 原因 修正
steps.extractvariables.ExecutionFailed 500

このエラーは、次の場合に発生します。

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

デプロイエラー

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

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

障害変数

以下の変数は、このポリシーにより実行時にエラーが発生したときに設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

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

エラー レスポンスの例

    {
       "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>
    

スキーマ

関連トピック

カスタム分析を使用して API メッセージ コンテンツを分析する

変数リファレンス