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 バックエンドウェブサイトをアクセスするための以下の方法をサポートします。

  • 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 は MOCK 統合タイプの OPTIONS メソッドを通じて CORS アクセスをサポートします。API Gateway は、CORS アクセスをサポートする必須のヘッダーを返します。

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

サンプル API をインポート、構築してテストするには

  1. まだ行っていない場合は、「前提条件: API Gateway で API を構築する準備を整える」のステップを完了してください。

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

  3. 以下のいずれかを行います。

    1. これがアカウントの最初の API である場合、API Gateway コンソールのウェルカムページから [ご利用開始にあたって] を選択します。

      ヒントが表示された場合、[OK] を選択して閉じ、続行します。

    2. これが最初の API でない場合、API Gateway [API] ホームページから [API の作成] を選択します。

  4. [新しい API の作成] の [Examples API (サンプル API)] を選択し、[インポート] を選択して API サンプルを作成します。最初の API の場合、API Gateway コンソールはデフォルトでこのオプションで開始されます。

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

  5. 新しく作成された API は、次のように表示されます。

    [リソース] ペインには、作成された API の構造が、ノードのツリーとして表示されます。各リソースで定義された API メソッドがツリーの辺になります。リソースが選択されると、そのすべてのメソッドが、右側の [メソッド] ペインにリスト表示されます。各メソッドの下には、エンドポイント URL、認証タイプ、および API キーの要件を含む、メソッドの短い概要が表示されます。

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

    選択した (POST /pets) メソッドで結果として表示される [メソッドの実行] ペインには、メソッドの構造と動作の論理的なビューが表示されます。[Method Request] および [メソッドレスポンス] は、API のフロントエンド (クライアント) を含む API のインターフェイスであるのに対し、[統合リクエスト] および [統合レスポンス] は、バックエンド (http://petstore-demo-endpoint.execute-api.com/petstore/pets) を含む API のインターフェイスです。クライアントは、API を使用して [メソッドリクエスト] からバックエンド機能にアクセスします。API Gateway は、必要に応じてクライアントリクエストを [統合リクエスト] のバックエンドで許容される形式に変換してから、受信リクエストをバックエンドに転送します。変換されたリクエストは、統合リクエストと呼ばれます。同様に、バックエンドは API Gateway へのレスポンスを [統合レスポンス] で返します。次に、API Gateway はこれを [メソッドレスポンス] にルーティングしてから、クライアントに送信します。また、API Gateway は、必要に応じて、バックエンドのレスポンスデータをクライアントで予期される形式にマッピングします。

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

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

    API 開発者は、メソッドリクエストとメソッドレスポンスを設定して、API のフロントエンドのやり取りの動作を制御します。統合リクエストと統合レスポンスを設定して、API のバックエンド統合の動作を制御します。これにはメソッド間のデータマッピングと、対応する統合が関連します。このセットアップ方法について、「チュートリアル: HTTP 非プロキシ統合で API をビルドする」で説明しています。ここでは、エンドツーエンドのユーザー体験を提供するための API のテストについて説明します。

  7. (前の図に示した )[クライアント] の [テスト] を選択してテストを開始します。たとえば、POST /pets メソッドをテストするには、次のペイロード ({"type": "dog","price": 249.99}) を [Request Body (リクエストボディ)] に入力してから、[テスト] ボタンを選択します。

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

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

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

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

  9. サンプル API をデプロイするには、[PetStore] の API を選択し、続いて [アクション] メニューから [API のデプロイ] を選択します。

    これは API の最初のデプロイであるため、[Deploy API のデプロイ] の [デプロイされるステージ] で、[新しいステージ] を選択します。[ステージ名] に名前を入力します (test など)。オプションで、[ステージの説明] および [デプロイの説明] に説明を入力します。[デプロイ] を選択します。

    結果として表示される [ステージエディター] ペインで、[呼び出し URL] に、API の GET / メソッドリクエストを呼び出す URL が表示されます。

  10. [ステージエディター] で、[呼び出し URL] リンクに従ってブラウザで GET / メソッドを送信します。その結果、正常なレスポンスとして、統合レスポンスのマッピングテンプレートから生成された結果が返されます。

  11. [ステージ] ナビゲーションペインで、[テスト] ステージを展開し、[/pets/{petId}] で [GET] を選択して、[呼び出し 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 非プロキシ統合で API をビルドする」を参照してください。