API プロキシにリクエストを行うと、API プロキシの構成方法に応じて、次のいずれかまたはすべての情報を渡すことができます。
- リクエスト ヘッダー
- クエリ パラメータ
- フォームデータ
- XML ペイロードまたは JSON ペイロード
- リソース URI
デフォルトでは、リクエストのすべてのデータが、変更されることなく ProxyEndpoint から TargetEndpoint に渡されます。そのため、TargetEndpoint ではバックエンド サーバーにリクエストを行ったとき、元のリクエストのすべての情報がバックエンド サービスに渡されます。
Edge がバックエンド サービスから受信したレスポンスについても同じことが当てはまります。デフォルトでは、レスポンスで受信したすべてのデータが、変更されることなくリクエストの発信元のアプリに渡されます。
リクエスト データをバックエンド サーバーに渡す方法
以下の図に、API プロキシの定義を示します。
この API プロキシの構成は次のとおりです。
- API プロキシ仮想ホスト: "default"
- 仮想ホストで定義されたドメイン: "http://myOrg-prod.apigee.net"
- プロキシ ベースパス: "/v1/weather"
- ルートルールで指定された TargetEndpoint: "default"
- ターゲット URL: "http://weather.yahooapis.com"
クライアント アプリにより、次の curl コマンドを使用して、API プロキシへの GET リクエストが行われます。
curl -X GET http://myOrg-prod.apigee.net/v1/weather/forecastrss?w=12797282
このリクエストにはリソース「forecastrss」と 1 つのクエリ パラメータ「w」が含まれています。Edge では、以下のようにリクエストが解析され、フロー変数にリクエストの部分が割り当てられます。
{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://myOrg-prod.apigee.net/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://myOrg-prod.apigee.net/v1/register/user
どちらの例でも、ヘッダーとフォームデータが、変更されることなくバックエンド サービスに渡されます。ヘッダーは、request.headers.count や request.headers.names などのフロー変数で表されます。フォームデータは、request.formparam.count や request.formparam.names などのフロー変数で表されます。
レスポンス データが返される方法
デフォルトでは、レスポンスのバックエンド サービスから Edge が受信したすべてのデータは、変更されることなくリクエストの送信元のアプリに渡されます。リクエストに関して前述したように、レスポンスで返されるデータには、Edge のフロー変数を介してアクセスできます。詳細は、フロー変数のリファレンスをご覧ください。
API プロキシのリクエスト データとレスポンス データへのアクセス
バックエンド サーバーに送信する前にリクエスト データを変更したくなる場合がよくあります。例:
- リクエストを検証するために Edge が使用するセキュリティ情報を削除する（その情報がバックエンド サービスには不要）。
- ユーザーの追跡やアナリティクスの収集などの目的で、バックエンド サービスに送信されるデータを追加する。
- リクエスト データに基づいて条件に応じてリクエストを処理する。たとえば、API プロキシに複数の TargetEndpoints がある場合があります。リクエストが使用する TargetEndpoint はリクエスト データにより決定されます。次に、バックエンド サービスに送信する前に、リクエストからそのデータを削除します。
同じことがレスポンスのデータにも該当します。レスポンス処理の一環として、API プロキシが要求側のアプリにデータを返す前に、データを変更することが必要な場合があります。
リクエスト メッセージにアクセスする
ポリシーを使用して、リクエスト メッセージの各部分にアクセスして変更することができます。これらの部分には、以下のものがあります。
- ヘッダー
- クエリ パラメータ
- フォーム パラメータ
- 送信元 IP アドレス
- HTTP メッセージ本文
通常のフローでは、リクエストが処理されると、プロキシは変換されたリクエストをターゲットに送信します。
ポリシーによってリクエスト変数を検査し、それらの変数の内容に基づいてリクエストを変換または拒否できます。ポリシーは、リクエスト ヘッダーに対応する変数など、適切な変数を設定することによってリクエストを変換します。
レスポンス メッセージにアクセスする
ポリシーはレスポンス メッセージに適用される変数を使用して、ヘッダー、クエリ パラメータ、フォーム パラメータ、送信元 IP アドレス、HTTP メッセージ本文などのメッセージ コンポーネントにアクセスできます。
プロキシはレスポンス メッセージを受信し、レスポンスで評価された条件に基づいてレスポンス メッセージに一連のポリシーを適用して、ポリシーによってそのレスポンスを変更または変換できます。
ポリシーによってレスポンス変数を検査し、それらの変数の内容に基づいてリクエストを変換または拒否できます。ポリシーは、レスポンス ヘッダーに対応する変数など、適切な変数を設定することによってレスポンスを変換します。
フロー変数にアクセスするための一般的なポリシー
Edge では、リクエスト データとレスポンス データを処理するために使用できるポリシーが定義されています。これらのポリシーには、次のものがあります。
- AssignMessage ポリシー: API プロキシフローの際に HTTP リクエストまたはレスポンス メッセージを作成または変更します。また、新しいフロー変数を作成、設定します。
- ExtractVariables ポリシー: 条件文で使用するために、ヘッダー、URI パス、ペイロード、クエリ パラメータを含むコンテンツをメッセージから抽出します。このポリシーでは、メッセージ コンテンツにテキスト パターンを適用し、一致が検出されると、指定された変数を設定します。
- JSONtoXML ポリシーと XMLtoJSON ポリシー: JavaScript Object Notation（JSON）形式から拡張マークアップ言語（XML）形式に、またはその反対にメッセージを変換します。
- JavaCallout ポリシー、JavaScript ポリシー、PythonScript ポリシー、RegularExpressionProtection ポリシー: これらのポリシーを使用すると、リクエスト データとレスポンス データを含むフロー変数にアクセスするスクリプトを作成できます。