ポリシー作成機能の使用

<AssignMessage name="GenerateGeocodingRequest">
  <AssignTo createNew="true" type="request">GeocodingRequest</AssignTo>
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
      <QueryParam name="region">{request.queryparam.country}</QueryParam>
      <QueryParam name="sensor">false</QueryParam>
    </QueryParams>
    <Verb>GET</Verb>
  </Set>
  <!-- Set variables for use in the final response -->
  <AssignVariable>
    <Name>PostalCode</Name>
    <Ref>request.queryparam.postalcode</Ref>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
  </AssignVariable>
</AssignMessage>

このポリシーの要素について以下に簡単に説明します。このポリシーの詳細については、Message ポリシーの割り当てをご覧ください。

• <AssignMessage name> - このポリシーに名前を付けます。この名前は、ポリシーをフローで参照するときに使用されます。
• <AssignTo> - GeocodingRequest という名前の変数を作成します。この変数は、ServiceCallout ポリシーによってバックエンドに送信されるリクエスト オブジェクトをカプセル化します。
• <QueryParams> - バックエンド API 呼び出しに必要なクエリ パラメータを設定します。この場合、Geocoding API は、郵便番号と国 ID で表される場所を把握する必要があります。アプリのユーザーがこの情報を指定します。ここではその情報を抽出します。この API で sensor は必須で、値は true または false です。ここでは、false にハードコードします。
• <Verb> - この場合、API に対して単純な GET リクエストを行います。
• <AssignVariable> - これらの変数は、API に渡される値を格納します。この例では、クライアントに返されたレスポンスでこれらの変数にアクセスします。

ServiceCallout でリクエストを送信する

ポリシー作成機能の次のステップでは、ServiceCallout ポリシーを作成します。次に示す ServiceCallout ポリシーは、前の AssignMessage ポリシーで作成したリクエスト オブジェクトを Google Geocoding サービスに送信し、GeocodingResponse という変数に結果を保存します。

<ServiceCallout name="ExecuteGeocodingRequest">
  <Request variable="GeocodingRequest"/>
  <Response>GeocodingResponse</Response>
  <HTTPTargetConnection>
    <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
  </HTTPTargetConnection>
</ServiceCallout>

このポリシーの要素について以下に簡単に説明します。

• <ServiceCallout> - 前のポリシーと同様に、このポリシーにも名前があります。
• <Request variable> - AssignMessage ポリシーで作成された変数です。これは、バックエンド API に送信されるリクエストをカプセル化します。
• <Response> - この要素では、レスポンスを格納する変数の名前を指定します。この変数には、ExtractVariables ポリシーで後ほどアクセスします。
• <HTTPTargetConnection> - バックエンド API のターゲット URL を指定します。この場合、API が JSON レスポンスを返すように指定します。

これで、2 つのポリシーが作成されました。1 つは、バックエンド API（Google の Geocoding API）を使用するために必要なリクエスト情報を指定するものです。2 つ目は、実際にリクエストをバックエンド API に送信するものです。次は、レスポンスを処理します。

<ExtractVariables name="ParseGeocodingResponse">
  <Source>GeocodingResponse</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
       <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
       <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

ExtractVariable ポリシーの主な要素は次のとおりです。

• <ExtractVariables name> - この場合も、ポリシーをフローで使用するときにポリシーを参照するために使用されます。
• <Source> - ServiceCallout ポリシーで作成したレスポンス変数を指定します。このポリシーは、この変数からデータを抽出します。
• <VariablePrefix> - 変数接頭辞では、このポリシーで作成される他の変数の名前空間を指定します。この接頭辞には、Edge の事前定義変数で定義されている予約済みの名前を除き、任意の名前を使用できます。
• <JSONPayload> - この要素は、目的のレスポンス データを取得し、名前付き変数に格納します。実際には、Geocoding API は、緯度と経度以外にもさまざまな情報を返します。ただし、このサンプルで必要な値は緯度と経度のみです。Geocoding API から返される JSON の完全なレンダリングについては、API のドキュメントをご覧ください。geometry.location.lat と geometry.location.lng の値は、返される JSON オブジェクト内の多数の項目のうちの 2 つにすぎません。

明らかでない場合もありますが、このポリシーで指定した変数接頭辞（geocoderesponse）と実際の変数名で名前が構成される 2 つの変数が ExtractVariables によって生成されることを確認することが重要です。これらの変数は API プロキシに格納され、プロキシフロー内の他のポリシーで使用できるようになります。これらの変数は次のとおりです。

• geocoderesponse.latitude
• geocoderesponse.longitude

以上で、ほとんどの作業が終わりました。リクエストの作成、バックエンド API の呼び出し、返された JSON データの解析を行う 3 つのポリシーの複合体を作成しました。最後のステップでは、フローのこの部分から別の AssignMessage ポリシーにデータを渡し、2 つ目のバックエンド API（Google Elevation API）を呼び出して、マッシュアップされたデータをアプリ デベロッパーに返します。

<AssignMessage name="AssignElevationParameters">
<Remove>
    <QueryParams>
      <QueryParam name="country"/>
      <QueryParam name="postalcode"/>
    </QueryParams>
  </Remove>
  <Set>
    <QueryParams>
      <QueryParam name="locations">{geocoderesponse.latitude},{geocoderesponse.longitude}</QueryParam>
      <QueryParam name="sensor">false</QueryParam>
    </QueryParams>
  </Set>
</AssignMessage>

Google Elevation API を調べると、2 つのクエリ パラメータを受け取ることがわかります。1 つ目のパラメータは locations で、その値は緯度と経度（カンマ区切り値）です。もう一方のパラメータは sensor です。このパラメータは必須で、値は true または false である必要があります。この時点で最も重要なのは、ここで作成するリクエスト メッセージには ServiceCallout が必要でないということです。プロキシの TargetEndpoint からバックエンド API を呼び出すことができるため、この時点で ServiceCallout から 2 つ目の API を呼び出す必要はありません。Google Elevations API を呼び出すために必要なデータはすべてそろっています。このステップで生成されるリクエスト メッセージは、メインのリクエスト パイプラインについて生成されるリクエストとは異なり ServiceCallout を必要としないため、ProxyEndpoint によって TargetEndpoint に転送された後、この API プロキシについて構成された RouteRule に転送されます。TargetEndpoint は、リモート API との接続を管理します。Elevation API の URL は、TargetEndpoint の HTTPConnection で定義します。詳細については、Elevation API のドキュメントをご覧ください。前に保存した QueryParams（country と postalcode）は不要になったため、ここでは削除します。

次に進む前に: フローの再確認

ここで、別の ServiceCallout ポリシーを作成しない理由を考えてみましょう。最終的には、別のメッセージを作成しました。そのメッセージは、ターゲットである Google Elevation API にどのようにして送信されるのでしょうか。これは、フローの <RouteRule> 要素で送信されます。<RouteRule> では、フローの <Request> 部分が実行された後の残りのリクエスト メッセージの処理方法を指定します。この <RouteRule> で指定した TargetEndpoint によって、API プロキシはメッセージを http://maps.googleapis.com/maps/api/elevation/xml に送信するよう指示されます。

ダウンロードしたサンプル API プロキシの場合、TargetProxy XML は doc-samples/policy-mashup-cookbook/apiproxy/targets/default.xml ファイルにあります。

<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <!-- This is where we define the target. For this sample we just use a simple URL. -->
    <URL>http://maps.googleapis.com/maps/api/elevation/xml</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

次は、Google Elevation API からのレスポンスを処理する必要があります。それが終われば完了です。

$ curl "http://{myorg}-test.apigee.net/policy-mashup-cookbook?country=us&postalcode=08008"

レスポンスには、アプリのエンドユーザーによって指定された郵便番号地域の中心のジオコード化された場所とそのジオコード化された場所の標高との組み合わせが含まれます。このデータは 2 つのバックエンド API から取得され、API プロキシに添付されたポリシーによってマッシュアップされて、1 つのレスポンスでクライアントに返されたものです。

{
   "country":"us",
   "postalcode":"08008",
   "elevation":{
      "meters":0.5045232,
      "feet":1.6552599030345978
   },
   "location":{
      "latitude":39.75007129999999,
      "longitude":-74.1357407
   }
}

まとめ

このクックブックのトピックでは、ポリシー作成機能パターンを使用して、複数のバックエンド ソースからのデータのマッシュアップを作成する方法を説明しました。ポリシー作成機能は、API にクリエイティブな機能を追加するために API プロキシの開発で使用される一般的なパターンです。