API Gateway:エラーマッピングタイプのプラグイン

1. 概要

エラーマッピングタイプのプラグインを使用して、クライアントの要求に応じて定義されたマッピングルールに基づいて、バックエンドエラー応答を新しいエラー応答にマッピングします。

2. クイックスタート

次の例は、API操作のバックエンドによって返されるエラーレスポンスを示しています。 HTTPステータスコードは200ですが、レスポンス本文にはJSON文字列のエラーメッセージが含まれています。

HTTP 200 OK
Content-Type:application/json

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

• クライアントが200以外のHTTPステータスコードを受信したいが、バックエンド設定を変更してこれを実現したくないと仮定します。 たとえば、クライアントには次のエラー応答が予想されます。

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

この場合、次のサンプルを使用してエラーマッピングタイプのプラグインを設定し、そのプラグインを関連するAPI操作にバインドできます。

---
# The parameters that are involved in mapping.
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"
# The mapping condition under which an error response needs to be mapped.
errorCondition: "$statusCode = 200 and $resultCode <> 'OK'"
# The parameter in an error response that is used to specify the error code and hit mapping rules.
errorCode: "resultCode"
# The mapping rules.
mappings:
  - code: "ROLE_NOT_EXISTS"
    statusCode: 404
    errorMessage: "Role Not Exists, RequestId=${resultId}"
  - code: "INVALID_PARAMETER"
    statusCode: 400
    errorMessage: "Invalid Parameter, RequestId=${resultId}"
# Optional. The default mapping rule.
defaultMapping:
  statusCode: 500
  errorMessage: "Unknown Error, ${resultCode}, RequestId=${resultId}"

この例では、HTTPステータスコードとエラー応答のresult_codeパラメーターを使用して、マッピング条件を定義します。 エラーレスポンスのHTTPステータスコードが200で、result_codeパラメーターの値がOKでない場合、マッピングが開始されます。 result_codeパラメーターは、マッピングルールを定義するために使用されます。 1つのルールは、result_codeパラメーターの値がROLE_NOT_EXISTSの場合、元のHTTPステータスコードが404にマップされることです。 もう1つのルールは、result_codeパラメーターの値がINVALID_PARAMETERの場合、元のHTTPステータスコードが400にマップされることです。 デフォルトのマッピング規則も定義される。 result_codeパラメーターの値が前の値のどちらでもない場合、元のHTTPステータスコードは500にマップされます。

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

3.1. プラグインの設定

エラーマッピングタイプのプラグインをJSON形式またはYAML形式で設定できます。 次のパラメータを指定できます。

• parameters: 必須です。 マッピングに含まれるパラメーター。 これらのパラメーターは、map形式のキーと値のペアとして指定されます。 パラメーターの定義方法と条件式の記述方法については、「パラメーターと条件式の使用」をご参照ください。

• errorCondition: 必須です。 エラー応答をマッピングする必要があるマッピング条件。 条件式の結果がtrueの場合、マッピングが開始されます。

• errorCode: オプション。 エラーコードとヒットマッピングルールを指定するために使用されるエラーレスポンスのパラメーター。 errorCodeパラメーターの値で指定されたエラーコードは、マッピングルールのcodeパラメーターの値と比較されます。

• mappings: 必須です。 マッピングルール。 API Gatewayは、これらのマッピングルールに基づいてエラー応答を再構築します。 マッピングルールには、次のパラメーターが含まれます。

  • code: 省略可能です。 errorCodeパラメーターの値で指定されたエラーコードが同じであるエラーレスポンスを識別するために使用される指定値。 このパラメーターの値は、すべてのマッピングルール間で一意である必要があります。 エラー応答のエラーコードが現在のマッピングルールのcodeパラメーターの値と同じである場合、エラー応答は現在のルールに基づいてマッピングされます。

  • condition: オプション。 現在のマッピングルールに基づいてエラー応答をマッピングする必要がある条件。 条件式の結果がtrueの場合、エラーレスポンスは現在のルールに基づいてマッピングされます。

  • statusCode: 必須です。 現在のマッピングルールに基づいてエラーレスポンスをマッピングする必要がある場合に、エラーレスポンスの元のHTTPステータスコードを置き換えるHTTPステータスコード。

  • errorMessage: オプション。 マッピング後にクライアントに返されるエラーメッセージ。 このパラメーターの値は、元のバックエンドエラー応答のパラメーターから取得され、エラーログのerrorMessageパラメーターにも保存されます。 マッピング後のエラー応答では、このパラメーターはX-Ca-error-Messageヘッダーフィールドの値として表示されます。

  • responseHeaders: オプション。 現在のマッピングルールがヒットした場合に、マッピング後にエラーレスポンスに含まれるレスポンスヘッダーフィールド。 このパラメーターは、map形式のキーと値のペアとして指定します。

  • responseBody: オプション。 現在のマッピングルールに基づいてエラーレスポンスをマッピングする必要がある場合に、エラーレスポンスの元のレスポンスボディを上書きするレスポンスボディ。

• defaultMapping: オプション。 デフォルトのマッピングルール。 エラー応答がmappingsパラメーターで定義されているルールにヒットしない場合、エラー応答は既定のマッピングルールに基づいてマッピングされます。

  • statusCode: 必須です。 エラーレスポンスをデフォルトのマッピングルールに基づいてマッピングする必要がある場合に、エラーレスポンスの元のHTTPステータスコードを置き換えるHTTPステータスコード。

  • errorMessage: オプション。 マッピング後にクライアントに返されるエラーメッセージ。 このパラメーターの値は、元のバックエンドエラー応答のパラメーターから取得され、エラーログのerrorMessageパラメーターにも保存されます。 マッピング後のエラー応答では、このパラメーターはX-Ca-error-Messageヘッダーフィールドの値として表示されます。

  • responseHeaders: オプション。 デフォルトのマッピングルールがヒットした場合に、マッピング後にエラーレスポンスに含まれるレスポンスヘッダーフィールド。 このパラメーターは、map形式のキーと値のペアとして指定します。

  • responseBody: オプション。 エラーレスポンスをデフォルトのマッピングルールに基づいてマッピングする必要がある場合に、エラーレスポンスの元のレスポンスボディを上書きするレスポンスボディ。

エラーマッピングタイプのプラグインを設定するときは、次の項目に注意してください。

• mappingConditionおよびmappings[].conditionで条件式を記述するために使用されるパラメーターは、parametersパラメーターで定義する必要があります。 それ以外の場合、プラグインは機能せず、エラーを報告します。 パラメーターの定義方法と条件式の記述方法については、「パラメーターと条件式の使用」をご参照ください。

• errorCodeパラメーターの値は、parametersパラメーターで定義されているパラメーターの名前である必要があります。

• マッピングルールを設定するときは、codeパラメーターとconditionパラメーターの少なくとも1つを指定する必要があります。 codeパラメーターを指定する場合、このパラメーターの値はすべてのマッピングルール間で一意である必要があります。 conditionパラメーターを指定する場合、条件式を要件を満たす順序で記述する必要があります。 これは、条件の順序が優先順位を決定するためです。

• errorMessageおよびresponseBodyパラメーターを "${Code}: ${Message}" 形式に置き換えることができます。 この形式のCodeおよびMessageパラメーターの値は、parametersパラメーターで定義されているパラメーターから取得する必要があります。

• responseHeadersパラメーターを ${Message} 形式に置き換えることもできます。

• responseBodyパラメーターを指定しない場合、マッピング後にクライアントに返されるエラーレスポンスのレスポンスボディは、元のエラーレスポンスのレスポンスボディと同じになります。

• responseHeadersパラメーターを使用して、バックエンドエラー応答の対応するヘッダーフィールドを置き換えるヘッダーフィールドとその値を指定できます。 ヘッダーフィールドの値を "として指定した場合、このヘッダーフィールドはマッピング後に削除されます。 このパラメーターを指定しない場合、マッピング後にクライアントに返されるエラー応答のヘッダーフィールドは、元のエラー応答のヘッダーフィールドと同じになります。

• defaultMappingパラメーターを指定せず、エラー応答がマッピングルールにヒットしない場合、元のバックエンドエラー応答がクライアントに返されます。

3.2. マッピングに関わるパラメータ

次のコードスニペットに示すように、マッピングに関与するパラメーターをparametersパラメーターのキーと値のペアとして指定する必要があります。 各キーはパラメータの名前です。 各値はLocation:Name形式で指定されます。 この形式は、パラメータの値が応答またはシステムのコンテキストから取得されることを示します。

---
# The parameters that are involved in mapping.
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"

'Location:Name' 形式を使用してパラメーター値を取得する場合は、次の場所を指定できます。 場所の詳細については、「パラメーターと条件式の使用」をご参照ください。

• ErrorCodeとErrorMessageの場所は、API Gatewayのシステムエラー応答のエラーコードとエラーメッセージを取得するために使用されます。 詳細については、「エラーコード一覧」をご参照ください。

• BodyJsonFieldの場所を使用して、バックエンド応答の本文でJSON文字列を取得できます。 ただし、レスポンス本文のサイズが16,380バイトを超える場合、取得される文字列は

  nullを使用します。

3.3. 働くメカニズム

以下のアクションは、エラーマッピングタイプのプラグインがどのように機能するかを説明します。

• 1. 手順1: parametersパラメーターで定義されているパラメーターのリストに基づいて、バックエンドエラー応答とシステムのコンテキストからパラメーターの値を取得します。

  2. ステップ2: パラメーターと取得した値を使用して、errorConditionパラメーターに記述された条件式を実行します。 結果がtrueの場合は、次のステップに進みます。 結果が偽である場合、プロセスは終了する。

  3. 手順3: errorCodeパラメーターが指定されている場合、errorCodeパラメーターの値で指定されているエラーコードを取得します。 次に、エラーコードがマッピングルールのcodeパラメーターの値と等しいかどうかを確認します。

  4. 手順4: 手順3でマッピングルールがヒットしなかった場合、マッピングルールのconditionパラメーターに記述されている条件式を順番に実行します。

  5. ステップ5: ステップ3またはステップ4でマッピングルールがヒットした場合、元のエラー応答はマッピングルールに基づいてマッピングされます。 それ以外の場合、元のエラー応答はデフォルトのマッピングルールに基づいてマッピングされます。

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

• API Gatewayでは、チェック、検証、スロットリング、プラグイン操作などのプロセスでシステムエラーが発生する可能性があります。 詳細については、「エラーコード表」をご参照ください。 ErrorCodeを場所として使用して、システムエラー応答の情報を取得できます。 たとえば、クライアントはHTTPステータスコード200のみをサポートし、API Gatewayによって返されるHTTPステータスコード429をHTTPステータスコード200にマッピングします。

• システムエラー応答の場合、StatusCode、Header、BodyJsonFieldなどの場所から取得される値はすべてnullです。 エラーマッピングタイプのプラグインのマッピング条件を定義する場合、バックエンドエラー応答の場合、ErrorCodeの場所から取得される値はOであることに注意してください。

• システムエラー応答のエラーコードは、X-Ca-error-codeヘッダーフィールドの値として返され、エラーログのerrorCodeパラメーターにも格納されます。 この値は、エラーマッピングタイプのプラグインを使用して上書きすることはできません。

• エラーログのstatusCodeパラメーターは、API Gatewayからクライアントに送信されるHTTPステータスコードの値を記録します。 この値は、エラーマッピングタイプのプラグインを使用して上書きできます。

4. 設定例

4.1. エラーマッピングのエラー応答でエラーコードを使用する

マッピング

---
# The parameters that are involved in mapping.
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"
# The mapping condition under which an error response needs to be mapped.
errorCondition: "$statusCode = 200 and $resultCode <> 'OK'"
# The parameter in an error response that is used to specify the error code and hit mapping rules.
errorCode: "resultCode"
# The mapping rules.
mappings:
  - code: "ROLE_NOT_EXISTS"
    statusCode: 404
    errorMessage: "Role Not Exists, RequestId=${resultId}"
  - code: "INVALID_PARAMETER"
    statusCode: 400
    errorMessage: "Invalid Parameter, RequestId=${resultId}"
# Optional. The default mapping rule.
defaultMapping:
  statusCode: 500
  errorMessage: "Unknown Error, ${resultCode}, RequestId=${resultId}"

5. 制限事項

• Error Mappingタイプの各プラグインには、最大16個のパラメーターを定義できます。

• 各条件式には、最大512文字を使用できます。

• BodyJsonFieldの場所を使用してエラーレスポンスの本文でJSON文字列を取得する場合、レスポンス本文のサイズは最大16,380バイトになります。 レスポンス本文のサイズがこの制限を超えると、取得される文字列はnullになります。

• エラーマッピングタイプの各プラグインに対して、最大16,380バイトのメタデータを設定できます。

• エラーマッピングタイプの各プラグインに対して、conditionパラメーターを使用して最大20個のマッピングルールを設定できます。