コンソールにサインインする
Amazon API Gateway
開発者ガイド

AWS ドキュメント » Amazon API Gateway » 開発者ガイド » Amazon API Gateway の使用開始 » HTTP 統合で API Gateway API を構築する » HTTP カスタム統合で API をビルドする

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 リソースを作成するには、ルートを選択し、[Actions]、[Create Resource] の順に選択します。

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

    リソース Part B を作成する

  4. /pets リソースで GET メソッドを公開するには、[Actions] を選択し、[Create Method] を選択します。

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

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

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

    注記

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

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

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

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

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

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

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

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

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

    注記

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

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

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

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

  6. GET メソッドの [Method Execution] ペインで [Method Request] を選択し、[Authorization] の [AWS_IAM] を選択します。次に、[URL Query String Parameters] セクションを展開し、[Add query string] を選択して、type および page という名前の 2 つのクエリ文字列パラメーターを作成します。チェックマークアイコンを選択して、クエリ文字列パラメータを追加するごとに保存します。

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

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

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

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

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

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

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

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

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

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

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

    API のデプロイ

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

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

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

    GET メソッドがオープンアクセスをサポートする場合 (メソッドの許可タイプが NONE に設定されている場合など)、デフォルトのブラウザでメソッドを呼び出すには [URL の呼び出し] リンクをダブルクリックしてください。必要なら、URL の呼び出しにクエリ文字列パラメーターを付けることもできます。AWS_IAM 許可タイプについては、「アクセスキー ID とシークレットアクセスキー」で説明している通り、IAM アカウントの AWS ユーザーに対応するキーでサインインする必要があります。これを行うには、「署名バージョン 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 を作成して、これらの機能やその他の機能を公開します。タスクには次のものが含まれています。

  • http://petstore-demo-endpoint.execute-api.com/petstore/pets の HTTP エンドポイントのプロキシとして機能する https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/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. [Resources] ペインで、1 つのスラッシュ (/) で表されるリソースルートを選択し、[Actions] ドロップダウンメニューから [Create Resource] を選択します。

  2. [Resource Name] に「petstorewalkthrough」を入力します。

  3. [Resource Path] でデフォルトの [/petstorewalkthrough] を選択した後、[Create Resource] を選択します。

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

  1. [Resources] ペインで、[/petstorewalkthrough] を選択してから [Create Resource] を選択します。

  2. [Resource Name] に「pets」を入力します。

  3. [Resource Path] でデフォルトの [/petstorewalkthrough/pets] を選択した後、[Create Resource] を選択します。

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

  1. [Resources] ペインで、[/petstorewalkthrough/pets] を選択してから [Create Resource] を選択します。

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

  3. [Resource Path] で、[petid] を「{petId}」で上書きします。petId は中括弧 ({ }) で括り、「/petstorewalkthrough/pets/{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 にそれぞれマッピングします。

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

  2. [/petstorewalkthrough/pets - GET - Setup] ペインで、[Integration type] の [HTTP] を選択し、[HTTP method] の [GET] を選択します。

  3. [Endpoint URL] に「http://petstore-demo-endpoint.execute-api.com/petstore/pets」を入力します。

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

  5. [Method Execution] ペインで [Method Request] を選択した後、[URL Query String Parameters] の横の矢印を選択します。

  6. [Add query string] を選択します。

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

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

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

  9. [Add query string] を再度選択します。

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

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

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

  12. [Method Execution]、[Integration Request] の順に選択した後、[URL Query String Parameters] の横の矢印を選択します。

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

  14. [Add query string] を選択します。

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

  16. [Mapped from] に「method.request.querystring.petType」と入力します。

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

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

  18. [Add query string] を再度選択します。

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

  20. [Mapped from] に「method.request.querystring.petsPage」と入力します。

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

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

  22. [Method Execution] を選択します。[Client] ボックスで [TEST] を選択します。[Query Strings] エリアの [petType] に「cat」と入力します。[petsPage] に「2」と入力します。

  23. [Test] を選択します。成功すると、[Response Body] に次の内容が表示されます。 

    [
  {
    "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. [Resources] リストで、[/petstorewalkthrough/pets/{petId}] を選択して [Actions] ドロップダウンメニューから [Create Method] を選択し、メソッドの HTTP 動詞として [GET] を選択します。

  2. [Setup] ペインで、[Integration type] に [HTTP] を選択し、[HTTP method] に [GET] を選択します。

  3. [Endpoint URL] で、[http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}] を入力します。

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

  5. [Method Execution] ペインで [Integration Request] を選択した後、[URL Path Parameters] の横の矢印を選択します。

  6. [Add path] を選択します。

  7. [Name] に id を入力します。

  8. [Mapped from] に「method.request.path.petId」と入力します。

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

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

  10. [Method Execution] を選択し、[Client] ボックスで [TEST] を選択します。[Path] エリアの [petId] に「 1」と入力します。

  11. [Test] を選択します。成功すると、[Response Body] に次の内容が表示されます。 

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

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

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

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

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

  1. [Resources] ペインで、[/petstorewalkthrough/pets]を選択して [Actions] ドロップダウンメニューから [Create Method] を選択し、メソッドの HTTP 動詞として [POST] を選択します。

  2. [Setup] ペインで、[Integration type] に [HTTP] を選択し、[HTTP method] に [POST] を選択します。

  3. [Endpoint URL] に「http://petstore-demo-endpoint.execute-api.com/petstore/pets」を入力します。

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

  5. [Method Execution] ペインの [Client] ボックスで、[TEST] を選択します。[Request Body] を展開した後、次を入力します。 

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

  6. [Test] を選択します。成功すると、[Response Body] に次の内容が表示されます。 

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

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

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

API をデプロイする

  1. [Resources] ペインで、[Deploy API] を選択します。

  2. [Deployment stage] で、[test] を選択します。

    注記

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

  3. [Deployment description] に「HTTP エンドポイント呼び出しの演習」と入力します。

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

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

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

  1. [Stage Editor] ペインの [Invoke 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 の使用開始」および「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: モデルを作成する

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

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

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

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

  3. [Create] を選択します。

  4. [Model name] に「PetsModelNoFlatten」を入力します。

  5. [Content type] に「application/json」と入力します。

  6. [Model description] に「ID を番号に、タイプをクラスに、価格を販売価格に変更。」と入力します。

  7. [Model schema] に、次の 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. [Create model] を選択します。

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

  1. [Create] を選択します。

  2. [Model name] に「PetsModelFlattenSome」を入力します。

  3. [Content type] に「application/json」と入力します。

  4. [Model description] に「ID とタイプを説明に結合し、価格を希望価格に変更」と入力します。

  5. [Model schema] に、以下を入力します。 

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

  6. [Create model] を選択します。

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

  1. [Create] を選択します。

  2. [Model name] に「PetsModelFlattenAll」を入力します。

  3. [Content type] に「application/json」と入力します。

  4. [Model description] に、「ID、タイプ、価格をリストのセットに結合」と入力します。

  5. [Model schema] に、以下を入力します。 

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

  6. [Create model] を選択します。

入力モデルを作成する

  1. [Create] を選択します。

  2. [Model name] に「PetsLambdaModel」を入力します。

  3. [Content type] に「application/json」と入力します。

  4. [Model description] に、「GetPetsInfo モデル」を入力します。

  5. [Model schema] に、以下を入力します。 

    {
  "$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. [Create model] を選択します。

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

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

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

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

  2. [Resources] ペインで、[/petstorewalkthrough] を選択してから [Create Resource] を選択します。

  3. [Resource Name] に「NoFlatten」を入力します。

  4. [Resource Path] でデフォルトの [/petstorewalkthrough/noflatten] を選択した後、[Create Resource] を選択します。

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

  1. [Resources] ペインで、再度 [/petstorewalkthrough] を選択してから [Create Resource] を選択します。

  2. [Resource Name] に「FlattenSome」を入力します。

  3. [Resource Path] でデフォルトの [/petstorewalkthrough/flattensome] を選択した後、[Create Resource] を選択します。

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

  1. [Resources] ペインで、再度 [/petstorewalkthrough] を選択してから [Create Resource] を選択します。

  2. [Resource Name] に「FlattenAll」を入力します。

  3. [Resource Path] でデフォルトの [/petstorewalkthrough/flattenall] を選択した後、[Create Resource] を選択します。

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

  1. [Resources] ペインで、再度 [/petstorewalkthrough] を選択してから [Create Resource] を選択します。

  2. [Resource Name] に「LambdaFlattenSome」を入力します。

  3. [Resource Path] でデフォルトの [/petstorewalkthrough/lambdaflattensome] を選択した後、[Create Resource] を選択します。

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

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

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

  1. [Resources] リストで、[/petstorewalkthrough/flattenall] を選択してから [Create Method] を選択します。

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

  3. 設定ペインで、[Integration type] として [HTTP]、[HTTP method] として [GET] を選択し、[Endpoint URL] に「http://petstore-demo-endpoint.execute-api.com/petstore/pets」と入力して [Save] を選択します。

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

  1. [Resources] リストで、[/petstorewalkthrough/lambdaflattensome] を選択してから [Create Method] を選択します。

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

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

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

  1. [Resources] リストで、[/petstorewalkthrough/flattensome] を選択してから [Create Method] を選択します。

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

  3. 設定ペインで、[Integration type] として [HTTP]、[HTTP method] として [GET] を選択し、[Endpoint URL] に「http://petstore-demo-endpoint.execute-api.com/petstore/pets」と入力して [Save] を選択します。

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

  1. [Resources] リストで、[/petstorewalkthrough/noflatten] を選択してから [Actions]、[Create Method] の順に選択します。

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

  3. 設定ペインで、[Integration type] として [HTTP]、[HTTP method] として [GET] を選択し、[Endpoint URL] に「http://petstore-demo-endpoint.execute-api.com/petstore/pets」と入力して [Save] を選択します。

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

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

Lambda 関数を作成する

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

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

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

    • [Lambda: Function list] ページが表示される場合は、[Create a Lambda function] を選択します。

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

  4. [Description] に「ペット情報を取得。」と入力します。

  5. [Code template] で、[None] を選択します。

  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: How it Works の「モデルのプログラミング」とAWS Lambda 開発者ガイド のサンプル演習を参照してください。

  7. [Handler name] でデフォルトの index.handler を選択します。

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

  9. [Create Lambda function] を選択します。

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

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

  12. ポップアップリストで、[Edit or test function] を選択します。

  13. [Sample event] で、表示されたコードを次のように置換します。 

    {
                   
}

    ヒント

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

  14. [Invoke] を選択します。[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 ログにも書き込まれます。

  15. [Go to function list] を選択します。

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

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

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

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

  2. [Method Execution] ペインで、[Method Response] を選択してから [200] の横の矢印を選択します。

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

  4. [Method Execution]、[Integration Response] の順に選択してから、[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. [Method Execution] を選択し、[Client] ボックスで [TEST]、[Test] の順に選択します。成功すると、[Response Body] に次の内容が表示されます。 

    {
  "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 の [Resources] ツリーで、[/petstorewalkthrough/lambdaflattensome] ノードの下にある [GET] を選択します。

  2. [Method Execution] で、[Method Response] を選択します。次に [200] の横にある矢印を選択してセクションを展開します。

  3. [Response Models for 200] エリアで、[application/json] のコンテンツタイプの行にある鉛筆アイコンを選択します。[Models] で [PetsModelFlattenSome] を選択し、チェックマークアイコンを選択して選択内容を保存します。

  4. [Method Execution] に戻ります。[Integration Response] を選択し、[200] の横にある矢印を選択します。

  5. [Body Mapping Templates] セクションで、[Content-Type] の [application/json] を選択します。

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

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

    #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. [Method Execution] を選択し、[Client] ボックスで [TEST]、[Test] の順に選択します。成功すると、[Response Body] に次の内容が表示されます。 

    [
  {
    "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 の [Resources] ツリーで、[/petstorewalkthrough/flattensome] ノードの下にある [GET] を選択します。

  2. [Method Execution] ペインで、[Method Response] を選択します。

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

  4. [Response Models for 200] エリアで、[application/json] の鉛筆アイコンを選択します。[Models] で [PetsModelFlattenSome] を選択し、チェックマークアイコンを選択して選択内容を保存します。

  5. [Method Execution] に戻って、[Integration Response] を選択します。

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

  7. [本文マッピングテンプレート] エリアを展開します。[Content type] の [application/json] を選択します。[Generate template] で [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. [Method Execution] に戻って、[Client] ボックスの [TEST] を選択します。次に [Test] を選択します。成功すると、[Response Body] に次の内容が表示されます。 

    [
  {
    "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 の [Resources] ツリーで、[/petstorewalkthrough/noflatten] ノードの下にある [GET] を選択します。

  2. [Method Execution] ペインで、[Method Response] を選択して [200] セクションを展開します。

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

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

  5. [Method Execution]、[Integration Response] の順に選択してから、[200] の横の矢印を選択してセクションを展開します。

  6. [Mapping Templates] セクションを展開します。[Content type] の [application/json] を選択します。[Generate templates] で [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. [Method Execution] に戻って、[Client] ボックスで [TEST]、[Test] の順に選択します。成功すると、[Response Body] に次の内容が表示されます。 

    [
  {
    "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. [Resources] ペインで、[Deploy API] を選択します。

  2. [Deployment stage] で、[test] を選択します。

  3. [Deployment description] に、「モデルとマッピングテンプレートの演習」と入力します。

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

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

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

  1. [Stage Editor] ペインの [Invoke 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/ の後、noflatten を flattensome と置き換えます。

  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/ の後、flattensome を flattenall と置き換えます。

  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/ の後、flattenall を lambdaflattensome と置き換えます。

  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] ページの関数リストで、[GetPetsInfo] の横のボタンを選択した後、[Actions]、[Delete] の順に選択します。プロンプトが表示されたら、再度 [Delete] を選択します。

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

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

  2. [Details] エリアで、[Roles] を選択します。

  3. [APIGatewayLambdaExecRole] を選択した後、[Role Actions]、[Delete Role] の順に選択します。プロンプトが表示されたら、[Yes, Delete] を選択します。

  4. [Details] エリアで、[Policies] を選択します。

  5. [APIGatewayLambdaExecPolicy] を選択した後、[Policy Actions]、[Delete] の順に選択します。プロンプトが表示されたら、[Delete] を選択します。

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

次のステップ

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