03 リクエスト・レスポンス変換設定ガイド

[更新日：2025年2月18日]

概要 

このドキュメントでは、通過するリクエストやレスポンスの内容を動的に変更する API Gateway の作成方法について説明します。
サービス、ルートを作成し、そのルートに対してリクエストやレスポンスの変換の設定を行います。

サービス作成 

サイドバーからサービス一覧を選択し、サービス作成ボタンを押下します。

バックエンドサービスの情報を入力し、作成ボタンを選択するとサービスを作成することができます。

設定値

項目	設定値
名前（必須）	任意のサービス名
タグ	任意の値
プロトコル（必須）	http or https
ホスト（必須）	バックエンドサービスのホスト
パス	バックエンドサービスのパス（未入力の場合、「/」に設定される）
ポート	バックエンドサービスのポート番号（未入力の場合、設定したプロトコルに対応するポート番号が設定される）
認証設定	なし

作成に成功すると、以下のように一覧画面に表示されます。
サービス名をクリックもしくは行をダブルクリックすることで、サービス詳細画面に遷移します。

サービス詳細画面に遷移すると、登録したサービスの情報を確認することができます。

ルートの作成 

サイドバーからルート一覧を選択し、ルート作成ボタンを押下します。

必要な項目を入力し、作成ボタンを選択するとルートを作成することができます。

設定値

項目	設定値
名前（必須）	任意のルート名
タグ	任意の値
プロトコル（必須）	http or https or http/https
パス	任意のパス（未入力の場合、「/」が設定される）
HTTPメソッド	ルートへのアクセスメソッド（未入力の場合、全メソッドが許可される）

作成に成功すると、以下のように一覧画面に表示されます。
ルート名をクリックもしくは行をダブルクリックすることで、ルート詳細画面に遷移します。

ルート詳細画面に遷移すると、登録したルートの情報を確認することができます。

リクエスト変換の設定 

クライアントサイドからのリクエストを、バックエンドサービスに到達する前に変換する設定を行います。

サイドバーからリクエスト設定を選択し、リクエスト構成の画面で編集ボタンを押下します。必要な入力値を入力し、更新ボタンを押下することで、ルートにリクエスト変換の設定をすることができます。

設定値

同じキーが指定された場合、Allow > Remove > Rename > Replace > Add > Append の順で処理されます。

HTTPメソッド 

変換ロジックを適用するHTTPメソッドを指定します。

項目	設定値
HTTPメソッド	変換対象のメソッド

Allow 

許容する項目を指定します。未設定の場合は全ての項目が許容されます。

項目	設定値
Body	request bodyに許可するキーを設定する。ここで設定しなかったキーはリクエストからOmitされる。

例） bodyにa,bを指定した場合

{
  "a": "value1",
  "b": "value2",
  "c": "value3"
}

上記のリクエストは以下のように変換される。

{
  "a": "value1",
  "b": "value2"
}

Remove 

削除する項目を指定します。

項目	設定値
headerKeys	ヘッダーから削除するキーを設定する。
queryKeys	queryParameterから削除するキーを設定する。
bodyKeys	request bodyから削除するキーを設定する。

例） headerKeysにa,bを指定した場合

{
  "a": "value1",
  "b": "value2",
  "c": "value3"
}

上記のリクエストは以下のように変換される。

{
  "c": "value3"
}

Rename 

キー名を変更する項目を指定します。

項目	設定値
headers	headerにおいて、名称の置換を行うキーを設定する。
queryParams	queryParameterにおいて、名称の置換を行うキーを設定する。
body	request bodyにおいて、名称の置換を行うキーを設定する。

例） headersにa:x, b:yを指定した場合

{
  "a": "value1",
  "b": "value2",
  "c": "value3"
}

上記のリクエストは以下のように変換される。

{
  "x": "value1",
  "y": "value2",
  "c": "value3"
}

Replace 

置換する項目を指定します。

項目	設定値
headers	headerにおいて、値の置換を行うキーを設定する。
queryParams	queryParameterにおいて、値の置換を行うキーを設定する。
body	request bodyにおいて、値の置換を行うキーを設定する。

例） headersにa:x, b:yを指定した場合

{
  "a": "value1",
  "b": "value2",
  "c": "value3"
}

上記のリクエストは以下のように変換される。

{
  "a": "x",
  "b": "y",
  "c": "value3"
}

Add 

上書き追加する項目を指定します。

項目	設定値
headers	headerにおいて、追加するkey,valueを設定する。
queryParams	queryParameterにおいて、追加するkey,valueを設定する。
body	request bodyにおいて、追加するkey,valueを設定する。

例） headersにa:x, b:yを指定した場合

{
    "b": "value2",
    "c": "value3"
}

上記のリクエストは以下のように変換される。

{
  "a": "x",
  "b": "y",
  "c": "value3"
}

Append 

無ければ追加する項目を指定します。

項目	設定値
headers	headerにおいて、追加するkey,valueを設定する。
queryParams	queryParameterにおいて、追加するkey,valueを設定する。
body	request bodyにおいて、追加するkey,valueを設定する。

例） headersにa:x, b:yを指定した場合

{
    "b": "value2",
    "c": "value3"
}

上記のリクエストは以下のように変換される。

{
  "a": "x",
  "b": "value2",
  "c": "value3"
}

レスポンス変換の設定 

バックエンドサービスから返却されたレスポンスを変換する設定を行います。

サイドバーからレスポンス設定を選択します。レスポンス設定画面に遷移後、レスポンス構成の編集ボタンを押下します。
必要な入力値を入力し、更新ボタンを押下することで、ルートにレスポンス変換の設定をすることができます。

設定値

同じキーが指定された場合、Allow > Remove > Rename > Replace > Add > Append の順で処理されます。

Allow 

許容する項目を指定します。

項目	設定値
body	response bodyに許可するキーを設定する。ここで設定しなかったキーはレスポンスからOmitされる。

例） bodyにa,bを指定した場合

{
  "a": "value1",
  "b": "value2",
  "c": "value3"
}

上記のレスポンスは以下のように変換される。

{
  "a": "value1",
  "b": "value2"
}

Remove 

削除する項目を指定します。

項目	設定値
ifStatusCode	削除条件となるステータスコード。
headerKeys	レスポンスから削除するヘッダーを設定する。
jsonKeys	レスポンスのJSONから削除するフィールドを設定する。

例） headerKeysにa,bを指定した場合

{
  "a": "value1",
  "b": "value2",
  "c": "value3"
}

上記のレスポンスは以下のように変換される。

{
  "c": "value3"
}

Rename 

キー名を変更する項目を指定します。

項目	設定値
ifStatusCode	変更条件となるステータスコード。
headers	レスポンスの特定のヘッダーの名前を変更する。

例） headersにa:x, b:yを指定した場合

{
  "a": "value1",
  "b": "value2",
  "c": "value3"
}

上記のレスポンスは以下のように変換される。

{
  "x": "value1",
  "y": "value2",
  "c": "value3"
}

Replace 

置換する項目を指定します。

項目	設定値
ifStatusCode	置換条件となるステータスコード。
headers	レスポンスの特定のヘッダーの値を置換する。
json	レスポンスのJSONの特定のフィールドの値を置換する。
body	レスポンスのbodyを置換する。

例） headersにa:x, b:yを指定した場合

{
  "a": "value1",
  "b": "value2",
  "c": "value3"
}

上記のレスポンスは以下のように変換される。

{
  "a": "x",
  "b": "y",
  "c": "value3"
}

Add 

上書き追加する項目を指定します。

項目	設定値
ifStatusCode	追加条件となるステータスコード。
headers	レスポンスに新しいヘッダを追加する。
json	レスポンスのJSONの特定のフィールドに値を追加する。

例） headersにa:x, b:yを指定した場合

{
    "b": "value2",
    "c": "value3"
}

上記のレスポンスは以下のように変換される。

{
  "a": "x",
  "b": "y",
  "c": "value3"
}

Append 

無ければ追加する項目を指定します。

項目	設定値
ifStatusCode	追加条件となるステータスコード。
headers	レスポンスに新しいヘッダを追加する。
json	レスポンスのJSONの特定のフィールドに値を追加する。

例）headersにa:x, b:yを指定した場合

{
    "b": "value2",
    "c": "value3"
}

上記のレスポンスは以下のように変換される。

{
  "a": "x",
  "b": "value2",
  "c": "value3"
}

設定完了 

これでリクエスト・レスポンスの変換設定が完了しました。リクエスト変換を設定したルートにリクエストを送ると、API Gateway がリクエストを変換してバックエンドサービスにアクセスします。また、レスポンス変換を設定したルートにリクエストを送ると、API Gateway がバックエンドサービスからのレスポンスを変換し、クライアントに送信する前に加工します。