Amazon API Gateway
開発者ガイド

HTTP カスタム統合で API をビルドする

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

HTTP カスタム統合で API を作成する

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

  1. https://console.aws.amazon.com/apigateway で API Gateway コンソールにサインインします。

  2. API を作成するには、[Create new API] (最初の API を作成する場合)または [Create API] (以降の API を作成する場合)を選択します。次に、以下の手順を実行します。

    1. [New API] を選択します。

    2. [API Name] に名前を入力します。

    3. 必要に応じて、[Description] に短い説明を 入力します。

    4. [Create API] を選択します。

    結果として、空の API が作成されます。[リソース] ツリーには、メソッドのないルートリソース (/) が表示されます。この演習では、PetStore ウェブサイト (http://petstore-demo-endpoint.execute-api.com/petstore/pets.) の HTTP カスタム統合を使用して API を作成します。 わかりやすくするため、ルートの子として /pets リソースを作成し、クライアントが PetStore ウェブサイトから利用できる Pets 項目のリストを取得するために、このリソースで GET メソッドを公開します。

  3. /pets リソースを作成するには、ルートを選択し、[アクション]、[リソースの作成] の順に選択します。

    [Resource Name (リソース名)] に「Pets」と入力し、[Resource Path (リソースパス)] の値はそのままにして、[Enable API Gateway CORS (API Gateway CORS を有効にする)]、[Create Resource (リソースを作成する)] を選択します。

    
                        リソース Part B を作成する
  4. /pets リソースで GET メソッドを公開するには、[アクション] を選択し、[メソッドの作成] を選択します。

    
                        リソースでメソッドを作成する

    /pets リソースノードでリストから [GET] を選択し、チェックマークアイコンを選択してメソッドの作成を終了します。

    
                        リソースでメソッドを作成する

    注記

    API メソッドの他のオプションには、以下があります。

    • [POST]: 主に子リソースの作成に使用されます。

    • PUT。既存のリソースを更新するために主に使用します (推奨はされませんが、子リソースの作成にも使用できます)。

    • DELETE: リソースの削除に使用されます。

    • [PATCH]; リソースの更新に使用されます。

    • [HEAD]: テストシナリオで主に使用します。GET と同じですが、リソースの表現を返しません。

    • [OPTIONS]: 対象サービスに使用できる通信オプションに関する情報を取得するために呼び出し元が使用できます。

    作成されるメソッドは、まだバックエンドと統合されていません。次のステップでこれを設定します。

  5. メソッドの [設定] ペインで、[統合タイプ] の [HTTP] を選択し、[HTTP メソッド] ドロップダウンリストの [GET] を選択します。次に、[エンドポイント URL] の値として「http://petstore-demo-endpoint.execute-api.com/petstore/pets」と入力し、他のすべての設定をデフォルトのままにして、[保存] を選択します。

    注記

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

    
                        GET on Pets を PetStore サイトと統合する

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

    PetStore ウェブサイトでは、特定のページのペットのタイプ ("Dog" や "Cat" など) ごとに、Pet 項目のリストを取得できます。type および page クエリ文字列パラメータを使用して、このような入力を受け取ります。そのため、メソッドリクエストにクエリ文字列パラメーターを追加して、統合リクエストの対応するクエリ文字列にマッピングする必要があります。

  6. GET メソッドの [メソッドの実行] ペインで [Method Request (メソッドリクエスト)] を選択し、[権限付与] の [AWS_IAM] を選択します。次に、[URL クエリ文字列パラメータ] セクションを展開し、[クエリ文字列の追加] を選択して、type および page という名前の 2 つのクエリ文字列パラメータを作成します。チェックマークアイコンを選択して、クエリ文字列パラメータを追加するごとに保存します。

    
                        GET on Pets メソッドリクエストにクエリ文字列を追加する

    これで、クライアントはリクエストを送信するときに、ペットのタイプとページ番号をクエリ文字列パラメーターとして指定できます。これらの入力パラメータは、バックエンドの PetStore ウェブサイトに入力値を転送するために、統合クエリ文字列パラメータにマッピングする必要があります。メソッドでは AWS_IAM を使用するため、メソッドを呼び出すにはリクエストに署名する必要があります。

  7. メソッドの [統合リクエスト] ページから、[URL クエリ文字列パラメータ] セクションを展開します。デフォルトでは、メソッドリクエストのクエリ文字列パラメーターは、同様の名前の統合リクエストのクエリ文字列パラメーターにマッピングされます。このデフォルトマッピングは、デモ API で動作します。これはそのままにしておきます。対応する統合リクエストパラメータに別のリクエストパラメータをマッピングするには、[マッピング元] 列に示すように、パラメータの鉛筆アイコンを選択し、マッピング式を編集します。別の統合リクエストパラメータにメソッドリクエストパラメータをマッピングするには、最初に削除アイコンを選択して既存の統合リクエストパラメータを削除し、[クエリ文字列の追加] を選択して新しい名前と目的のメソッドリクエストのパラメータマッピング式を選択します。

    
                        GET on Pets のクエリ文字列を、メソッドリクエストから統合リクエストにマッピングします

    シンプルなデモ API の作成が完了しました。これで API をテストできます。

  8. API Gateway コンソールを使用して API をテストするには、GET /pets メソッドの [メソッドの実行] ペインから [テスト] を選択します。[メソッドテスト] ペインで、[タイプ] および [ページ] クエリ文字列にそれぞれ「Dog」および「2」と入力し、[テスト] を選択します。

    
                        GET on Pets メソッドのテスト呼び出し

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

    
                          GET on Pets メソッドのテスト呼び出しの結果

    これでテストが成功したので、API をデプロイし、公開することができます。

  9. API をデプロイするには、API を選択し、[アクション] ドロップダウンメニューから [API のデプロイ] を選択します。

    
                        API のデプロイ

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

    
                        API のデプロイ (パート 2)

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

    GET メソッドがオープンアクセスをサポートする場合 (メソッドの許可タイプが NONE に設定されている場合など)、デフォルトのブラウザでメソッドを呼び出すには [呼び出し URL] リンクをダブルクリックしてください。必要なら、URL の呼び出しにクエリ文字列パラメーターを付けることもできます。AWS_IAM 許可タイプについては、「アクセスキー ID とシークレットアクセスキー」で説明しているとおり、AWS アカウントの IAM ユーザーに対応するキーでサインインする必要があります。これを行うには、署名バージョン 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 署名] を [タイプ] オプションで [認証] タブから選択し、リクエストを送信する前に以下の必須プロパティを指定します。

    • [アクセスキー] には、AWS IAM からプロビジョニングされた発信者の AWS アクセスキーを入力します。

    • [シークレットキー] には、最初にアクセスキーが作成されたときに AWS IAM からプロビジョニングされた発信者の AWS シークレットキーを入力します。

    • [AWS リージョン] には、呼び出し URL で指定された API ホスティング AWS リージョンを入力します。

    • [サービス名] には、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 エンドポイントに渡すことができるようにします。

注記

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

前提条件

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

  1. API GatewayAPI を構築する準備を整える のステップ (API Gateway アクセス権限の IAM ユーザーへの割り当てなど) を完了します。

  2. 少なくとも、「HTTP カスタム統合で API をビルドする」のステップに従って、API Gateway コンソールで MyDemoAPI という新しい API を作成します。

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

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

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

  1. [リソース] ペインで、1 つのスラッシュ (/) で表されるリソースルートを選択し、[アクション] ドロップダウンメニューから [リソースの作成] を選択します。

  2. [リソース名] に「petstorewalkthrough」を入力します。

  3. [リソースパス] でデフォルトの [/petstorewalkthrough] を選択した後、[リソースの作成] を選択します。

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

  1. [リソース] ペインで、[/petstorewalkthrough] を選択してから [リソースの作成] を選択します。

  2. [リソース名] に「pets」を入力します。

  3. [リソースパス] でデフォルトの [/petstorewalkthrough/pets] を選択した後、[リソースの作成] を選択します。

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

  1. [リソース] ペインで、[/petstorewalkthrough/pets] を選択してから [リソースの作成] を選択します。

  2. [リソース名] に「petId」を入力します。これは、HTTP エンドポイントの項目 ID にマッピングされます。

  3. [リソースパス] で、[petid] を「{petId}」で上書きします。petId は必ず中括弧 ({ }) で括り、「/petstorewalkthrough/pets/{petId}」と表示されるようにしてください。その後、[リソースの作成] を選択します。

    これは、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 にそれぞれマッピングします。

  1. [リソース] ペインで、[/petstorewalkthrough/pets] を選択して [アクション] メニューから [メソッドの作成] を選択し、メソッド名のドロップダウンリストから [/pets] の下の [GET] を選択します。

  2. [/petstorewalkthrough/pets - GET - Setup] ペインで、[統合タイプ] の [HTTP] を選択し、[HTTP メソッド] の [GET] を選択します。

  3. [エンドポイント URL] に「http://petstore-demo-endpoint.execute-api.com/petstore/pets」を入力します。

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

  5. [メソッドの実行] ペインで [メソッドリクエスト] を選択した後、[URL クエリ文字列パラメータ] の横の矢印を選択します。

  6. [クエリ文字列の追加] を選択します。

  7. [Name] に、「petType」と入力します。

    これは、API のメソッドリクエストの petType クエリパラメータを指定します。

  8. チェックマークアイコンを選択し、メソッドリクエスト URL クエリ文字列パラメータの作成を完了します。

  9. [クエリ文字列の追加] を再度選択します。

  10. [Name] に、「petsPage」と入力します。

    これは、API のメソッドリクエストの petsPage クエリパラメータを指定します。

  11. チェックマークアイコンを選択し、メソッドリクエスト URL クエリ文字列パラメーターの作成を完了します。

  12. [メソッドの実行]、[統合リクエスト] の順に選択した後、[URL クエリ文字列パラメータ] の横の矢印を選択します。

  13. method.request.querystring.petType からマッピングされた petType エントリおよび method.request.querystring.petsPage からマッピングされた petsPage エントリを削除します。このステップを実行するのは、エンドポイントが、リクエスト URL に対して、デフォルト値ではなく type および page という名前のクエリ文字列パラメータを必要とするためです。

  14. [クエリ文字列の追加] を選択します。

  15. [Name] に、「type」と入力します。これにより、統合リクエスト URL に必要なクエリ文字列パラメータが作成されます。

  16. [マッピング元] に「method.request.querystring.petType」と入力します。

    これは、メソッドリクエストの petType クエリパラメータを統合リクエストの type クエリパラメータにマッピングします。

  17. チェックマークアイコンを選択し、統合リクエスト URL クエリ文字列パラメータの作成を完了します。

  18. [クエリ文字列の追加] を再度選択します。

  19. [Name] に、「page」と入力します。これにより、統合リクエスト URL に必要なクエリ文字列パラメータが作成されます。

  20. [マッピング元] に「method.request.querystring.petsPage」と入力します。

    これは、メソッドリクエストの petsPage クエリパラメータを統合リクエストの page クエリパラメータにマッピングします。

  21. チェックマークアイコンを選択し、統合リクエスト URL クエリ文字列パラメーターの作成を完了します。

  22. [メソッドの実行] を選択します。[クライアント] ボックスで、[テスト] を選択します。[クエリ文字列] エリアの [petType] に「cat」と入力します。[petsPage] に「2」と入力します。

  23. [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 の統合リクエストのパスパラメータにマッピングします。

  1. [リソース] リストで [/petstorewalkthrough/pets/{petId}] を選択し、[アクション] ドロップダウンメニューから [メソッドの作成] を選択します。次に、メソッドの HTTP 動詞として [GET] を選択します。

  2. [Setup (セットアップ)] ペインで、[統合タイプ] に [HTTP] を選択し、[HTTP メソッド] に [GET] を選択します。

  3. [エンドポイント URL] に「http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}」を入力します。

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

  5. [メソッドの実行] ペインで [統合タイプ] を選択した後、[URL パスパラメータ] の横の矢印を選択します。

  6. [パスの追加] を選択します。

  7. [Name] に、「id」と入力します。

  8. [マッピング元] に「method.request.path.petId」と入力します。

    これは petId のメソッドリクエストのパスパラメータを、id の統合リクエストのパスパラメータにマッピングします。

  9. チェックマークアイコンを選択し、URL パスパラメーターの作成を完了します。

  10. [メソッドの実行] を選択し、[クライアント] ボックスで [テスト] を選択します。[パス] エリアの [petId] に「1」と入力します。

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

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

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

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

  • POST /petstorewalkthrough/pets のメソッドリクエストを作成し、POST http://petstore-demo-endpoint.execute-api.com/petstore/pets の統合リクエストと統合します。

  • メソッドリクエストの JSON ペイロードを、変更せずに統合リクエストペイロードに渡します。

  1. [リソース] ペインで [/petstorewalkthrough/pets] を選択し、[アクション] ドロップダウンメニューから [メソッドの作成] を選択します。次に、メソッドの HTTP 動詞として [POST] を選択します。

  2. [Setup (セットアップ)] ペインで、[統合タイプ] に [HTTP] を選択し、[HTTP メソッド] に [POST] を選択します。

  3. [エンドポイント URL] に「http://petstore-demo-endpoint.execute-api.com/petstore/pets」を入力します。

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

  5. [メソッドの実行] ペインの [クライアント] ボックスで、[テスト] を選択します。[リクエストボディ] を展開した後、次を入力します。

    { "type": "dog", "price": 249.99 }
  6. [Test] を選択します。成功すると、[レスポンス本文] に次の内容が表示されます。

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

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

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

API をデプロイする

  1. [リソース] ペインで、[API のデプロイ] を選択します。

  2. [デプロイされるステージ] で、[test] を選択します。

    注記

    入力は UTF-8 でエンコードされた (ローカライズされていない) テキストである必要があります。

  3. [デプロイメントの説明] に「Calling HTTP endpoint walkthrough」と入力します。

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

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

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

  1. [ステージエディター] ペインの [呼び出し URL] の横で、URL をクリップボードにコピーします。次のように表示されます。

    https://my-api-id.execute-api.region-id.amazonaws.com/test
  2. ブラウザーの新しいタブのアドレスボックスにこの URL を貼り付けます。

  3. 次のように /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 } ]
  4. petstorewalkthrough/pets の後に、「?petType=cat&petsPage=2」と入力します。次のように表示されます。

    https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets?petType=cat&petsPage=2
  5. URL を参照します。次の情報が表示されます。

    [ { "id": 4, "type": "cat", "price": 999.99 }, { "id": 5, "type": "cat", "price": 249.99 }, { "id": 6, "type": "cat", "price": 49.97 } ]
  6. petstorewalkthrough/pets の後の「?petType=cat&petsPage=2」を「/1」と置き換えます。次のように表示されます。

    https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets/1
  7. URL を参照します。次の情報が表示されます。

    { "id": 1, "type": "dog", "price": 249.99 }
  8. ウェブデバッギングプロキシツールまたは 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 呼び出しの出力データ形式を変換する方法を説明します。「レスポンスペイロードをマッピングする」を参照してください。

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

このウォークスルーでは、API Gateway でモデルとマッピングテンプレートを使用して API 呼び出しに対する出力スキーマを別のものに変換する方法について説明します。この演習は、「Amazon API Gateway で REST API の使用を開始する」および「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 から numbertype から 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 番目のモデルとマッピングテンプレートは、次のように idtypedescription に結合し、priceaskingPrice に名前変更する目的で使用されます。

[ { "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 番目のモデルとマッピングテンプレートは、次のように idtype、および pricelistings のセットに結合する目的で使用されます。

{ "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: モデルを作成する

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

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

  1. https://console.aws.amazon.com/apigateway で API Gateway コンソールにサインインします。

  2. [MyDemoAPI] が表示される場合は、[モデル] を選択します。

  3. [作成] を選択します。

  4. [モデル名] に「PetsModelNoFlatten」を入力します。

  5. [コンテンツタイプ] に「application/json」と入力します。

  6. [モデルの説明] に「Changes id to number, type to class, and price to salesPrice」を入力します。

  7. [モデルのスキーマ] に、次の 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" } } } }
  8. [モデルの作成] を選択します。

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

  1. [作成] を選択します。

  2. [モデル名] に「PetsModelFlattenSome」を入力します。

  3. [コンテンツタイプ] に「application/json」と入力します。

  4. [モデルの説明] に「Combines id and type into description, and changes price to askingPrice」を入力します。

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

    { "$schema": "http://json-schema.org/draft-04/schema#", "title": "PetsModelFlattenSome", "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "askingPrice": { "type": "number" } } } }
  6. [モデルの作成] を選択します。

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

  1. [作成] を選択します。

  2. [モデル名] に「PetsModelFlattenAll」を入力します。

  3. [コンテンツタイプ] に「application/json」と入力します。

  4. [モデルの説明] に「Combines id, type, and price into a set of listings」を入力します。

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

    { "$schema": "http://json-schema.org/draft-04/schema#", "title": "PetsModelFlattenAll", "type": "object", "properties": { "listings": { "type": "array", "items": { "type": "string" } } } }
  6. [モデルの作成] を選択します。

入力モデルを作成する

  1. [作成] を選択します。

  2. [モデル名] に「PetsLambdaModel」を入力します。

  3. [コンテンツタイプ] に「application/json」と入力します。

  4. [モデルの説明] に「GetPetsInfo model」を入力します。

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

    { "$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" } } } }
  6. [モデルの作成] を選択します。

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

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

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

  1. リンク リストで [リソース] を選択します。

  2. [リソース] ペインで、[/petstorewalkthrough] を選択してから [リソースの作成] を選択します。

  3. [リソース名] に「NoFlatten」を入力します。

  4. [リソースパス] でデフォルトの [/petstorewalkthrough/noflatten] を選択した後、[リソースの作成] を選択します。

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

  1. [リソース] ペインで、再度 [/petstorewalkthrough] を選択してから [リソースの作成] を選択します。

  2. [リソース名] に「FlattenSome」を入力します。

  3. [リソースパス] でデフォルトの [/petstorewalkthrough/flattensome] を選択した後、[リソースの作成] を選択します。

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

  1. [リソース] ペインで、再度 [/petstorewalkthrough] を選択してから [リソースの作成] を選択します。

  2. [リソース名] に「FlattenAll」を入力します。

  3. [リソースパス] でデフォルトの [/petstorewalkthrough/flattenall] を選択した後、[リソースの作成] を選択します。

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

  1. [リソース] ペインで、再度 [/petstorewalkthrough] を選択してから [リソースの作成] を選択します。

  2. [リソース名] に「LambdaFlattenSome」を入力します。

  3. [リソースパス] でデフォルトの [/petstorewalkthrough/lambdaflattensome] を選択した後、[リソースの作成] を選択します。

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

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

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

  1. [リソース] リストで、[/petstorewalkthrough/flattenall] を選択してから [メソッドの作成] を選択します。

  2. ドロップダウンリストから [GET] を選択し、チェックマークアイコンを選択して選択内容を保存します。

  3. 設定ペインで、[統合タイプ] として [HTTP]、[HTTP メソッド] として [GET] を選択し、[エンドポイント URL] に「http://petstore-demo-endpoint.execute-api.com/petstore/pets」と入力して [保存] を選択します。

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

  1. [リソース] リストで、[/petstorewalkthrough/lambdaflattensome] を選択してから [メソッドの作成] を選択します。

  2. ドロップダウンリストから [GET] を選択し、チェックマークを選択して選択内容を保存します。

  3. 設定ペインで、[統合タイプ] として [Lambda 関数] を選択し、[Lambda リージョン] ドロップダウンリストから GetPetsInfo Lambda 関数を作成したリージョンを選択します。次に、[Lambda 関数] として [GetPetsInfo] を選択して [保存] を選択します。Lambda 関数にアクセス権限を追加するよう求められたら、[OK] を選択します。

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

  1. [リソース] リストで、[/petstorewalkthrough/flattensome] を選択してから [メソッドの作成] を選択します。

  2. ドロップダウンリストから [GET] を選択し、チェックマークアイコンを選択して選択内容を保存します。

  3. 設定ペインで、[統合タイプ] として [HTTP]、[HTTP メソッド] として [GET] を選択し、[エンドポイント URL] に「http://petstore-demo-endpoint.execute-api.com/petstore/pets」と入力して [保存] を選択します。

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

  1. [リソース] リストで、[/petstorewalkthrough/noflatten] を選択してから [アクション]、[メソッドの作成] の順に選択します。

  2. ドロップダウンリストから [GET] を選択し、チェックマークアイコンを選択して選択内容を保存します。

  3. 設定ペインで、[統合タイプ] として [HTTP]、[HTTP メソッド] として [GET] を選択し、[エンドポイント URL] に「http://petstore-demo-endpoint.execute-api.com/petstore/pets」と入力して [保存] を選択します。

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

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

Lambda 関数を作成する

  1. https://console.aws.amazon.com/lambda/ にある AWS Lambda コンソールを開きます。

  2. 次のいずれかを行ってください。

    • ウェルカムページが表示される場合は、[今すぐ始める] を選択します。

    • [Lambda: 関数リスト] ページが表示される場合は、[Lambda 関数の作成] を選択します。

  3. [Name] に、「GetPetsInfo」と入力します。

  4. [説明] に「Gets information about pets」と入力します。

  5. [コードテンプレート] で、[なし] を選択します。

  6. 次のコードを入力します。

    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 ログに情報を書き込みます。event には、Lambda 関数への入力が含まれています。context には、呼び出しコンテキストが含まれています。callback は、結果を返します (Node.js 4.3 以降の場合)。Lambda 関数コードを書き込む方法の詳細については、AWS Lambda: 仕組みの「モデルのプログラミング」と AWS Lambda 開発者ガイドのサンプル演習を参照してください。

  7. [Handler name (ハンドラ名)] でデフォルトの index.handler を選択します。

  8. [ロール] で、Lambda 統合で API Gateway API をビルドする で作成した Lambda 実行ロールの APIGatewayLambdaExecRole を選択します。

  9. [Lambda 関数の作成] を選択します。

  10. 関数リストで、[GetPetsInfo] を選択して関数の詳細を表示します。

  11. この関数を作成した AWS リージョンをメモしておきます。これは、後で必要になります。

  12. ポップアップリストで、[関数の編集またはテスト] を選択します。

  13. [サンプルイベント] で、表示されたコードを次のように置換します。

    { }

    ヒント

    空の中括弧は、この Lambda 関数に入力値が存在しないことを意味しています。この関数では、ペット情報を含む JSON オブジェクトのみ返るため、ここではこれらのキーと値のペアは必要ありません。

  14. [呼び出し] を選択します。[実行結果] に、[{"id":1,"type":"dog","price":249.99},{"id":2,"type":"cat","price":124.99},{"id":3,"type":"fish","price":0.99}] が表示されます。また、同じ内容が CloudWatch Logs ログファイルにも書き込まれます。

  15. [Go to function list (関数リストに移動)] を選択します。

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

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

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

  1. API の [リソース] ツリーで、[/petstorewalkthrough/flattenall] ノードの下にある [GET] を選択します。

  2. [メソッドの実行] ペインで、[メソッドレスポンス] を選択してから [200] の横の矢印を選択します。

  3. [Response Models for 200 (200 のレスポンスモデル)] エリアで、[application/json] の鉛筆アイコンを選択し、メソッド出力のモデルの設定を開始します。[モデル] で [PetsModelFlattenAll] を選択し、チェックマークアイコンを選択して設定を保存します。

  4. [メソッドの実行]、[統合レスポンス] の順に選択してから、[200] の横の矢印を選択します。

  5. [本文マッピングテンプレート] セクションを展開し、[Content-Type] の [application/json] を選択します。

  6. [Generate template from model (モデルからテンプレートを生成)] で [PetsModelFlattenAll] を選択し、開始点として PetsModelFlattenAll モデルの後にマッピングテンプレートを表示します。

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

    #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 ] }
  8. [Save] を選択します。

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

    { "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 メソッドの統合を設定してテストするには

  1. API の [リソース] ツリーで、[/petstorewalkthrough/lambdaflattensome] ノードの下にある [GET] を選択します。

  2. [メソッドの実行] で、[メソッドレスポンス] を選択します。次に [200] の横にある矢印を選択してセクションを展開します。

  3. [Response Models for 200 (200 のレスポンスモデル)] エリアで、[application/json] のコンテンツタイプの行にある鉛筆アイコンを選択します。[モデル] で [PetsModelFlattenSome] を選択し、チェックマークアイコンを選択して選択項目を保存します。

  4. [メソッドの実行] に戻ります。[統合レスポンス] を選択し、[200] の横にある矢印を選択します。

  5. [本文マッピングテンプレート] セクションで、[Content-Type] の [application/json] を選択します。

  6. [テンプレートの生成] で [PetsModelFlattenSome] を選択して、このメソッドの出力のマッピングスクリプトテンプレートを表示します。

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

    #set($inputRoot = $input.path('$')) [ #foreach($elem in $inputRoot) { "description" : "Item $elem.id is a $elem.type.", "askingPrice" : $elem.price }#if($foreach.hasNext),#end #end ]
  8. [メソッドの実行] を選択し、[クライアント] ボックスで [テスト]、[テスト] の順に選択します。成功すると、[レスポンス本文] に次の内容が表示されます。

    [ { "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 メソッドの統合を設定してテストするには

  1. API の [リソース] ツリーで、[/petstorewalkthrough/flattensome] ノードの下にある [GET] を選択します。

  2. [メソッドの実行] ペインで、[メソッドレスポンス] を選択します。

  3. [200] の横にある矢印を選択します。

  4. [Response Models for 200 (200 のレスポンスモデル)] エリアで、[application/json] の鉛筆アイコンを選択します。[モデル] で [PetsModelFlattenSome] を選択し、チェックマークアイコンを選択して選択項目を保存します。

  5. [メソッドの実行] に戻って、[統合タイプ] を選択します。

  6. [200] の横にある矢印を選択してセクションを展開します。

  7. [本文マッピングテンプレート] エリアを展開します。[Content-Type] の [application/json] を選択します。[テンプレートの生成] で [PetsModelFlattenSome] を選択して、このメソッドの出力のマッピングスクリプトテンプレートを表示します。

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

    #set($inputRoot = $input.path('$')) [ #foreach($elem in $inputRoot) { "description": "Item $elem.id is a $elem.type.", "askingPrice": $elem.price }#if($foreach.hasNext),#end #end ]
  9. [Save] を選択します。

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

    [ { "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 メソッドの統合を設定してテストするには

  1. API の [リソース] ツリーで、[/petstorewalkthrough/noflatten] ノードの下にある [GET] を選択します。

  2. [メソッドの実行] ペインで、[メソッドレスポンス] を選択して [200] セクションを展開します。

  3. [Response Models for 200 (200 のレスポンスモデル)] エリアで、[application/json] の鉛筆アイコンを選択して、このメソッドのレスポンスモデルを更新します。

  4. [application/json] のコンテンツタイプのモデルとして [PetsModelNoFlatten] を選択し、チェックマークアイコンを選択して選択内容を保存します。

  5. [メソッドの実行]、[統合レスポンス] の順に選択してから、[200] の横の矢印を選択してセクションを展開します。

  6. [マッピングテンプレート] セクションを展開します。[Content-Type] の [application/json] を選択します。[テンプレートの生成] で [PetsModelNoFlatten] を選択して、このメソッドの出力のマッピングスクリプトテンプレートを表示します。

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

    #set($inputRoot = $input.path('$')) [ #foreach($elem in $inputRoot) { "number": $elem.id, "class": "$elem.type", "salesPrice": $elem.price }#if($foreach.hasNext),#end #end ]
  8. [Save] を選択します。

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

    [ { "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 をデプロイする

  1. [リソース] ペインで、[API のデプロイ] を選択します。

  2. [デプロイされるステージ] で、[test] を選択します。

  3. [デプロイメントの説明] に「Using models and mapping templates walkthrough」と入力します。

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

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

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

  1. [ステージエディター] ペインの [呼び出し URL] の横で、URL をクリップボードにコピーします。次のように表示されます。

    https://my-api-id.execute-api.region-id.amazonaws.com/test
  2. ブラウザーの新しいタブのアドレスボックスにこの URL を貼り付けます。

  3. 次のように /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 } ]
  4. petstorewalkthrough/ の後、noflattenflattensome と置き換えます。

  5. 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 } ]
  6. petstorewalkthrough/ の後、flattensomeflattenall と置き換えます。

  7. 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." ] }
  8. petstorewalkthrough/ の後、flattenalllambdaflattensome と置き換えます。

  9. 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 実行ロールを削除しないでください。

API Gateway は現在、機能しない API の非アクティブ化や削除をサポートしていません。

Lambda 関数を削除するには

  1. AWS マネジメントコンソール にサインインし、https://console.aws.amazon.com/lambda/ にある AWS Lambda コンソールを開きます。

  2. [Lambda: Function list (Lambda: 関数リスト)] ページの関数リストで、[GetPetsInfo] の横のボタンを選択した後、[アクション]、[削除] の順に選択します。プロンプトが表示されたら、再度 [削除] を選択します。

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

  1. https://console.aws.amazon.com/iam/ にある IAM コンソールを開きます。

  2. [詳細] エリアで、[ロール] を選択します。

  3. [APIGatewayLambdaExecRole] を選択した後、[ロールアクション]、[ロールの削除] の順に選択します。プロンプトが表示されたら、[Yes, Delete] を選択します。

  4. [詳細] エリアで、[ポリシー] を選択します。

  5. [APIGatewayLambdaExecPolicy]、[ポリシーアクション]、[削除] の順に選択します。プロンプトが表示されたら、[削除] を選択します。

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

次のステップ

次の演習では、API Gateway API を作成して AWS サービスにアクセスする方法を説明します。「AWS 統合で API Gateway API をビルドする」を参照してください。