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

このページの内容は 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 ポリシー: これらのポリシーを使用すると、スクリプトを記述して、リクエストとレスポンスのデータを含むフロー変数にアクセスできます。