REST API で API Gateway 統合のレスポンスステータスコードをマッピングする方法を教えてください。

解決方法

バックエンドレスポンスステータスコードを上書きする場合は、 API Gateway マッピングテンプレートまたは正規表現を使用してステータスコードをマッピングします。これは、REST API とのプロキシ統合と非プロキシ統合で行うことができます。

プロキシ統合と非プロキシ統合を使用して、REST API のレスポンスステータスコードをマッピングします。プロキシレスポンスがあると、API Gateway はバックエンドから送信されたステータスコードを受け取ります。Lambda プロキシ統合では、API Gateway がバックエンドの Lambda 関数に次の出力を JSON 形式で返す要求をします。

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode, 
    "headers": { "headerName": "headerValue", ... },
    "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
    "body": “…”65411
}

Lambda 関数とのプロキシ統合では、ステータスコードはバックエンド Lambda 関数から API Gateway に直接渡されます。非プロキシ統合では、ステータスコードを Lambda 関数から直接渡すことはできません。

API Gateway が Lambda 関数を正常に呼び出すと、デフォルトのレスポンスステータスコードは 200 になります。Lambda でエラーが発生した場合も、ステータスコードが返されます。API Gateway のレスポンスコードはカスタマイズできます。カスタムレスポンスコードを作成する必要がある場合は、非プロキシ統合とマッピングテンプレートを使用してください。

カスタムコードによる応答方法の設定

以下の手順に従って、API Gateway からのカスタムレスポンスコードで応答するメソッドを設定します。

1.    API Gateway コンソールで、パブリック REST API を作成します。

2.    リソースとそのリソースのメソッドを作成します。

3.    API Gateway に返してほしいステータスコードを含むメソッドレスポンスを設定します。

4.    Lambda 統合レスポンスを設定します。

• Lambda Error Regex には、Lambda 関数によって返されるエラーメッセージの正規表現パターンを指定します。
  注: HTTP レスポンスの HTTP エラー正規表現も確認できます。
• メソッドのレスポンスステータスには、API Gateway が返す必要があるステータスコードを指定します。
• [Content Handling] (コンテンツの処理) のオプションを選択して、レスポンスをクライアントに送信する前にレスポンス本文をどのように処理するかを設定します。
• ステータスコードのデフォルトパターンが 200 に設定されていることを確認します。

5.    統合レスポンスの設定が完了したら、変更を保存、テスト、デプロイします。

ステータスコードを静的な値にマッピング

API Gateway がバックエンドから返されたステータスコードのグループをキャプチャするには、ステータスコードを静的な値にマッピングします。

1.    変更したいステータスコードのあるリソースに移動します。

2.    API Gateway のレスポンスコードとして 400 を返すようにメソッドレスポンスを設定します。

3.    リソース設定に戻り、統合レスポンスを設定します。

4.    HTTP ステータス正規表現の値は、バックエンドから返されたステータスをキャプチャします。その後、ステータスはステップ 2 で定義したレスポンスコードにマッピングされます。

HTTP ステータス正規表現のデフォルト値が「-」で、メソッドのレスポンスステータスとして 200 にマップされている場合、バックエンドマップがすべてのステータスコードをキャプチャし 200 に返します。HTTP ステータス正規表現値を 2\ d\ {2} に変更すると、すべての 2xx レスポンスをキャプチャして 200 にマッピングできます。

5.    他のステータスコードを取得するには、[Add integration response] (統合レスポンスの追加) を選択します。

4xx の場合は、 HTTP ステータス正規表現に、4\ d\ {2} を追加します。[Method response status] (メソッドレスポンスのステータス) で [400] を選択します。これはステップ 2 で定義されました。

6.    API をデプロイします。API が 2xx ステータスコードを返すと、それらは 200 ステータスコードにマッピングされます。API が 4xx ステータスコードを返す場合、それらは 400 ステータスコードにマッピングされます。

正規表現は複数の方法でフォーマットできます。以下はその例です。

• .* ([01] [0-9] [0-9] |2 [0-4] [0-9] |25 [0-5]) .* は、100-199、200-249、250-255 のいずれかの間のステータスコードに一致します。
• .*5\d\d.* は 5xx などのステータスコードと一致します。

次のサンプルコードは、Lambda 関数をテストするためのものです。

def lambda_handler(event, context):
    if "error" not in event or event['error'] == "":
        return("Pass")
    elif event['error'] == 'sample 400':
        raise Exception({"errorMessage": "Error: Raising 400 from within the Lambda function","errorType": "Exception"})
    elif event['error'] == 'sample 500':
        raise Exception({"errorMessage": "Error: Raising 500 from within the Lambda function","errorType": "Exception"})
    else:
        return("Error Value in the json request should either be 400 or 500 to demonstrate")

この例では、API Gateway から送信されたエラー値が 400 エラーか 500 エラーかをチェックします。400 または 500 エラーの場合、Lambda コードはエラーメッセージと共に例外を発生させます。API Gateway がレスポンスを受信すると、サービスはエラーメッセージが統合レスポンスで設定されたパターンと一致するかどうかをチェックします。API Gateway は、Lambda 正規表現パターンが一致した場合、それに応じて応答します。

7.    設定が成功したら、API Gateway コンソールを使用してステータスコードをテストできます。

マッピングテンプレートによるステータスコードのマッピング

前の例では正規表現を使用していますが、マッピングテンプレートも使用できます。次の例では、バックエンドの 200 ステータスコードを上書きして 400 ステータスコードを適用します。

1.    次のサンプルコードを使用して Lambda 関数を作成します。

----------------------
def lambda_handler(event, context):
    # TODO implement print(event)
    return { 'statusCode': 200, 'body': "customerror" }
-----------------------

2.    以前の Lambda 関数をバックエンドに使用して、Lambda の非プロキシ統合を含む API を作成します。

3.    「Override an API's response status code with the API Gateway console」(API Gateway コンソールで API のレスポンスステータスコードを上書きする) チュートリアルで説明されている手順 6 ～ 10 に従います。

この例では、次のマッピングテンプレートを使用します。

----------------------
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("customerror"))
#set($context.responseOverride.status = 400)
#end 
----------------------

4.    API を保存、テスト、デプロイします。

---

関連情報

モデルとマッピングテンプレートの操作

API リクエストとレスポンスの変革

Amazon API Gateway デべロッパーガイド