チュートリアル: サンプルをインポートして REST API を作成する - Amazon API Gateway

チュートリアル: サンプルをインポートして REST API を作成する

PetStore ウェブサイトの HTTP 統合を使用してシンプルな REST API を作成、テストするために Amazon API Gateway コンソールを使用できます。API 定義は OpenAPI 2.0 ファイルとして事前設定されています。API 定義を API Gateway にロードしたあと、API Gateway コンソールを使用して API の基本構造を確認するか、単純に API をデプロイしてテストすることができます。

PetStore サンプル API では、クライアントがhttp://petstore-demo-endpoint.execute-api.com/petstore/petsの HTTP バックエンドウェブサイトをアクセスするための以下の方法をサポートします。

注記

このチュートリアルでは、HTTP エンドポイントを例として使用します。独自の API を作成する場合、HTTP 統合には HTTPS エンドポイントを使用することをお勧めします。

  • GET /: どのバックエンドエンドポイントとも統合されていない API のルートリソースへの読み取りアクセス。API Gateway は PetStore ウェブサイトの概要で応答します。これは MOCK 統合タイプの例です。

  • GET /pets: 同様の名前のバックエンド /pets リソースと統合されている API の /pets リソースへの読み取りアクセス。バックエンドは PetStore で利用可能なペットのページを返します。これは HTTP 統合タイプの例です。統合エンドポイントの URL はhttp://petstore-demo-endpoint.execute-api.com/petstore/pets です。

  • POST /pets: バックエンド /pets リソースと統合されている API の /petstore/pets リソースへの書き込みアクセス。正しいリクエストを受信すると、バックエンドは指定されたペットを PetStore に追加し、結果を呼び出し元に返します。統合は HTTP でもあります。

  • GET /pets/{petId}: 受信リクエスト URL のパス変数として指定される petId 値によって識別されるペットへの読み取りアクセス。このメソッドには HTTP 統合タイプもあります。バックエンドは PetStore で見つかった指定されたペットを返します。バックエンド HTTP エンドポイントの URL は http://petstore-demo-endpoint.execute-api.com/petstore/pets/n で、n は照会されたペットの識別子としての整数です。

API は OPTIONS 統合タイプの MOCK メソッドを通じて CORS アクセスをサポートします。API Gateway は、CORS アクセスをサポートする必要なヘッダーを返します。

次の手順では、API Gateway コンソールを使用して、サンプルから API を作成してテストする方法を説明します。

サンプル API をインポート、構築してテストするには
  1. https://console.aws.amazon.com/apigateway で API Gateway コンソールにサインインします。

  2. 次のいずれかを行います。

    • 最初の API を作成するには、[REST API][ビルド] を選択します。

    • 以前に API を作成した場合は、[API の作成] を選択し、[REST API][ビルド] を選択します。

  3. [REST API の作成][サンプル API] を選択し、[API の作成] を選択して API サンプルを作成します。

    [API の作成] を選択する前に、OpenAPI 定義ファイルを下へスクロールして、この API サンプルの詳細について参照できます。

  4. メインナビゲーションペインで、[リソース] を選択します。新しく作成された API は、次のように表示されます。

    [リソース] ペインには、作成された API の構造が、ノードのツリーとして表示されます。各リソースで定義された API メソッドがツリーの辺になります。リソースが選択されると、そのすべてのメソッドが、右側の [メソッド] テーブルにリスト表示されます。各メソッドには、メソッドタイプ、統合タイプ、認証タイプ、API キー要件が表示されます。

  5. メソッドの詳細を表示する、そのセットアップを変更する、またはメソッド呼び出しをテストするには、メソッドリストまたはリソースツリーからメソッド名を選択します。ここでは、図として POST /pets メソッドを選択します。

    表示される [メソッド実行] ペインには、選択した (POST /pets) メソッドの構造と動作が論理的に表示されます。

    [メソッドリクエスト][メソッドレスポンス] は、API のフロントエンドとのインターフェイスを表し、[統合リクエスト][統合レスポンス] は API とバックエンドとのインターフェイスを表します。

    クライアントは、API を使用して [メソッドリクエスト] からバックエンド機能にアクセスします。API Gateway は、必要に応じてクライアントリクエストを [統合リクエスト] のバックエンドで許容される形式に変換してから、受信リクエストをバックエンドに転送します。変換されたリクエストは、統合リクエストと呼ばれます。同様に、バックエンドは、[統合レスポンス] で API Gateway にレスポンスを返します。API Gateway は、そのレスポンスを [Method Response (メソッドレスポンス)] にルーティングした後でクライアントに送信します。また、API Gateway は、必要に応じて、バックエンドのレスポンスデータをクライアントで予期される形式にマッピングします。

    API リソースの POST メソッドで、メソッドリクエストのペイロードが統合リクエストのペイロードと同じ形式の場合、メソッドリクエストペイロードは、変更せずに統合リクエストに渡すことができます。

    GET / メソッドリクエストは MOCK 統合タイプを使用し、実際のバックエンドのいずれのエンドポイントにも関連付けられません。対応する [統合レスポンス] は、静的な HTML ページを返すように設定されています。メソッドが呼び出されると、API Gateway はリクエストを受け取り、ただちに [メソッドレスポンス] で、クライアントに設定済みの統合レスポンスを返します。Mock 統合を使用して、バックエンドのエンドポイントを必要とすることなく API をテストできます。また、これを使用して、レスポンス本文マッピングテンプレートから生成されたローカルレスポンスを送信することもできます。

    API デベロッパーは、メソッドリクエストとメソッドレスポンスを設定して、API のフロントエンドのやり取りの動作を制御します。統合リクエストと統合レスポンスを設定して、API のバックエンド統合の動作を制御します。これにはメソッド間のデータマッピングと、対応する統合が関連します。ここでは、エンドツーエンドのユーザー体験を提供するための API のテストについて説明します。

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

  7. たとえば、POST /pets メソッドをテストするには、次のペイロード ({"type": "dog","price": 249.99}) を [リクエスト本文] に入力してから、[テスト] を選択します。

    入力では、PetStore ウェブサイトでペットのリストに追加するペットの属性を指定します。

  8. 結果は次のように表示されます。

    出力の [ログ] エントリは、メソッドリクエストから統合リクエストへの状態の変化と、統合レスポンスからメソッドレスポンスへの状態の変化を示します。これは、リクエストが失敗する原因となるマッピングエラーのトラブルシューティングに役立つ場合があります。この例では、マッピングは適用されません。メソッドリクエストのペイロードは、統合リクエストでバックエンドに渡されます。また、同様に、バックエンドレスポンスは、統合レスポンスからメソッドレスポンスに渡されます。

    API Gateway test-invoke-request 機能以外のクライアントを使用して API をテストするには、最初に API をステージにデプロイする必要があります。

  9. サンプル API をデプロイするには、[API のデプロイ] を選択します。

  10. [ステージ] には、[新規ステージ] を選択し、test を入力します。

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

  12. デプロイを選択します。

  13. 結果として表示される [ステージ][ステージの詳細] で、[URL を呼び出す] には API の GET / メソッドリクエストを呼び出す URL が表示されます。

    REST API を作成すると、コンソールに API の呼び出し URL が表示されます。
  14. コピーアイコンを選択して API の呼び出し URL をコピーし、Web ブラウザに API の呼び出し URL を入力します。その結果、正常なレスポンスとして、統合レスポンスのマッピングテンプレートから生成された結果が返されます。

  15. [Stages] (ステージ) ナビゲーションペインで、[test] (テスト) ステージを展開し、/pets/{petId} で [GET] を選択してから、[Invoke URL] (呼び出し URL) の値 https://api-id.execute-api.region.amazonaws.com/test/pets/{petId} をコピーします。{petId} はパス変数を表します。

    (前のステップで取得した) [呼び出し URL] の値をブラウザのアドレスバーに貼り付け、{petId}1 などで置き換え、Enter キーを押してリクエストを送信します。200 OK レスポンスが、次の JSON ペイロードとともに返されます。

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

    このように API メソッドを呼び出すことは可能です。これは、その Authorization タイプが NONE に設定されているためです。AWS_IAM 認証が使用されている場合、署名バージョン 4 (SigV4) のプロトコルを使用してリクエストに署名します。このようなリクエストの例については、「チュートリアル: HTTP 非プロキシ統合を使用して REST API をビルドする」を参照してください。