API Gateway:エラーコードマッピングプラグイン

1. 概要

このプラグインを使用して、バックエンドのエラーレスポンスをクライアントが期待する形式に変換します。

2. はじめに

次の例では、バックエンドは HTTP 200 レスポンスを返しますが、レスポンスボディの JSON フィールドにエラーメッセージが含まれています。

HTTP 200 OK
Content-Type:application/json

{"req_msg_id":"d02afa56394f4588832bed46614e1772","result_code":"ROLE_NOT_EXISTS"}

• このシナリオでは、クライアントは 200 以外のレスポンスを期待しているため、バックエンドを変更せずにこのレスポンスを返す必要があります。

HTTP 404 
X-Ca-Error-Message: Role Not Exists, ResultId=d02afa56394f4588832bed46614e1772

これに対応するには、エラーコードマッピングプラグインを次のように設定します。

---
# マッピングに関連するフィールド
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"
# マッピング条件
errorCondition: "$statusCode = 200 and $resultCode <> 'OK'"
# エラーコードフィールド
errorCode: "resultCode"
# マッピング項目
mappings:
  - code: "ROLE_NOT_EXISTS"
    statusCode: 404
    errorMessage: "Role Not Exists, RequestId=${resultId}"
  - code: "INVALID_PARAMETER"
    statusCode: 400
    errorMessage: "Invalid Parameter, RequestId=${resultId}"
# デフォルトマッピング (オプション)
defaultMapping:
  statusCode: 500
  errorMessage: "Unknown Error, ${resultCode}, RequestId=${resultId}"

この例では、マッピング条件はバックエンドのレスポンスコードと JSON レスポンスボディの result_code フィールドに基づいています。バックエンドのレスポンスコードが 200 で、かつ result_code フィールドが 'OK' でない場合に、エラーコードマッピングがトリガーされます。result_code フィールドの値がマッピングのエラーコードとして使用されます。2 つのエラーコードが設定されています。ROLE_NOT_EXISTS はクライアントに 404 レスポンスを返し、INVALID_PARAMETER は 400 レスポンスを返します。それ以外のすべてのエラーコードは 500 レスポンスを返します。

3. プラグイン設定とマッピングルール

3.1. プラグイン設定

エラーコードマッピングプラグインは json または yaml 形式で設定します。設定フィールドは次のとおりです。

• parameters (必須)：マッピングに使用されるパラメーターです。これらのパラメーターはマップとして設定されます。詳細については、「パラメーターと条件式の使用」をご参照ください。

• errorCondition (必須)：レスポンスがエラーであるかどうかを判断する条件式です。式が true と評価された場合、マッピングが実行されます。

• errorCode (オプション)：エラーコードを提供するパラメーターを指定します。このパラメーターの値は、mappings リスト内の code フィールドとの照合に使用されます。

• mappings (必須)：マッピングレコードのリストです。ゲートウェイは、エラーコードまたはエラー条件に一致するレコードに基づいてレスポンスを再構築します。フィールドは次のとおりです。

  • code (オプション)：一意の識別子です。このパラメーターを設定する場合、errorCode パラメーターは必須です。errorCode パラメーターの値がこの code パラメーターの値と一致する場合、現在のマッピングレコードが実行されます。

  • condition (オプション)：エラー条件式です。式が true と評価された場合、現在のマッピングレコードが実行されます。

  • statusCode (必須)：現在のマッピングレコードの HTTP ステータスコードです。

  • errorMessage (オプション)：現在のマッピングレコードのエラーメッセージです。このメッセージは X-Ca-Error-Message レスポンスヘッダーとログの errorMessage フィールドに表示されます。

  • responseHeaders (オプション)：現在のマッピングレコードのレスポンスヘッダーです。マップとして設定します。

  • responseBody (オプション)：現在のマッピングレコードで、元のレスポンスボディを上書きするレスポンスボディです。

• defaultMapping (オプション)：デフォルトのマッピングレコードです。mappings 内に一致するレコードがない場合、このレコードがレスポンスとして使用されます。

  • statusCode (必須)：現在のマッピングレコードの HTTP ステータスコードです。

  • errorMessage (オプション)：現在のマッピングレコードのエラーメッセージです。このメッセージは X-Ca-Error-Message レスポンスヘッダーとログの errorMessage フィールドに表示されます。

  • responseHeaders (オプション)：現在のマッピングレコードのレスポンスヘッダーです。マップとして設定します。

  • responseBody (オプション)：現在のマッピングレコードで、元のレスポンスボディを上書きするレスポンスボディです。

設定ルール：

• mappingCondition と mappings[].condition の条件式で使用されるパラメーターは、parameters フィールドで定義する必要があります。定義されていない場合、エラーが発生します。パラメーターの定義と条件式の詳細については、「パラメーターと条件式の使用」をご参照ください。

• errorCode フィールドで使用されるパラメーターは、parameters で定義する必要があります。

• mappings リストの各レコードには、code または condition のいずれかを設定する必要があります。code を設定する場合、その値はリスト内で一意である必要があります。condition を設定する場合、レコードはリストの順序で評価されます。最初に一致したレコードが実行されます。

• errorMessage と responseBody では、"${Code}: ${Message}" のようなテンプレート形式を使用して変数を置換できます。パラメーターの値は、parameters の設定によって抽出された値が使用されます。

• responseHeaders の値も、テンプレート置換のために ${Message} 形式を使用できます。

• responseBody が設定されていない場合、バックエンドのレスポンスボディはパススルーされます。

• responseHeaders が設定されていない場合、バックエンドのレスポンスヘッダーはパススルーされます。設定されている場合、設定したキーと値のペアがバックエンドのレスポンスヘッダーを上書きします。値が '' に設定されている場合、対応するヘッダーは削除されます。

• defaultMapping が設定されていない場合、バックエンドのレスポンスはエラーコードマッピングなしでパススルーされます。

3.2. マッピングパラメーター

マッピングパラメーターは、parameters フィールドにキーと値のペアとして設定します。キーは変数名で、値は Location:Name 形式を使用して、レスポンスまたはシステムコンテキストの特定の場所から値を取得します。

---
# マッピングに関連するフィールド
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"

エラーコードマッピングでは、次の場所が利用できます。詳細については、「パラメーターと条件式の使用」をご参照ください。

• ErrorCode と ErrorMessage を使用すると、API Gateway のシステムエラーコードとメッセージを取得できます。詳細については、「エラーコード表」をご参照ください。

• BodyJsonField を使用すると、JSONPath を使用してバックエンドの JSON レスポンスから値を抽出できます。ただし、バックエンドのレスポンスボディが 15,360 バイト を超えると、このパラメーターでは値を抽出できず、null が返されます。

3.3. 実行ルール

エラーコードマッピングプラグインは、次の順序で実行されます。

1. プラグインは、parameters に設定されたパラメーターリストに基づいて、レスポンスとシステムコンテキストから現在のパラメーター値を取得します。

2. プラグインは、ステップ 1 のパラメーター値を使用して、errorCondition に設定された条件式を実行します。式が true と評価された場合、処理は続行されます。false と評価された場合、プラグインは停止し、マッピングは実行されません。

3. errorCode パラメーターが設定されている場合、プラグインはその値を取得し、mappings 内で code の値が一致するマッピングレコードを検索します。

4. ステップ 3 で一致するレコードが見つからない場合、プラグインは mappings 内の各マッピングレコードの condition を、一致が見つかるまで順次評価します。

5. ステップ 3 または 4 でマッピングレコードが一致した場合、ゲートウェイはそのレコードの設定に基づいて新しいレスポンスを構築します。それ以外の場合、defaultMapping が設定されていればその設定に基づいてレスポンスを構築し、設定されていなければ元のレスポンスをパススルーします。

3.4. システムエラーのマッピングとログ

• API Gateway のシステムエラーは、ゲートウェイのチェック、検証、スロットリング、プラグイン処理中に発生する可能性があります。ErrorCode パラメーターを使用して、これらのシステムエラーコードをマッピングできます。たとえば、スロットリングによって発生した 429 レスポンスを、200 レスポンスしかサポートしていないクライアント向けに 200 レスポンスへマッピングできます。システムエラーコードのリストについては、「エラーコード表」をご参照ください。

• システムエラーが発生した場合、StatusCode、Header、BodyJsonField など、レスポンスから取得されるパラメーターの値は null になります。条件式を作成する際にはこの点に留意してください。システムエラーが発生しない場合、ErrorCode の場所から取得される値は OK です。

• API Gateway のシステムエラーコードは、X-Ca-Error-Code レスポンスヘッダーに表示され、ログの errorCode フィールドに記録されます。エラーコードマッピングプラグインは、この値を上書きしません。

• ログの statusCode フィールドには、ゲートウェイがクライアントに返すレスポンスコードが記録されます。エラーコードマッピングプラグインは、この値を上書きできます。

4. 設定例

4.1. ボディエラーコードのマッピング

マッピング

---
# マッピングに関連するフィールド
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"
# マッピング条件
errorCondition: "$statusCode = 200 and $resultCode <> 'OK'"
# エラーコードフィールド
errorCode: "resultCode"
# マッピング項目
mappings:
  - code: "ROLE_NOT_EXISTS"
    statusCode: 404
    errorMessage: "Role Not Exists, RequestId=${resultId}"
  - code: "INVALID_PARAMETER"
    statusCode: 400
    errorMessage: "Invalid Parameter, RequestId=${resultId}"
# デフォルトマッピング (オプション)
defaultMapping:
  statusCode: 500
  errorMessage: "Unknown Error, ${resultCode}, RequestId=${resultId}"

4.2. レスポンスボディのマッピング

#
# この例では、カスタム JSON エラーボディをフロントエンドに返します。
---
# マッピングパラメーターの指定
parameters:
  statusCode: "StatusCode"
  resultCode: "Header:X-Ca-Error-Code"
  requestId: "Header:X-Ca-Request-Id"
  errorMessage: "Header:X-Ca-Error-Message"

# マッピング条件
errorCondition: "$statusCode != 200"
# エラーコードフィールド
errorCode: "resultCode"
# マッピング項目
mappings:
  - code: "I400MH"
    statusCode: 200
    responseHeaders:
        Content-Type: "application/json"
        X-Ca-Error-Message: ""
        X-Ca-Error-Code: ""
    responseBody: |
        {
            "code":"89",
            "message":"${errorMessage}",
            "resultCode":"${resultCode}"
            
        }

5. 制限

• 最大 16 個のパラメーターを定義できます。

• 各式の最大文字数は 512 文字です。

• BodyJsonField を使用する場合、レスポンスボディは 15,360 バイト に制限されます。ボディがこのサイズを超えると、null 値が返されます。

• プラグイン設定のサイズは 50 KB に制限されます。

• mappings で condition を使用する場合、最大 20 個のマッピングレコードを設定できます。