HTTP カスタム統合を使用して API を作成するリクエストパラメータをマッピングするレスポンスペイロードをマッピングする

チュートリアル: HTTP 非プロキシ統合を使用して REST API をビルドする

このチュートリアルでは、Amazon API Gateway コンソールを使用して、API をゼロから作成します。コンソールを API デザインスタジオとして使用して API 機能を絞り込み、その動作を確認して API を作成し、API をステージにデプロイします。

トピック

HTTP カスタム統合を使用して API を作成する
API Gateway API のリクエストパラメータをマッピングする
レスポンスペイロードをマッピングする

HTTP カスタム統合を使用して API を作成する

このセクションでは、リソースの作成、リソースでのメソッドの公開、目的の API 動作を達成するためのメソッドの設定、および API のテストとデプロイのステップを説明します。

API Gateway コンソール (https://console.aws.amazon.com/apigateway) にサインインします。
API Gateway を初めて使用する場合は、サービスの特徴を紹介するページが表示されます。[REST API] で、[構築] を選択します。[Create Example API (サンプル API の作成)] がポップアップ表示されたら、[OK] を選択します。

API Gateway を使用するのが初めてではない場合、[API を作成)] を選択します。[REST API] で、[構築] を選択します。
1. [新しい API] を選択します。
2. [API 名] に名前を入力します。
3. 必要に応じて、[説明] に短い説明を入力します。
4. [Create API] を選択します。
結果として、空の API が作成されます。[リソース] ツリーには、メソッドのないルートリソース (/) が表示されます。この演習では、PetStore ウェブサイト (http://petstore-demo-endpoint.execute-api.com/petstore/pets.) の HTTP カスタム統合を使用して API を作成します。わかりやすくするため、ルートの子として /pets リソースを作成し、クライアントが PetStore ウェブサイトから利用できる Pets 項目のリストを取得するために、このリソースで GET メソッドを公開します。
/pets リソースを作成するには、ルートを選択し、[アクション]、[リソースの作成] の順に選択します。

[Resource Name (リソース名)] に「Pets」と入力し、[Resource Path (リソースパス)] の値はそのままにして、[Enable API Gateway CORS (API Gateway CORS を有効にする)]、[Create Resource (リソースを作成する)] を選択します。
/pets リソースで GET メソッドを公開するには、[アクション] を選択し、[メソッドの作成] を選択します。

/pets リソースノードでリストから [GET] を選択し、チェックマークアイコンを選択してメソッドの作成を終了します。
注記
API メソッドの他のオプションには、以下があります。
- [POST]: 主に子リソースの作成に使用されます。
- PUT。既存のリソースを更新するために主に使用します (推奨はされませんが、子リソースの作成にも使用できます)。
- DELETE: リソースの削除に使用されます。
- [PATCH]; リソースの更新に使用されます。
- [HEAD]: テストシナリオで主に使用します。GET と同じですが、リソースの表現を返しません。
- [OPTIONS]: 対象サービスに使用できる通信オプションに関する情報を取得するために呼び出し元が使用できます。
作成されるメソッドは、まだバックエンドと統合されていません。次のステップでこれを設定します。
メソッドの [設定] ペインで、[統合タイプ] の [HTTP] を選択し、[HTTP メソッド] ドロップダウンリストの [GET] を選択します。次に、[エンドポイント URL] の値として「http://petstore-demo-endpoint.execute-api.com/petstore/pets」と入力し、他のすべての設定をデフォルトのままにして、[保存] を選択します。

注記
統合リクエストの [HTTP メソッド] で、バックエンドによってサポートされているメソッドを選択する必要があります。HTTP または Mock integration の場合、メソッドリクエストと統合リクエストが同じ HTTP 動詞を使用すると意味があります。他の統合タイプの場合、メソッドリクエストでは、おそらく統合リクエストとは異なる HTTP 動詞を使用します。たとえば、Lambda 関数を呼び出すには、統合リクエストでは POST を使用して関数を呼び出す必要がありますが、Lambda; 関数のロジックに応じて、メソッドリクエストでは任意の HTTP 動詞を使用できます。

メソッドの設定が終了すると、[メソッドの実行] ペインが表示され、さらにメソッドリクエストを設定し、クエリ文字列またはカスタムヘッダーパラメータを追加できます。また、統合リクエストを更新し、メソッドリクエストから入力データをマッピングして、バックエンドで必要な形式にすることもできます。

PetStore ウェブサイトでは、特定のページのペットのタイプ ("Dog" や "Cat" など) ごとに、Pet 項目のリストを取得できます。type および page クエリ文字列パラメータを使用して、このような入力を受け取ります。そのため、メソッドリクエストにクエリ文字列パラメーターを追加して、統合リクエストの対応するクエリ文字列にマッピングする必要があります。
GET メソッドの [メソッドの実行] ペインで [Method Request (メソッドリクエスト)] を選択し、[権限付与] の [AWS_IAM] を選択します。次に、[URL クエリ文字列パラメータ] セクションを展開し、[クエリ文字列の追加] を選択して、type および page という名前の 2 つのクエリ文字列パラメータを作成します。チェックマークアイコンを選択して、クエリ文字列パラメータを追加するごとに保存します。

これで、クライアントはリクエストを送信するときに、ペットのタイプとページ番号をクエリ文字列パラメーターとして指定できます。これらの入力パラメータは、バックエンドの PetStore ウェブサイトに入力値を転送するために、統合クエリ文字列パラメータにマッピングする必要があります。メソッドでは AWS_IAM を使用するため、メソッドを呼び出すにはリクエストに署名する必要があります。
メソッドの [統合リクエスト] ページから、[URL クエリ文字列パラメータ] セクションを展開します。デフォルトでは、メソッドリクエストのクエリ文字列パラメーターは、同様の名前の統合リクエストのクエリ文字列パラメーターにマッピングされます。このデフォルトマッピングは、デモ API で動作します。これはそのままにしておきます。対応する統合リクエストパラメータに別のリクエストパラメータをマッピングするには、[マッピング元] 列に示すように、パラメータの鉛筆アイコンを選択し、マッピング式を編集します。別の統合リクエストパラメータにメソッドリクエストパラメータをマッピングするには、最初に削除アイコンを選択して既存の統合リクエストパラメータを削除し、[クエリ文字列の追加] を選択して新しい名前と目的のメソッドリクエストのパラメータマッピング式を選択します。

シンプルなデモ API の作成が完了しました。これで API をテストできます。
API Gateway コンソールを使用して API をテストするには、GET /pets メソッドの [Method Execution (メソッドの実行)] ペインから[Test (テスト)] を選択します。[メソッドテスト] ペインで、[タイプ] および [ページ] クエリ文字列にそれぞれ「Dog」および「2」と入力し、[テスト] を選択します。

結果が次のように表示されます (テスト結果を表示するには、下へスクロールダウンしなければならない場合があります)。

これでテストが成功したので、API をデプロイし、公開することができます。
API をデプロイするには、API を選択し、[アクション] ドロップダウンメニューから [API のデプロイ] を選択します。

[API のデプロイ] ダイアログで、ステージ (または、API の最初のデプロイの場合は [New Stage]) を選択し、名前 (例: 「test」、「prod」、「dev」など) を [ステージ名] 入力フィールドに入力します。オプションで、[ステージの説明] または [デプロイメントの説明] (あるいはその両方) に説明を入力し、[デプロイ] を選択します。

デプロイ後は、API のエンドポイントの呼び出し URL (Invoke URL) を取得できます。

GET メソッドがオープンアクセスをサポートする場合 (メソッドの許可タイプが NONE に設定されている場合など)、デフォルトのブラウザでメソッドを呼び出すには [呼び出し URL] リンクをダブルクリックしてください。必要なら、URL の呼び出しにクエリ文字列パラメーターを付けることもできます。ここで説明した AWS_IAM 認証タイプでは、AWS アカウントの IAM ユーザーのアクセスキー ID と対応するシークレットアクセスキーでリクエストに署名する必要があります。これを行うには、署名バージョン 4 (SigV4) プロトコルをサポートするクライアントを使用してください。このようなクライアントとしては、AWS SDK または「Postman」アプリケーションまたは cURL コマンドを使うアプリケーションなどがあります。ペイロードを受け取る POST、PUT、PATCH メソッドを呼び出すには、ペイロードを処理するクライアントの使用も必須です。

Postman でこの API メソッドを呼び出すには、ステージ固有のメソッド呼び出し URL (前のイメージを参照) にクエリ文字列パラメータを追加して完全なメソッドリクエスト URL を作成します。
```
https://api-id.execute-api.region.amazonaws.com/test/pets?type=Dog&page=2
```
ブラウザのアドレスバーにこの URL を指定します。HTTP 動詞として [GET] を選択します。[AWS Signature] (AWS 署名) を [Type] (タイプ) オプションで [Authorization] (認証) タブから選択し、リクエストを送信する前に以下の必須プロパティを指定します。
- [AccessKey] には、AWS IAM からプロビジョニングされた発信者の AWS アクセスキーを入力します。
- [SecretKey] には、最初にアクセスキーが作成されたときに AWS IAM からプロビジョニングされた発信者の AWS シークレットキーを入力します。
- [AWS Region] (AWS リージョン) で、呼び出し URL で指定された API ホスティング AWS リージョンを入力します。
- [Service Name (サービス名)] には、API Gateway 実行サービスに「execute-api」と入力します。
SDK を使用してクライアントを作成する場合は、SDK で公開されたメソッドを呼び出して、リクエストに署名できます。実装の詳細については、選択する AWS SDK を参照してください。

注記
API が変更された場合、再度リクエスト URL を呼び出す前に、API を再デプロイして、新機能または更新された機能を使用できるようにする必要があります。

API Gateway API のリクエストパラメータをマッピングする

このチュートリアルでは、メソッドリクエストパラメータを、API Gateway API 用の該当する統合リクエストパラメータにマッピングする方法を説明します。HTTP カスタム統合でサンプル API を作成し、API Gateway を使用してメソッドリクエストパラメータを対応する統合リクエストパラメータにマッピングする方法を示します。次に以下のパブリックアクセス可能な HTTP エンドポイントにアクセスします。


http://petstore-demo-endpoint.execute-api.com/petstore/pets

上記の URL をコピーする場合は、ウェブブラウザのアドレスバーに貼り付け、Enter または Return を押すと、次の JSON 形式のレスポンス本文が取得されます。


[
  {
    "id": 1,
    "type": "dog",
    "price": 249.99
  },
  {
    "id": 2,
    "type": "cat",
    "price": 124.99
  },
  {
    "id": 3,
    "type": "fish",
    "price": 0.99
  }
]

前述のエンドポイントは、type および page の 2 つのクエリパラメータを受け取ることができます。たとえば、URL を次のように変更します。


http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=cat&page=2

この場合、猫のみを表示する 2 ページを表示する、次の JSON 形式のレスポンスペイロードを受け取ります。


[
  {
    "id": 4,
    "type": "cat",
    "price": 999.99
  },
  {
    "id": 5,
    "type": "cat",
    "price": 249.99
  },
  {
    "id": 6,
    "type": "cat",
    "price": 49.97
  }
]

このエンドポイントは、URL パスパラメーターで表示されるように、項目 ID の使用もサポートします。たとえば、次を参照する場合:


http://petstore-demo-endpoint.execute-api.com/petstore/pets/1

次のように、項目に関する JSON 形式の情報が ID 1 とともに表示されます。


{
  "id": 1,
  "type": "dog",
  "price": 249.99
}

サポートする GET オペレーションに加えて、このエンドポイントはペイロードで POST を受け取ります。例えば、Postman を使用して、POST メソッドリクエストを以下の場所に送信します。


http://petstore-demo-endpoint.execute-api.com/petstore/pets

ヘッダー Content-type: application/json と次のリクエストボディを含めます。


{
  "type": "dog",
  "price": 249.99
}

この場合、レスポンス本文で次の JSON オブジェクトを受け取ります。


{
  "pet": {
    "type": "dog",
    "price": 249.99
  },
  "message": "success"
}

ここで、この PetStore ウェブサイトの HTTP カスタム統合を使用して API Gateway API を作成して、これらの機能やその他の機能を公開します。タスクには次のものが含まれています。

https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets の HTTP エンドポイントのプロキシとして機能する http://petstore-demo-endpoint.execute-api.com/petstore/pets のリソースで、API を作成します。
API が 2 つのメソッドリクエストのクエリパラメータ (petType および petsPage) を受け取り、それぞれ統合リクエストの type および page クエリパラメータにマッピングして、リクエストを HTTP エンドポイントに渡すことができるようにします。
API のメソッドリクエスト URL の {petId} のパスパラメータをサポートし、項目 ID を指定します。また、これを統合リクエストの URL で {id} パスパラメータにマッピングし、リクエストを HTTP エンドポイントに送信します。
メソッドリクエストが、バックエンドウェブサイトで定義される形式の JSON ペイロードを受け取り、統合リクエストを通じて変更なしでペイロードをバックエンド HTTP エンドポイントに渡すことができるようにします。

トピック

Prerequisites
ステップ 1: リソースを作成する
ステップ 2: メソッドを作成してテストする
ステップ 3: API をデプロイする
ステップ 4: API をテストする

注記

この演習のステップでは使用されている大文字と小文字の違いに注意してください。大文字の代わりに小文字 (またはその逆) を入力すると、演習の後半でエラーが発生する場合があります。

Prerequisites

この演習を開始する前に、次の操作を行う必要があります。

API Gateway アクセス許可の IAM ユーザーへの割り当てなど、API Gateway の開始方法の前提条件のステップを完了します。
少なくとも、「チュートリアル: HTTP 非プロキシ統合を使用して REST API をビルドする」のステップに従って、API Gateway コンソールで MyDemoAPI という新しい API を作成します。

ステップ 1: リソースを作成する

このステップでは、API が HTTP エンドポイントを操作するための 3 つのリソースを作成します。

最初のリソースを作成する

[Resources] (リソース) ペインで単一のスラッシュ (/) で表されるリソースルートを選択し、次に [Actions] (アクション) ドロップダウンメニューから [Create Resource] (リソースの作成) を選択します。
[リソース名] に「petstorewalkthrough」を入力します。
[Resource Path (リソースパス)] で、デフォルトの [/petstorewalkthrough] をそのまま使用し、[Create Resource (リソースの作成)] を選択します。

2 番目のリソースを作成する

[Resources (リソース)] ペインで、[/petstorewalkthrough] を選択し、[Create Resource (リソースの作成)] を選択します。
[リソース名] に「pets」を入力します。
[Resource Path (リソースパス)] で、デフォルトの [/petstorewalkthrough/pets] をそのまま使用し、[Create Resource (リソースの作成)] を選択します。

3 番目のリソースを作成する

[Resources (リソース)] ペインで、[/petstorewalkthrough/pets] を選択し、[Create Resource (リソースの作成)] を選択します。
[リソース名] に「petId」を入力します。これは、HTTP エンドポイントの項目 ID にマッピングされます。
[Resource Path (リソースパス)] で、[petid] を {petId} で上書きします。/petstorewalkthrough/pets/ {petID} が { } の周りに表示されるように中括弧 (petId) を使用し、[Create Resource (リソースの作成)] を選択します。

これは、HTTP エンドポイントで /petstore/pets/my-item-id にマッピングされます。

ステップ 2: メソッドを作成してテストする

このステップでは、バックエンド HTTP エンドポイントとメソッドを統合し、GET メソッドリクエストパラメータを該当する統合リクエストパラメータにマッピングしてから、メソッドをテストします。

最初の GET メソッドをセットアップしてテストするには

この手順では、以下について示します。

GET /petstorewalkthrough/pets のメソッドリクエストを作成し、GET http://petstore-demo-endpoint.execute-api.com/petstore/pets の統合リクエストと統合します。
petType および petsPage のメソッドリクエストのクエリパラメータを、統合リクエストのクエリ文字列パラメータ type および page にそれぞれマッピングします。

[Resources] (リソース) ペインで [/petstorewalkthrough/pets] を選択し、[Actions] (アクション) メニューから [Create Method] (メソッドの作成) を選択して、メソッド名のドロップダウンリストから [/pets] 下の [GET] を選択します。
[/petstorewalkthrough/pets - GET - Setup] ペインで、[統合タイプ] の [HTTP] を選択し、[HTTP メソッド] の [GET] を選択します。
[Endpoint URL (エンドポイント URL)] に「http://petstore-demo-endpoint.execute-api.com/petstore/pets」と入力します。
[Save] を選択します。
[メソッドの実行] ペインで [メソッドリクエスト] を選択した後、[URL クエリ文字列パラメータ] の横の矢印を選択します。
[クエリ文字列の追加] を選択します。
[Name (名前)] に、「petType」と入力します。

これは、API のメソッドリクエストの petType クエリパラメータを指定します。
チェックマークアイコンを選択し、メソッドリクエスト URL クエリ文字列パラメータの作成を完了します。
[クエリ文字列の追加] を再度選択します。
[Name (名前)] に、「petsPage」と入力します。

これは、API のメソッドリクエストの petsPage クエリパラメータを指定します。
チェックマークアイコンを選択し、メソッドリクエスト URL クエリ文字列パラメータの作成を完了します。
[メソッドの実行]、[統合リクエスト] の順に選択した後、[URL クエリ文字列パラメータ] の横の矢印を選択します。
petType からマッピングされた method.request.querystring.petType エントリおよび petsPage からマッピングされた method.request.querystring.petsPage エントリを削除します。このステップを実行するのは、エンドポイントが、リクエスト URL に対して、デフォルト値ではなく type および page という名前のクエリ文字列パラメータを必要とするためです。
[クエリ文字列の追加] を選択します。
[Name (名前)] に、「type」と入力します。これにより、統合リクエスト URL に必要なクエリ文字列パラメータが作成されます。
[Mapped from (マッピング元)] に「method.request.querystring.petType」と入力します。

これは、メソッドリクエストの petType クエリパラメーターを統合リクエストの type クエリパラメーターにマッピングします。
チェックマークアイコンを選択し、統合リクエスト URL クエリ文字列パラメータの作成を完了します。
[クエリ文字列の追加] を再度選択します。
[Name (名前)] に、「page」と入力します。これにより、統合リクエスト URL に必要なクエリ文字列パラメータが作成されます。
[Mapped from (マッピング元)] に「method.request.querystring.petsPage」と入力します。

これは、メソッドリクエストの petsPage クエリパラメーターを統合リクエストの page クエリパラメーターにマッピングします。
チェックマークアイコンを選択し、統合リクエスト URL クエリ文字列パラメータの作成を完了します。
[メソッドの実行] を選択します。[クライアント] ボックスで、[テスト] を選択します。[クエリ文字列] エリアの [petType] に「cat」と入力します。[petsPage] に「2」と入力します。

[Test (テスト)] を選択します。成功すると、[レスポンス本文] に次の内容が表示されます。


[
  {
    "id": 4,
    "type": "cat",
    "price": 999.99
  },
  {
    "id": 5,
    "type": "cat",
    "price": 249.99
  },
  {
    "id": 6,
    "type": "cat",
    "price": 49.97
  }
]

2 番目の GET メソッドをセットアップしてテストするには

この手順では、以下について示します。

GET /petstorewalkthrough/pets/{petId} のメソッドリクエストを作成し、GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id} の統合リクエストと統合します。
petId のメソッドリクエストのパスパラメータを、id の統合リクエストのパスパラメータにマッピングします。

[Resources] (リソース) リストで [/petstorewalkthrough/pets/{petId}] を選択し、[Actions] (アクション)ドロップダウンメニューから [Create Method] (メソッドの作成) を選択して、メソッドの HTTP 動詞として [GET] を選択します。
[Setup (セットアップ)] ペインで、[統合タイプ] に [HTTP] を選択し、[HTTP メソッド] に [GET] を選択します。
[Endpoint URL (エンドポイント URL)] に「http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}」と入力します。
[Save] を選択します。
[メソッドの実行] ペインで [統合タイプ] を選択した後、[URL パスパラメータ] の横の矢印を選択します。
[パスの追加] を選択します。
[Name (名前)] に、「id」と入力します。
[Mapped from (マッピング元)] に「method.request.path.petId」と入力します。

これは petId のメソッドリクエストのパスパラメータを、id の統合リクエストのパスパラメータにマッピングします。
チェックマークアイコンを選択し、URL パスパラメーターの作成を完了します。
[メソッドの実行] を選択し、[クライアント] ボックスで [テスト] を選択します。[パス] エリアの [petId] に「1」と入力します。
[Test (テスト)] を選択します。成功すると、[レスポンス本文] に次の内容が表示されます。
```
{   
  "id": 1,
  "type": "dog",
  "price": 249.99
}
```

POST メソッドをセットアップしてテストするには

この手順では、以下について示します。

POST /petstorewalkthrough/pets のメソッドリクエストを作成し、POST http://petstore-demo-endpoint.execute-api.com/petstore/pets の統合リクエストと統合します。
メソッドリクエストの JSON ペイロードを、変更せずに統合リクエストペイロードに渡します。

[Resources] (リソース) ペインで [/petstorewalkthrough/pets] を選択し、[Actions] (アクション) ドロップダウンメニューから [Create Method] (メソッドの作成) を選択して、メソッドの HTTP 動詞として [POST] を選択します。
[Setup (セットアップ)] ペインで、[統合タイプ] に [HTTP] を選択し、[HTTP メソッド] に [POST] を選択します。
[Endpoint URL (エンドポイント URL)] に「http://petstore-demo-endpoint.execute-api.com/petstore/pets」と入力します。
[Save] を選択します。
[メソッドの実行] ペインの [クライアント] ボックスで、[テスト] を選択します。[リクエストボディ] を展開した後、次を入力します。
```
{
  "type": "dog",
  "price": 249.99
}
```
[Test (テスト)] を選択します。成功すると、[レスポンス本文] に次の内容が表示されます。
```
{
  "pet": {
    "type": "dog",
    "price": 249.99
  },
  "message": "success"
}
```

ステップ 3: API をデプロイする

このステップでは、API をデプロイして、以降 API Gateway コンソール外で呼び出せるようにします。

API をデプロイする

[リソース] ペインで、[API のデプロイ] を選択します。
[デプロイされるステージ] で、[test] を選択します。

注記
入力は UTF-8 でエンコードされた (ローカライズされていない) テキストである必要があります。
[デプロイメントの説明] に「Calling HTTP endpoint walkthrough」と入力します。
[デプロイ] を選択します。

ステップ 4: API をテストする

このステップでは、API Gateway コンソール外に移動し、API を使用して HTTP エンドポイントにアクセスします。

[ステージエディター] ペインの [呼び出し URL] の横で、URL をクリップボードにコピーします。次のように表示されます。
```
https://my-api-id.execute-api.region-id.amazonaws.com/test
```
ブラウザーの新しいタブのアドレスボックスにこの URL を貼り付けます。

次のように /petstorewalkthrough/pets を追加します。


https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets

URL を参照します。次の情報が表示されます。


[
  {
    "id": 1,
    "type": "dog",
    "price": 249.99
  },
  {
    "id": 2,
    "type": "cat",
    "price": 124.99
  },
  {
    "id": 3,
    "type": "fish",
    "price": 0.99
  }
]

petstorewalkthrough/pets の後に、「?petType=cat&petsPage=2」と入力します。次のように表示されます。
```
https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets?petType=cat&petsPage=2
```

URL を参照します。次の情報が表示されます。


[
  {
    "id": 4,
    "type": "cat",
    "price": 999.99
  },
  {
    "id": 5,
    "type": "cat",
    "price": 249.99
  },
  {
    "id": 6,
    "type": "cat",
    "price": 49.97
  }
]

petstorewalkthrough/pets の後の「?petType=cat&petsPage=2」を「/1」と置き換えます。次のように表示されます。
```
https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets/1
```
URL を参照します。次の情報が表示されます。
```
{
  "id": 1,
  "type": "dog",
  "price": 249.99
}
```
ウェブデバッギングプロキシツールまたは cURL コマンドラインツールを使用して、前の手順から POST メソッドリクエストを URL に送信します。次のように /petstorewalkthrough/pets を追加します。
```
https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets
```
以下のヘッダーを加えます。
```
Content-Type: application/json
```
また、リクエストボディに次のコードを追加してください。
```
{
  "type": "dog",
  "price": 249.99
}
```
たとえば、cURL コマンドラインツールを使用する場合は、次のようなコマンドを実行します。
```
curl -H "Content-Type: application/json" -X POST -d "{\"type\": \"dog\",\"price\": 249.99}" https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets
```
その後、次の情報が応答本文で返されます。
```
{
  "pet": {
    "type": "dog",
    "price": 249.99
  },
  "message": "success"
}
```

このチュートリアルはこれで終了です。

レスポンスペイロードをマッピングする

このチュートリアルでは、API Gateway でモデルとマッピングテンプレートを使用して API コールの出力を 1 つのデータスキーマから別のものに変換する方法について説明します。この演習は、「API Gateway の開始方法」および「API Gateway API のリクエストパラメータをマッピングする」の手順と概念に基づいています。これらの演習を完了していない場合は、先に完了することを推奨します。

このチュートリアルでは API Gateway を使用し、パブリックにアクセス可能な HTTP エンドポイントと、今回作成する AWS Lambda 関数からサンプルデータを取得します。HTTP エンドポイントと Lambda 関数は同じサンプルデータを返します。


[
  {
    "id": 1,
    "type": "dog",
    "price": 249.99
  },
  {
    "id": 2,
    "type": "cat",
    "price": 124.99
  },
  {
    "id": 3,
    "type": "fish",
    "price": 0.99
  }
]

モデルとマッピングテンプレートを使用し、このデータの出力形式を 1 回以上変換します。API Gateway では、モデルが一部のデータの形式 (スキーマ、シェイプとも呼ばれます) を定義します。API Gateway では、一部のデータの形式を変換する目的でマッピングテンプレートが使用されます。詳細については、「モデルとマッピングテンプレートの使用」を参照してください。

最初のモデルとマッピングテンプレートは、次のように id から number、type から class、および price から salesPrice に名前変更する目的で使用されます。


[
  {
    "number": 1,
    "class": "dog",
    "salesPrice": 249.99
  },
  {
    "number": 2,
    "class": "cat",
    "salesPrice": 124.99
  },
  {
    "number": 3,
    "class": "fish",
    "salesPrice": 0.99
  }
]

2 番目のモデルとマッピングテンプレートは、次のように id と type を description に結合し、price を askingPrice に名前変更する目的で使用されます。


[
  {
    "description": "Item 1 is a dog.",
    "askingPrice": 249.99
  },
  {
    "description": "Item 2 is a cat.",
    "askingPrice": 124.99
  },
  {
    "description": "Item 3 is a fish.",
    "askingPrice": 0.99
  }
]

3 番目のモデルとマッピングテンプレートは、次のように id、type、および price を listings のセットに結合する目的で使用されます。


{
  "listings": [
    "Item 1 is a dog. The asking price is 249.99.",
    "Item 2 is a cat. The asking price is 124.99.",
    "Item 3 is a fish. The asking price is 0.99."
  ]
}

トピック

ステップ1: モデルを作成する
ステップ 2: リソースを作成する
ステップ 3: GET メソッドを作成する
ステップ 4: Lambda 関数を作成する
ステップ 5: メソッドをセットアップしてテストする
ステップ 6: API をデプロイする
ステップ 7: API をテストする
ステップ 8: クリーンアップする

ステップ1: モデルを作成する

このステップでは、4 つのモデルを作成します。最初の 3 つのモデルは、HTTP エンドポイントと Lambda 関数で使用するデータ出力形式を表します。最後のモデルは、Lambda 関数で使用するデータ入力スキーマを表します。

最初の出力モデルを作成する

https://console.aws.amazon.com/apigateway で API Gateway コンソールにサインインします。
MyDemoAPI が表示されている場合は、[Models (モデル)] を選択します。
[Create] を選択します。
[Model name (モデル名)] に「PetsModelNoFlatten」と入力します。
[コンテンツタイプ] に「application/json」と入力します。
[モデルの説明] に「Changes id to number, type to class, and price to salesPrice」を入力します。

[モデルのスキーマ] に、次の JSON スキーマ互換定義を入力します。


{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "PetsModelNoFlatten",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "number": { "type": "integer" },
      "class": { "type": "string" },
      "salesPrice": { "type": "number" }
    }
  }
}

[モデルの作成] を選択します。

2 番目の出力モデルを作成する

[Create] を選択します。
[Model name (モデル名)] に「PetsModelFlattenSome」と入力します。
[コンテンツタイプ] に「application/json」と入力します。
[モデルの説明] に「Combines id and type into description, and changes price to askingPrice」を入力します。

[モデルのスキーマ] に、以下を入力します。


{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "PetsModelFlattenSome",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "description": { "type": "string" },
      "askingPrice": { "type": "number" }    
    }
  }
}

[モデルの作成] を選択します。

3 番目の出力モデルを作成する

[Create] を選択します。
[Model name (モデル名)] に「PetsModelFlattenAll」と入力します。
[コンテンツタイプ] に「application/json」と入力します。
[モデルの説明] に「Combines id, type, and price into a set of listings」を入力します。

[モデルのスキーマ] に、以下を入力します。


{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "PetsModelFlattenAll",
  "type": "object",
  "properties": {
    "listings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

[モデルの作成] を選択します。

入力モデルを作成する

[Create] を選択します。
[Model name (モデル名)] に「PetsLambdaModel」と入力します。
[コンテンツタイプ] に「application/json」と入力します。
[モデルの説明] に「GetPetsInfo model」を入力します。

[モデルのスキーマ] に、以下を入力します。


{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "PetsLambdaModel",
  "type": "array",
  "items": {
    "type": "object", 
    "properties": {
      "id": { "type": "integer" },
      "type": { "type": "string" },
      "price": { "type": "number" }
    }
  }
}

[モデルの作成] を選択します。

ステップ 2: リソースを作成する

このステップでは、4 つのリソースを作成します。最初の 3 つのリソースは、HTTP エンドポイントから 3 つの出力形式でサンプルデータを取得するためのものです。最後のリソースは、id と type を description に結合して price を askingPrice に名前変更する出力スキーマで Lambda 関数からサンプルデータを取得するためのものです。

最初のリソースを作成する

リンクリストで [リソース] を選択します。
[Resources (リソース)] ペインで、[/petstorewalkthrough] を選択し、[Create Resource (リソースの作成)] を選択します。
[リソース名] に「NoFlatten」を入力します。
[Resource Path (リソースパス)] で、デフォルトの [/petstorewalkthrough/noflatten] をそのまま使用して、[Create Resource (リソースの作成)] を選択します。

2 番目のリソースを作成する

[Resources (リソース)] ペインで、[/petstorewalkthrough] をもう一度選択し、[Create Resource (リソースの作成)] を選択します。
[リソース名] に「FlattenSome」を入力します。
[Resource Path (リソースパス)] で、デフォルトの /petstorewalkthrough/flattensome をそのまま使用して、[Create Resource (リソースの作成)] を選択します。

3 番目のリソースを作成する

[Resources (リソース)] ペインで、[/petstorewalkthrough] をもう一度選択し、[Create Resource (リソースの作成)] を選択します。
[リソース名] に「FlattenAll」を入力します。
[Resource Path (リソースパス)] で、デフォルトの [/petstorewalkthrough/flattenall] をそのまま使用して、[Create Resource (リソースの作成)] を選択します。

4 番目のリソースを作成する

[Resources (リソース)] ペインで、[/petstorewalkthrough] をもう一度選択し、[Create Resource (リソースの作成)] を選択します。
[リソース名] に「LambdaFlattenSome」を入力します。
[Resource Path (リソースパス)] で、デフォルトの [/petstorewalkthrough/lambdaflattensome] をそのまま使用して、[Create Resource (リソースの作成)] を選択します。

ステップ 3: GET メソッドを作成する

このステップでは、前のステップで作成した各リソース用に GET メソッドを作成します。

最初の GET メソッドを作成する

[Resources (リソース)] リストで、[/petstorewalkthrough/flattenall] を選択し、[Create Method (メソッドの作成)] を選択します。
ドロップダウンリストから [GET] を選択し、チェックマークアイコンを選択して選択内容を保存します。
[Setup (設定)]ペインで、[Integration type (統合タイプ)] として [HTTP]、[HTTP method (HTTP メソッド)] として [GET] を選択し、[Endpoint URL (エンドポイント URL)] に「http://petstore-demo-endpoint.execute-api.com/petstore/pets」と入力して [Save (保存)] を選択します。

2 番目の GET メソッドを作成する

[Resources (リソース)] リストで、[/petstorewalkthrough/lambdaflattensome] を選択し、[Create Method (メソッドの作成)] を選択します。
ドロップダウンリストから [GET] を選択し、チェックマークを選択して選択内容を保存します。
[Setup (設定)]ペインで、[Integration type (統合タイプ)] として [Lambda Function (Lambda 関数)] を選択し、[Lambda リージョン] ドロップダウンリストから GetPetsInfo Lambda 関数を作成したリージョンを選択します。次に、[Lambda Function (Lambda 関数)] として [GetPetsInfo] を選択して [Save (保存)] を選択します。Lambda 関数にアクセス許可を追加するよう求められたら、[OK] を選択します。

3 番目の GET メソッドを作成する

[Resources (リソース)] リストで、[/petstorewalkthrough/flattensome] を選択し、[Create Method (メソッドの作成)] を選択します。
ドロップダウンリストから [GET] を選択し、チェックマークアイコンを選択して選択内容を保存します。
[Setup (設定)] ペインで、[Integration type (統合タイプ)] として [HTTP]、[HTTP method (HTTP メソッド)] として [GET] を選択し、[Endpoint URL (エンドポイント URL)] に「http://petstore-demo-endpoint.execute-api.com/petstore/pets」と入力して [Save (保存)] を選択します。

4 番目の GET メソッドを作成する

[Resources (リソース)] リストで、[/petstorewalkthrough/noflatten] を選択し、[Actions (アクション)]、[Create Method (メソッドの作成)] の順に選択します。
ドロップダウンリストから [GET] を選択し、チェックマークアイコンを選択して選択内容を保存します。
[Setup (設定)] ペインで、[Integration type (統合タイプ)] として [HTTP]、[HTTP method (HTTP メソッド)] として [GET] を選択し、[Endpoint URL (エンドポイント URL)] に「http://petstore-demo-endpoint.execute-api.com/petstore/pets」と入力して [Save (保存)] を選択します。

ステップ 4: Lambda 関数を作成する

このステップでは、サンプルデータを返す Lambda 関数を作成します。

Lambda 関数を作成するには

https://console.aws.amazon.com/lambda/ で、AWS Lambda コンソールを開きます。
次のいずれかを行ってください。
- ウェルカムページが表示される場合は、[今すぐ始める] を選択します。
- [Lambda: Function list (Lambda: 関数リスト)] ページが表示される場合は、[Create a Lambda function (Lambda 関数の作成)] を選択します。
[Name (名前)] に、「GetPetsInfo」と入力します。
[説明] に「Gets information about pets」と入力します。
[コードテンプレート] で、[なし] を選択します。
次のコードを入力します。
```
console.log('Loading event');

exports.handler = function(event, context, callback) {
  callback(null, 
    [{"id": 1, "type": "dog", "price": 249.99},
    {"id": 2, "type": "cat", "price": 124.99},
    {"id": 3, "type": "fish", "price": 0.99}]); // SUCCESS with message
};
```
ヒント
Node.js で書かれた前述のコードで、console.log が Amazon CloudWatch log に情報を書き込みます。event には、Lambda 関数への入力が含まれています。context には、呼び出しコンテキストが含まれています。callback は、結果を返します。Lambda 関数コードの作成方法の詳細については、AWS Lambda: How it Works の「Programming Model」セクションと、AWS Lambda デベロッパーガイドのサンプルチュートリアルを参照してください。
[Handler name (ハンドラ名)] でデフォルトの index.handler を選択します。
[Role (ロール)] で、で作成した Lambda 実行ロール [ApigateWayLambdaExecRole] を選択します Lambda 統合で API Gateway REST API を構築する。
[Create Lambda function] を選択します。
関数リストで、[GetPetsInfo] を選択して関数の詳細を表示します。
この関数を作成した AWS リージョンをメモしておきます。これは、後で必要になります。
ポップアップリストで、[関数の編集またはテスト] を選択します。
[サンプルイベント] で、表示されたコードを次のように置換します。
```
{
                   
}
```
ヒント
空の中括弧は、この Lambda 関数に入力値が存在しないことを意味しています。この関数では、ペット情報を含む JSON オブジェクトのみ返るため、ここではこれらのキーと値のペアは必要ありません。
[呼び出し] を選択します。[Execution result (実行結果)] に、[{"id":1,"type":"dog","price":249.99},{"id":2,"type":"cat","price":124.99},{"id":3,"type":"fish","price":0.99}] が表示されます。また、同じ内容が CloudWatch Logs ログにも書き込まれます。
[Go to function list (関数リストに移動)] を選択します。

ステップ 5: メソッドをセットアップしてテストする

このステップでは、メソッドレスポンス、統合リクエスト、統合レスポンスを設定して、HTTP エンドポイントと Lambda; 関数に関連付けられている GET メソッドの入出力データスキーマ (またはモデル) を指定します。API Gateway コンソールでこれらのメソッドを呼び出してテストする方法についても説明します。

最初の GET メソッドの統合を設定してテストするには

API の [Resources (リソース)] ツリーから、[/petstorewalkthrough/flattenall] ノードの下の [GET] を選択します。
[メソッドの実行] ペインで、[メソッドレスポンス] を選択してから [200] の横の矢印を選択します。
[Response Models for 200 (200 のレスポンスモデル)] エリアで、[application/json] の鉛筆アイコンを選択し、メソッド出力のモデルの設定を開始します。[Models (モデル)] で、[PetsModelFlattenAll] を選択し、チェックマークアイコンを選択して設定を保存します。
[メソッドの実行]、[統合レスポンス] の順に選択してから、[200] の横の矢印を選択します。
[マッピングテンプレート] セクションを展開し、[Content-Type] で [application/json] を選択します。
[Generate template from model (モデルからテンプレートを作成)] で [PetsModelFlattenAll] を選択し、開始点として [PetsModelFlattenAll] モデルの後にマッピングテンプレートを表示します。

マッピングテンプレートコードを次のように変更します。


#set($inputRoot = $input.path('$'))
{
  "listings" : [
#foreach($elem in $inputRoot)
    "Item number $elem.id is a $elem.type. The asking price is $elem.price."#if($foreach.hasNext),#end
        
#end
  ]
}

[Save] を選択します。

[メソッドの実行] を選択し、[クライアント] ボックスで [テスト]、[テスト] の順に選択します。成功すると、[レスポンス本文] に次の内容が表示されます。


{
  "listings" : [
    "Item number 1 is a dog. The asking price is 249.99.",        
    "Item number 2 is a cat. The asking price is 124.99.",        
    "Item number 3 is a fish. The asking price is 0.99."        
  ]
}

2 番目の GET メソッドの統合を設定してテストするには

API の [Resources (リソース)] ツリーから、[/petstorewalkthrough/lambdaflattensome] ノードの下の [GET] を選択します。
[メソッドの実行] で、[メソッドレスポンス] を選択します。次に [200] の横にある矢印を選択してセクションを展開します。
[Response Models for 200 (200 のレスポンスモデル)] エリアで、[application/json] のコンテンツタイプの行にある鉛筆アイコンを選択します。[Models (モデル)] で [PetsModelFlattenSome] を選択し、チェックマークアイコンを選択して選択内容を保存します。
[メソッドの実行] に戻ります。[統合レスポンス] を選択し、[200] の横にある矢印を選択します。
[マッピングテンプレート] セクションの [Content-Type] で [application/json] を選択します。
[Generate template (テンプレートの作成)] で [PetsModelFlattenSome] を選択して、このメソッドの出力のマッピングスクリプトテンプレートを表示します。

コードを次のように変更して、[保存] を選択します。


#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
  {
    "description" : "Item $elem.id is a $elem.type.",
    "askingPrice" : $elem.price
  }#if($foreach.hasNext),#end

#end
]


[
  {
    "description" : "Item 1 is a dog.",
    "askingPrice" : 249.99
  },    
  {
    "description" : "Item 2 is a cat.",
    "askingPrice" : 124.99
  },    
  {
    "description" : "Item 3 is a fish.",
    "askingPrice" : 0.99
  }    
]

3 番目の GET メソッドの統合を設定してテストするには

API の [Resources (リソース)] ツリーから、[/petstorewalkthrough/flattensome] ノードの下の [GET] を選択します。
[メソッドの実行] ペインで、[メソッドレスポンス] を選択します。
の横にある矢印を選択します。。
[Response Models for 200 (200 のレスポンスモデル)] エリアで、[application/json] の鉛筆アイコンを選択します。[Models (モデル)] で、[PetsModelFlattenSome] を選択し、チェックマークアイコンを選択して選択内容を保存します。
[メソッドの実行] に戻って、[統合タイプ] を選択します。
[200] の横にある矢印を選択してセクションを展開します。
[マッピングテンプレート] エリアを展開します。[Content-Type] の [application/json] を選択します。[Generate template (テンプレートの作成)] で [PetsModelFlattenSome] を選択して、このメソッドの出力のマッピングスクリプトテンプレートを表示します。

次のようにコードを変更します。


#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
  {
    "description": "Item $elem.id is a $elem.type.",
    "askingPrice": $elem.price 
  }#if($foreach.hasNext),#end

#end
]

[Save] を選択します。

[メソッドの実行] に戻って、[クライアント] ボックスの [テスト] を選択します。次に [テスト] を選択します。成功すると、[レスポンス本文] に次の内容が表示されます。


[
  {
    "description": "Item 1 is a dog.",
    "askingPrice": 249.99
  },    
  {
    "description": "Item 2 is a cat.",
    "askingPrice": 124.99
  },    
  {
    "description": "Item 3 is a fish.",
    "askingPrice": 0.99
  }    
]

4 番目の GET メソッドの統合を設定してテストするには

API の Resources (リソース) ツリーから、[/petstorewalkthrough/noflatten] ノードの下の [GET] を選択します。
[メソッドの実行] ペインで、[メソッドレスポンス] を選択して [200] セクションを展開します。
[Response Models for 200 (200 のレスポンスモデル)] エリアで、[application/json] の鉛筆アイコンを選択して、このメソッドのレスポンスモデルを更新します。
[application/json] のコンテンツタイプのモデルとして [PetsModelNoFlatten] を選択し、チェックマークアイコンを選択して選択内容を保存します。
[メソッドの実行]、[統合レスポンス] の順に選択してから、[200] の横の矢印を選択してセクションを展開します。
[マッピングテンプレート] セクションを展開します。[Content-Type] の [application/json] を選択します。[Generate templates (テンプレートの生成)] で [PetsModelNoFlatten] を選択して、このメソッドの出力のマッピングスクリプトテンプレートを表示します。

次のようにコードを変更します。


#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
  {
    "number": $elem.id,
    "class": "$elem.type",
    "salesPrice": $elem.price 
  }#if($foreach.hasNext),#end

#end
]

[Save] を選択します。

[メソッドの実行] に戻って、[クライアント] ボックスで [テスト]、[テスト] の順に選択します。成功すると、[レスポンス本文] に次の内容が表示されます。


[
  {
    "number": 1,
    "class": "dog",
    "salesPrice": 249.99
  },    
  {
    "number": 2,
    "class": "cat",
    "salesPrice": 124.99
  },    
  {
    "number": 3,
    "class": "fish",
    "salesPrice": 0.99
  }    
]

ステップ 6: API をデプロイする

このステップでは、API をデプロイして、以降 API Gateway コンソール外で呼び出せるようにします。

API をデプロイする

[リソース] ペインで、[API のデプロイ] を選択します。
[デプロイされるステージ] で、[test] を選択します。
[デプロイメントの説明] に「Using models and mapping templates walkthrough」と入力します。
[デプロイ] を選択します。

ステップ 7: API をテストする

このステップでは、API Gateway コンソール外で HTTP エンドポイントと Lambda 関数を操作します。

[ステージエディター] ペインの [呼び出し URL] の横で、URL をクリップボードにコピーします。次のように表示されます。
```
https://my-api-id.execute-api.region-id.amazonaws.com/test
```
ブラウザーの新しいタブのアドレスボックスにこの URL を貼り付けます。

次のように /petstorewalkthrough/noflatten を追加します。


https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/noflatten

URL を参照します。次の情報が表示されます。


[
  {
    "number": 1,
    "class": "dog",
    "salesPrice": 249.99
  },    
  {
    "number": 2,
    "class": "cat",
    "salesPrice": 124.99
  },    
  {
    "number": 3,
    "class": "fish",
    "salesPrice": 0.99
  }    
]

petstorewalkthrough/ の後、noflatten を flattensome と置き換えます。

URL を参照します。次の情報が表示されます。


[
  {
    "description": "Item 1 is a dog.",
    "askingPrice": 249.99
  },    
  {
    "description": "Item 2 is a cat.",
    "askingPrice": 124.99
  },    
  {
    "description": "Item 3 is a fish.",
    "askingPrice": 0.99
  }    
]

petstorewalkthrough/ の後、flattensome を flattenall と置き換えます。

URL を参照します。次の情報が表示されます。


{
  "listings" : [
    "Item number 1 is a dog. The asking price is 249.99.",        
    "Item number 2 is a cat. The asking price is 124.99.",        
    "Item number 3 is a fish. The asking price is 0.99."        
  ]
}

petstorewalkthrough/ の後、flattenall を lambdaflattensome と置き換えます。

URL を参照します。次の情報が表示されます。


[
  {
    "description" : "Item 1 is a dog.",
    "askingPrice" : 249.99
  },    
  {
    "description" : "Item 2 is a cat.",
    "askingPrice" : 124.99
  },    
  {
    "description" : "Item 3 is a fish.",
    "askingPrice" : 0.99
  }    
]

ステップ 8: クリーンアップする

このチュートリアルで作成した Lambda 関数が不要になった場合は、削除できます。また、付随する IAM リソースも削除できます。

警告

API が依存する Lambda 関数を削除すると、API は機能しなくなります。Lambda 関数の削除は元に戻すことができません。再度 Lambda 関数を使用するには、関数を再度作成する必要があります。

Lambda 関数が依存している IAM リソースを削除すると、Lambda 関数は機能しなくなります。また、同関数に依存する API は機能しなくなります。IAM リソースの削除は元に戻すことができません。再度 IAM リソースを使用するには、リソースを再度作成する必要があります。このチュートリアルや他のチュートリアルで作成したリソースをひき続き試す場合は、Lambda 呼び出しロールまたは Lambda 実行ロールを削除しないでください。

Lambda 関数を削除するには

AWS Management Console にサインインして AWS Lambda コンソール (https://console.aws.amazon.com/lambda/) を開きます。
[Lambda: Function list (Lambda: 関数リスト)] ページの関数リストで、[GetPetsInfo] の横のボタンを選択した後、[Actions (アクション)]、[Delete (削除)] の順に選択します。プロンプトが表示されたら、再度 [削除] を選択します。

関連付けられた IAM リソースを削除する

IAM コンソール (https://console.aws.amazon.com/iam/) を開きます。
[詳細] エリアで、[ロール] を選択します。
[ApigateWayLambdaExecRole] を選択し、[Role Actions (ロールアクション)]、[Delete Role (ロールの削除)] の順に選択します。プロンプトが表示されたら、[Yes, Delete (はい、削除します)] を選択します。
[詳細] エリアで、[ポリシー] を選択します。
[APIGatewayLambdaExecPolicy] を選択し、[Policy Actions (ポリシーアクション)]、[Delete (削除)] の順に選択します。プロンプトが表示されたら、[削除] を選択します。

この演習はこれで終了です。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

チュートリアル: HTTP プロキシ統合を使用して REST API をビルドする

チュートリアル: プライベート統合を使用して API をビルドする