API Gateway の API とモデルを関連付けるにはどうすればよいですか?

最終更新日: 2020 年 10 月 30 日

Amazon API Gateway の API にモデルを統合したいと考えています。どうすればそれができますか?

簡単な説明

API Gateway で API 用のモデルを作成して、ペイロードのデータ形式を定義することができます。API Gateway モデルでは、JSON スキーマのドラフト 4 を使用する必要があります。

次の手順を実行して、モデルを API に関連付けます。

1.     モデルスキーマを作成し、API のモデルを作成します。

2.     モデルを API メソッドに関連付けます。

3.     モデルをテストします。

4.     (オプション) モデルのマッピングテンプレートを作成します。

5.     API をデプロイして、テストします。

解決方法

モデルスキーマを作成し、API のモデルを作成します。

API に関連付けるモデルスキーマを作成します。以下のモデル例では、API のユーザーは、リクエストボディで UserIDName を渡す必要があります。また、このモデルでは、UserIDName を文字列値にし、指定された Age は 18 以上の整数値にする必要があります。

注意: この例では、application/json を使用します。

{
  "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "User",
    "type": "object",
    "properties": {
        "UserID": {
            "type": "string"
        },
        "Name": {
            "type": "string"
        },
        "Age": {
            "description": "Age in years",
            "type": "integer",
            "minimum": 18
        }
    },
    "required": ["UserID", "Name"]
}

モデルスキーマを作成したら、API Gateway コンソールを使ってモデルを作成します

モデルを API メソッドに関連付ける

1.    API Gateway コンソール で API を開きます。

2.    ナビゲーションペインで [リソース] を選択します。

3.    モデルを関連付ける API メソッドを選択します。

4.    [Method Execution (メソッドの実行)] で [Method Request (メソッドリクエスト)] を選択します。

5.    [Request Validator (リクエストの検証)] で [Validate body (ボディの検証)] を選択します。次に、チェックアイコンを選び、選択内容を保存します。

6.    [Request Body (リクエストボディ)] を展開します。次に、[Add model (モデルの追加)] を選択します。

7.    [Content type] に、モデルのコンテンツタイプ (たとえば、"application/json") を入力します。

8.    [Model name (モデル名)] で、作成したモデルを選択します。

9.    チェックアイコンを選び、選択内容を保存します。

モデルをテストする

1.    API の [Resources (リソース)] リストから、モデルを関連付けた API メソッドを選択します。

2.    [Method Execution (メソッドの実行)] ビューで [TEST] を選択します。

3.    [Request Body] (リクエストボディ) に、作成したモデルスキーマと一致するリクエストボディを入力します。

注: application/json のサンプルモデルをテストするには、次の例のようなリクエスト本文が使用できます。

{ "UserID": "abc123", "Name":"Ana","Age":21}

4.    [Test] を選択します。

5.    サンプルのリクエストボディがモデルスキーマに一致すると、正常なレスポンスを受け取ります。

(オプション) モデルのマッピングテンプレートを作成する

マッピングテンプレートを使用して、API の統合バックエンドに送信されるリクエストを修正するには、以下のステップを実行します。

1.    API の [Resources (リソース)] リストから、モデルを関連付けた API メソッドを選択します。

2.    [Method Execution (メソッドの実行)] ビューで [Integration Request (統合リクエスト)] を選択します。

3.    [マッピングテンプレート] を展開します。

4.    [Request body passthrough] (リクエストボディのパススルー) には、[When there are no templates defined (recommended)] (テンプレートが定義されていない場合 (推奨)) を選択します。

5.    [マッピングテンプレートの追加] を選択します。

6.    [Content-Type] に、モデルのコンテンツタイプ (たとえば、"application/json") を入力します。次に、チェックアイコンを選び、選択内容を保存します。

7.     [Generate template] (テンプレートの生成) で、作成したモデルを選択します。

注: サンプルモデル application/json の場合は、次のように表示されます。

#set($inputRoot = $input.path('$')) { "UserID" : "$inputRoot.UserID", "Name" : "$inputRoot.Name", "Age" : $inputRoot.Age }

8.     API の統合バックエンドに渡す値に応じてテンプレートを修正します。

9.    [Save] (保存) を選択します。

API をデプロイして、テストする

1.    ナビゲーションペインで [リソース] を選択します。

2.    [Actions] を選択します。次に、[Deploy API (API をデプロイ)] を選択します。

3.    [Deployment stage (デプロイステージ)] で、既存のステージを選択するか、[New Stage (新しいステージ)] を選択してステージを作成します。新しいステージを作成した場合は、[Stage name (ステージ名)] に名前を入力する必要もあります。

4.    [デプロイ] を選択します。

API をテストするには、モデルに関連付けられたメソッドとコンテンツタイプを使用する API にテストリクエストを送信します。テストリクエストは、API 開発ツールまたは curl コマンドを使って送信できます。この curl コマンドは、この application/json モデル例のテストリクエストを送信します。

curl -X POST <YOUR-API-URL> -H 'Content-Type: application/json' -d '{ "UserID": "abc123", "Name":"Ana","Age":21}'

正しいメソッドとコンテンツタイプを使うテストリクエストを送信した後、正常なレスポンス "200 OK" を受け取ったことを確認してください。

他には、無効なレスポンス本文のテストリクエストを送信してのテストも行えます。次のリクエストボディは、必要な属性 UserID が含まれていないため、サンプルのモデル application/json では無効となります。

{ "Name":"Ana", "Age":21}

無効なリスポンスボディを使うテストリクエストを送信した後、「無効なリクエストボディ」などのメッセージを示す 400 エラーを受け取ります。