Proxy Rewrite plugin

Proxy Rewrite plugin（技術名 proxy-rewrite、Transformation グループ）は、API Gateway がバックエンドに転送する前に request の情報を書き換えます: Host ヘッダー、path（URI）、HTTP method、ヘッダーの追加・変更・削除。

注記

Proxy Rewrite はセキュリティ plugin ではなく、request をブロックすることはありません。認証や rate limiting などの他のステップを通過した有効な request を変換するだけです。

ユースケース

Proxy Rewrite plugin は、クライアントが API Gateway に送る URI、host、method、ヘッダーが、バックエンドで必要なものと異なる場合に適しています。

主なケース:

• API Gateway は path /v1/users を公開しているが、バックエンドは /internal/users しか受け付けない: uri または regex_uri で path を書き換えます。
• バックエンドが、クライアントが呼び出す公開ドメインとは異なる内部の Host ヘッダーを要求する: host を使います。
• レガシーのバックエンドが固定の method（例: POST）しか受け付けない: method を使って、すべての request をその method で送ります。
• 認証済みの Consumer 名をカスタムヘッダーでバックエンドに渡し、元の API キーを運ぶヘッダーを削除する: headers.set と headers.remove を組み合わせます。

Proxy Rewrite plugin を作成する

Proxy Rewrite plugin を作成するには、次の手順を実行します。

1. 左側のメニューで API Gateway → Plugin を選択し、右上で API Gateway を選択して New plugin をクリックし、Add plugin ポップアップで Proxy Rewrite を選択します。Route / Service の Plugins タブから追加することもできます。Plugin の追加を参照してください。

2. Basic Information セクションで Display Name を入力します。Basic Informationを参照してください。

3. Configuration セクションを選択します。フォームには 8 つの属性がすべて表示されますが、すべて空です。フィールド内の灰色のテキスト（iresty.com、/get、^/rewrite-regex/(.*)、/$1）は入力のヒントにすぎないため、最初の JSON は {} です。この plugin には必須属性も Quick Start Templates もなく、入力した属性ごとに JSON に表示されます。

属性	必須	説明
host	N	クライアントの元の Host ヘッダーの代わりにバックエンドに送る新しい Host ヘッダーです。有効なドメイン名である必要があります。
method	N	バックエンドに転送する前に request の HTTP method を変更します。元の method を維持するには Keep original（デフォルト）のままにします。
uri	N	バックエンドに送る新しい固定の path で、$arg_name などの NGINX 変数を使用できます。/ で始める必要があります。uri と regex_uri の両方を設定した場合は、uri が優先されます。
regex_uri	N	正規表現で path を書き換える [pattern, replacement] の組で、元の path から新しい path を導く場合に使います。pattern が一致すると、request は replacement で転送されます。一致しない場合は元の path が維持されます。$1、$2 などはキャプチャグループを参照します。+ Add をクリックすると組を追加します。入力する行数は偶数である必要があります。
use_real_request_uri_unsafe	N	クライアントの生の URI を使い、URI の正規化を省略します。安全ではないため、セキュリティ上のリスクを十分に理解している場合にのみオンにしてください。
headers.add	N	request にヘッダーを追加します。同じ名前の既存ヘッダーは上書きされずに残ります。
headers.set	N	ヘッダーの値を上書きするか、存在しない場合は追加します。Host を変更する場合は、ここで Host ヘッダーを設定するのではなく、host 属性を使ってください。
headers.remove	N	バックエンドに転送する前に request からヘッダーを削除します。ヘッダー名だけが必要です。

3 つのヘッダーグループをすべて設定した場合は、add → remove → set の順に処理されます。

注記

JSON では、regex_uri は [pattern, replacement] の組で項目が並ぶフラットな配列です。3 つのヘッダーグループは headers オブジェクトに入ります。add と set は {"header-name": "value"} のようなオブジェクト、remove はヘッダー名の配列です。

4. Scope セクションを選択し、Global または Scoped を選んで、Route / Service を割り当てます。Scopeを参照してください。

5. Create をクリックします。Plugin created successfully というメッセージが表示され、選択した範囲に対応する Applied to 列とともに plugin が一覧に表示されます。

設定例

以下の 4 つの設定は、ユースケースの 4 つのケースに対応しています。

Host ヘッダーだけを変更し、クライアントが呼び出した path は維持します。

{
  "host": "backend.internal"
}

バックエンドに届く前に path の prefix を取り除きます。クライアントが /v1/users/42 を呼び出すと、バックエンドは /users/42 を受け取ります。

{
  "regex_uri": [
    "^/v1/(.*)",
    "/$1"
  ]
}

path を固定の値に変更し、method を強制します（POST しか受け付けないレガシーのバックエンド）。uri と regex_uri の両方を設定すると uri が優先されるため、通常はどちらか一方だけを使います。

{
  "uri": "/internal/users",
  "method": "POST"
}

認証済みの Consumer 名をカスタムヘッダーでバックエンドに渡し、元の API キーを運ぶヘッダーを削除します。

{
  "headers": {
    "set": {
      "X-Consumer-Name": "$consumer_name",
      "X-Forwarded-Client-IP": "$remote_addr"
    },
    "remove": [
      "X-API-Key"
    ]
  }
}

注記

$ で始まる値は NGINX 変数で、request が API Gateway を通過するときに実際の値に置き換えられます。$consumer_name に値が入るのは、Route / Service で認証 plugin（JWT Auth など）が先に実行される場合だけです。そうでない場合、ヘッダーは空になります。

よくある問題

フォームは入力時に値をチェックし、エラーを表示します。

エラー	原因	対処方法
host にエラーが表示される	値が有効なドメイン名ではありません	有効なドメイン名を入力します（例: backend.internal）。
uri にエラーが表示される	値が / で始まっていません	先頭に / を付けます（例: /internal/users）。
regex_uri にエラーが表示される	入力した行数が奇数で、replacement のない pattern があります	各 pattern / replacement の組を入力します。
ヘッダー名にエラーが表示される	ヘッダー名に : が含まれています	ヘッダー名から : を削除します。

次のステップ

• Plugin の概要
• Plugin の詳細表示