Transformer - API Gateway - Alibaba Cloud ドキュメントセンター

リクエスト/レスポンス書き換えプラグインは、HTTP リクエストがバックエンドに到達する前、および HTTP レスポンスがクライアントに到達する前に、それらを変更します。このプラグインを使用して、リクエストパラメーター (Header、Query、Form) とレスポンスヘッダーの追加、上書き、削除や、レスポンスステータスコードのオーバーライドができます。

サポートされる操作

このプラグインは、リクエストのライフサイクルにおける 2 つのポイントでトラフィックをインターセプトします。インバウンドパスではパラメーターマッピング後、アウトバウンドパスではエラーコードマッピング後です。各ポイントで、設定した変換ルールを適用します。

HTTP リクエストに対しては、以下の操作がサポートされています。

addRequestParameterIfAbsent: 指定された場所 (Header、Query、Form) に、指定の名前と値でパラメーターを追加します。パラメーターが既に存在する場合は、変更されません。
putRequestParameter: 指定された場所に、指定の名前と値でパラメーターを追加します。パラメーターが既に存在する場合は、その値が上書きされます。
removeRequestParameter: 場所とパラメーター名を指定して、パラメーターを削除します。

HTTP レスポンスに対しては、以下の操作がサポートされています。

setResponseStatusCode: バックエンドサービスから返されるステータスコードをオーバーライドします。
addResponseHeaderIfAbsent: 指定の名前と値でレスポンスヘッダーを追加します。ヘッダーが既に存在する場合は、変更されません。
putResponseHeader: 指定の名前と値でレスポンスヘッダーを追加します。ヘッダーが既に存在する場合は、その値が上書きされます。
removeResponseHeader: 名前を指定してレスポンスヘッダーを削除します。

説明

リクエスト操作は、Header、Query、Form の 3 つの場所をサポートしています。レスポンス操作は Header のみをサポートしています。

重要

リクエスト変換は、パラメーターマッピング後、リクエストがバックエンドに転送される前に実行されます。レスポンス変換は、エラーコードマッピング後、レスポンスがクライアントに返される前に実行されます。

設定例

プラグインは、YAML または JSON で設定します。どちらも同じスキーマを使用します。YAML と JSON の変換ツールを使用して、形式を切り替えることができます。以下の YAML テンプレートは、サポートされているすべての操作を網羅しています。

---
addRequestParameterIfAbsent:         # リクエストに追加します。パラメーターが既に存在する場合はスキップします。
  - name: userId
    value: 123456
    location: query
putRequestParameter:                 # リクエストに追加します。パラメーターが既に存在する場合は上書きします。
  - name: name
    value: Jack
    location: header
removeRequestParameter:              # リクエストから削除します。
  - name: address
    location: form
setResponseStatusCode: 200           # レスポンスステータスコードをオーバーライドします。
addResponseHeaderIfAbsent:           # レスポンスヘッダーに追加します。ヘッダーが既に存在する場合はスキップします。
  - name: age
    value: 18
putResponseHeader:                   # レスポンスヘッダーに追加します。ヘッダーが既に存在する場合は上書きします。
  - name: name
    value: Alice
removeResponseHeader:                # レスポンスヘッダーから削除します。
  - name: phone

addRequestParameterIfAbsent / addResponseHeaderIfAbsent と putRequestParameter / putResponseHeader の主な違いは、パラメーターが既に存在する場合の動作です。

addRequestParameterIfAbsent: API Gateway は、リクエストを転送する前に、クエリ文字列に userId が存在するかどうかを確認します。存在しない場合、API Gateway は値 123456 を挿入します。既に存在する場合、API Gateway は何も変更しません。これは、クライアントが既に送信した値を上書きせずに、デフォルト値を設定する場合に便利です。
putResponseHeader: API Gateway は、ヘッダーが既に存在するかどうかに関係なく、name レスポンスヘッダーを Alice に設定します。ヘッダーが存在する場合、その値は上書きされます。これは、すべてのレスポンスに特定のヘッダー値を強制する場合に便利です。

制限事項

リクエスト/レスポンス書き換えプラグインは、Dedicated Instances でのみ利用可能です。

2024 年 4 月 2 日より前に購入された Dedicated Instances の場合、設定の適用に失敗した際は、チケットを送信してインスタンスのバージョンをアップグレードしてください。