リクエスト変数とレスポンス変数

このページの内容は Apigee と Apigee ハイブリッドに該当します。

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

API プロキシに対してリクエストを行うときには、API プロキシの構成方法に応じて、次のいずれかまたはすべての情報を渡すことができます。

  • リクエスト ヘッダー
  • クエリ パラメータ
  • フォームデータ
  • XML ペイロードまたは JSON ペイロード
  • リソース URI

デフォルトでは、リクエストのすべてのデータが、変更されることなく ProxyEndpoint から TargetEndpoint に渡されます。したがって、TargetEndpoint がバックエンド サーバーにリクエストを送信すると、元のリクエストのすべての情報がバックエンド サービスに渡されます。

バックエンド サービスから Apigee が受信したレスポンスについても同様です。デフォルトでは、レスポンスで受信したすべてのデータが、変更されることなくリクエストの送信元のアプリに渡されます。

リクエスト データをバックエンド サーバーに渡す方法

次の図は、API プロキシの定義を示しています。

HTTP クライアントからプロキシ エンドポイントを経由してバックエンドの TargetEndpoint まで送信され、HTTP サービスに到達するリクエスト。プロキシ エンドポイントとターゲット エンドポイントの例を示しています。

この図の API プロキシ:

  • API プロキシ仮想ホスト: default
  • 環境グループのホスト名によって定義されたドメイン: http://www.example.com
  • プロキシ ベースパス: /v1/weather
  • ルートルールで指定された TargetEndpoint: default
  • ターゲット URL: http://weather.yahooapis.com

クライアント アプリは、次の curl コマンドを使用して、API プロキシに GET リクエストを送信します。

curl -X GET http://www.example.com/v1/weather/forecastrss?w=12797282

このリクエストには、リソース forecastrss と 1 つのクエリ パラメータ w が含まれています。次に示すとおり、Apigee はこのリクエストを解析し、フロー変数にリクエストの一部を割り当てます。

{request.verb} {proxy.basepath}/{proxy.pathsuffix}?{request.querystring}

フロー変数には次の値が設定されています。

  • request.verb: GET
  • proxy.basepath: /v1/weather
  • proxy.pathsuffix: forecastrss
  • request.querystring: w=12797282

TargetEndpoint は、リクエストの情報を使用してバックエンド サービスにリクエストを送信します。

{request.verb} {target.basepath}/{proxy.pathsuffix}?{request.querystring}

リクエストで指定されているリソースとクエリ パラメータが、バックエンド サーバーへのリクエストに自動的に含まれていることに注目してください。TargetEndpoint の定義により、このリクエストのフォームは以下のようになります。

curl -X GET http://weather.yahooapis.com/forecastrss?w=12797282

クエリ パラメータと同様に、API プロキシへのリクエストに含まれるすべてのヘッダーとフォーム パラメータがバックエンド サーバーに渡されます。たとえば、ヘッダーを含む以下のリクエストを行ったとします。

curl -X GET -H 'Content-type:application/xml' http://www.example.com/v1/weather/forecastrss?w=12797282

またはヘッダーとフォームデータを含む以下のフォームでリクエストを行ったとします。

curl -X POST -H "Content-type:application/json" -d \
  '{"email" : "janetutorialxml@example.com",
    "firstName" : "Jane",
    "lastName" : "Tutorial",
    "userName" : "jtutorialxml"
  }' \
  http://www.example.com/v1/register/user

どちらの例でも、ヘッダーとフォームデータが、変更されることなくバックエンド サービスに渡されます。ヘッダーは、request.headers.count や request.headers.names などのフロー変数で表されます。フォームデータは、request.formparam.count や request.formparam.names などのフロー変数で表されます。

レスポンス データが返される仕組み

デフォルトでは、Apigee がバックエンド サービスからのレスポンスで受信したすべてのデータは、変更されることなくリクエストの送信元のアプリに渡されます。リクエストに関して前述したように、レスポンスで返されるデータには、Apigee のフロー変数を使用してアクセスできます。詳細については、フロー変数のリファレンスをご覧ください。

API プロキシのリクエスト データとレスポンス データへのアクセス

バックエンド サーバーにリクエストを送信する前にリクエスト データを変更する必要が生じることがよくあります。次に例を示します。

  • Apigee でリクエストの検証に使用されるセキュリティ情報を削除する。この情報は、バックエンド サービスには必要ありません。
  • ユーザーの追跡や分析情報の収集などの目的で、バックエンド サービスに送信されるデータを追加する。
  • リクエスト データに基づいて条件に応じてリクエストを処理する。たとえば、API プロキシに複数の TargetEndpoints がある場合があります。リクエストが使用する TargetEndpoint はリクエスト データにより決定します。次に、バックエンド サービスに送信する前に、リクエストからそのデータを削除します。

同じことがレスポンスのデータにも該当します。レスポンス処理の一環として、API プロキシがリクエスト送信元のアプリにデータを返す前に、データを変更することが必要な場合があります。

リクエスト メッセージにアクセスする

リクエスト メッセージの各部分にアクセスして変更するには、ポリシーを使用します。これらの部分には、以下のものがあります。

  • ヘッダー
  • クエリ パラメータ
  • フォーム パラメータ
  • 送信元 IP アドレス
  • HTTP メッセージ本文

通常のフローでは、リクエストが処理されると、プロキシが変換されたリクエストをターゲットに送信します。

ポリシーによってリクエスト変数を検査し、変数の内容に基づいてリクエストを変換または拒否できます。ポリシーは、適切な変数（リクエスト ヘッダーに対応する変数など）を設定することでリクエストを変換します。

レスポンス メッセージにアクセスする

ポリシーはレスポンス メッセージに適用される変数を使用して、ヘッダー、クエリ パラメータ、フォーム パラメータ、送信元 IP アドレス、HTTP メッセージ本文などのメッセージ コンポーネントにアクセスできます。

プロキシはレスポンス メッセージを受信し、レスポンスで評価された条件に基づいてレスポンス メッセージに一連のポリシーを適用して、ポリシーによってそのレスポンスを変更または変換できます。

ポリシーによってレスポンス変数を検査し、それらの変数の内容に基づいてリクエストを変換または拒否できます。ポリシーは、適切な変数（レスポンス ヘッダーに対応する変数など）を設定することでレスポンスを変換します。

フロー変数にアクセスするための一般的なポリシー

Apigee は、リクエスト データとレスポンス データの処理に使用できるいくつかのポリシーを定義します。これには次のようなポリシーが含まれます。

  • AssignMessage ポリシー: API プロキシフロー中に HTTP リクエスト メッセージまたは HTTP レスポンス メッセージを作成または変更しますまた、新しいフロー変数を作成して値を入力します。
  • ExtractVariables ポリシー: 条件文で使用するために、ヘッダー、URI パス、ペイロード、クエリ パラメータなどのコンテンツをメッセージから抽出します。このポリシーでは次に、メッセージ コンテンツにテキスト パターンを適用し、一致するものが見つかると、指定された変数を設定します。
  • JSONtoXML ポリシーとXMLtoJSON ポリシー: メッセージを JavaScript Object Notation（JSON）形式から XML（拡張マークアップ言語）形式に（またはこの逆方向に）変換します。
  • JavaCallout ポリシー、JavaScript ポリシー、PythonScript ポリシー、RegularExpressionProtection ポリシー: これらのポリシーを使用すると、リクエストとレスポンスのデータを含むフロー変数にアクセスするためのスクリプトを作成できます。