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

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

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

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

このステップでは、空の API を作成します。次の手順では、非プロキシ HTTP 統合を使用して API を http://petstore-demo-endpoint.execute-api.com/petstore/pets エンドポイントに接続するためのリソースとメソッドを作成します。

API を作成する方法

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

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

   API Gateway を使用するのが初めてではない場合、[Create API] (API を作成)を選択します。[REST API] で、[構築] を選択します。

3. [API 名] に「HTTPNonProxyAPI」と入力します。

4. (オプション) [説明] に説明を入力します。

5. [API エンドポイントタイプ] を [リージョン別] に設定したままにします。

6. [IP アドレスの種類] には [IPv4] を選択します。

7. API の作成 を選択します。

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

/pets リソースを作成するには

1. [リソースの作成] を選択します。

2. [プロキシのリソース] はオフのままにします。

3. [リソースパス] は / のままにします。

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

5. [CORS (Cross Origin Resource Sharing)] はオフのままにします。

6. [リソースの作成] を選択します。

このステップでは、/pets リソースで GET メソッドを作成します。GET メソッドは http://petstore-demo-endpoint.execute-api.com/petstore/pets ウェブサイトと統合されています。API メソッドの他のオプションには、以下があります。

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

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

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

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

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

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

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

/pets リソースで GET メソッドを作成するには

1. /pets リソースを選択します。

2. [メソッドの作成] を選択します。

3. [メソッドタイプ] には、GET を選択します。

4. [統合タイプ] で、[HTTP 統合] を選択します。

5. [HTTP プロキシ統合] はオフのままにします。

6. [HTTP メソッド] で、[GET] を選択します。

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

   PetStore ウェブサイトでは、特定のページでペットの種類 (「Dog」や「Cat」など) ごとに、Pet 項目のリストを取得できます。

8. [コンテンツの処理] で、[パススルー] を選択します。

9. [URL クエリ文字列パラメータ] を選択します。

   PetStore ウェブサイトでは、type および page クエリ文字列パラメータを使用して入力を受け取ります。メソッドリクエストにクエリ文字列パラメータを追加して、統合リクエストの対応するクエリ文字列パラメータにマッピングします。

10. クエリ文字列パラメータを追加するには、次の操作を行います。

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

    2. [名前] に「type」と入力します。

    3. [必須] と [キャッシュ] はオフのままにしておきます。

    前の手順を繰り返し、page という名前で追加のクエリ文字列を作成します。

11. [メソッドの作成] を選択します。

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

入力パラメータを統合リクエストにマッピングするには

1. [統合リクエスト] タブの [統合リクエストの設定] で、[編集] を選択します。

2. [URL クエリ文字列パラメータ] を選択し、次の操作を行います。

   1. [クエリ文字列パラメータを追加] を選択します。

   2. [名前] にtypeと入力してください。

   3. [マッピング元] として「method.request.querystring.type」と入力します。

   4. [キャッシュ] はオフのままにします。

   5. [クエリ文字列パラメータを追加] を選択します。

   6. [名前] にpageと入力してください。

   7. [マッピング元] として「method.request.querystring.page」と入力します。

   8. [キャッシュ] はオフのままにします。

3. [保存] を選択します。

API をテストするには

1. [テスト] タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。

2. [クエリ文字列] に「type=Dog&page=2」と入力します

3. [テスト] を選択します。

   結果は次の例のようになります。

   

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

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

5. [ステージ] で [新規ステージ] を選択します。

6. [Stage name (ステージ名)] に Prod と入力します。

7. (オプション) [説明] に説明を入力します。

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

9. (オプション) [ステージの詳細] の [呼び出し URL] で、コピーアイコンを選択して API の呼び出し URL をコピーします。Postman や cURL のようなツールでこれを使用して API をテストできます。

SDK を使用してクライアントを作成する場合は、SDK で公開されたメソッドを呼び出して、リクエストに署名できます。実装の詳細については、選択する AWS SDK を参照してください。

注記

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

(オプション) リクエストパラメータをマッピングする

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

このチュートリアルでは、API のメソッドリクエスト の {petId} のパスパラメータを作成し、項目 ID を指定します。次に、これを統合リクエスト URL で {id} パスパラメータにマッピングし、リクエストを HTTP エンドポイントに送信します。

注記

大文字の代わりに小文字を使用するなど、大文字と小文字を間違えて入力すると、チュートリアルの後半でエラーが発生します。

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

このステップでは、パスパラメータ {petId} を使用してリソースを作成します。

{petId} リソースを作成するには

1. /pets リソースを選択し、[リソースを作成] を選択します。

2. [プロキシのリソース] はオフのままにします。

3. [リソースパス] として、[/pets/]を選択します。

4. [リソース名] に {petId} と入力します。

   petId の周りに波括弧 ({ }) を使用し、/pets/{petId} と表示されるようにします。

5. [CORS (Cross Origin Resource Sharing)] はオフのままにします。

6. [リソースの作成] を選択します。

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

このステップでは、{petId} パスパラメータを使用して GET メソッドを作成します。

GET メソッドをセットアップするには

1. /{petId} リソースを選択し、[メソッドを作成] を選択します。

2. [メソッドタイプ] には、GET を選択します。

3. [統合タイプ] で、[HTTP 統合] を選択します。

4. [HTTP プロキシ統合] はオフのままにします。

5. [HTTP メソッド] で、[GET] を選択します。

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

7. [コンテンツの処理] で、[パススルー] を選択します。

8. [デフォルトタイムアウト] はオンのままにします。

9. [メソッドの作成] を選択します。

次に、先ほど作成した {petId} パスパラメータを、統合リクエストの HTTP エンドポイント URL の {id} パスパラメータにマッピングします。HTTP エンドポイント URL は http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id} でした。

{petId} パスパラメータをマッピングするには

1. [統合リクエスト] タブの [統合リクエストの設定] で、[編集] を選択します。

2. [URL パスパラメータ] を選択します。

3. API Gateway は petId という名前の統合リクエストのパスパラメータを作成しますが、このパスパラメータはバックエンド統合として設定した HTTP エンドポイント URL には無効です。HTTP エンドポイントはパスパラメータとして {id} を使用します。[名前] で、petId を削除し、id を入力します。

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

4. [保存] を選択します。

次にメソッドをテストします。

メソッドをテストするには

1. [テスト] タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。

2. petId の [パス] に、「4」と入力します。

3. [Test (テスト)] を選択します。

   成功すると、[レスポンス本文] に次の内容が表示されます。

   {
     "id": 4,
     "type": "bird",
     "price": 999.99
   }

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

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

API をデプロイする

1. [API のデプロイ] を選択します。

2. [ステージ] で [実稼働] を選択します。

3. (オプション) [説明] に説明を入力します。

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

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

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

1. メインナビゲーションペインで、[ステージ] を選択します。

2. [ステージの詳細] で、コピーアイコンを選択して API の呼び出し URL をコピーします。

   次のように表示されます。

   https://my-api-id.execute-api.region-id.amazonaws.com/prod

3. リクエストを送信する前に、この URL をブラウザの新しいタブのアドレスボックスに入力し、/pets/4 を URL に付加します。

4. ブラウザは以下を返します。

   {
     "id": 4,
     "type": "bird",
     "price": 999.99
   }

次のステップ

リクエストの検証の有効化、データの変換、カスタムゲートウェイレスポンスの作成により、API をさらにカスタマイズできます。

API をカスタマイズするその他の方法については、以下のチュートリアルを参照してください。

• リクエスト検証の詳細については、「API Gateway で基本的なリクエストの検証を設定する」を参照してください。

• リクエストとレスポンスのペイロードを変換する方法の詳細については、「チュートリアル: AWS サービスへの統合のための統合リクエストとレスポンスを変更する」を参照してください。

• カスタムゲートウェイレスポンスの作成方法については、「API Gateway コンソールを使用して REST API のゲートウェイレスポンスをセットアップする」を参照してください。