メニュー
Amazon API Gateway
開発者ガイド

例から API Gateway API を構築する

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

サンプル API は、クライアントがhttp://petstore-demo-endpoint.execute-api.com/petstoreの 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: バックエンド /petstore/pets リソースと統合されている API の /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 を構築してテストするには

  1. API Gateway コンソールにサインインします。

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

    1. これがアカウントの最初の API である場合、API Gateway コンソールのウェルカムページから [Get Started] を選択します。

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

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

  3. [Create new API] の [Examples API] を選択し、[Import] を選択して API サンプルを作成します。最初の API の場合、API Gateway コンソールはデフォルトでこのオプションで開始されます。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    これは API の最初のデプロイであるため、[Deploy API] の [Deployment stage] で、[[New Stage]] を選択します。[Stage name] に名前を入力します (test など)。オプションで、[Stage description] および [Deployment description] に説明を入力します。[Deploy] を選択します。

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

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

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

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

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

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

サンプル API を通じて、API Gateway で API を作成する基本的なワークフローを理解しました。手順は以下に要約されます。

  1. AWS アカウントで API を RestApi リソースとして作成します。

  2. Resource リソースを、新しく作成した API のリソース階層に追加します。

  3. ResourceMethod リソースを作成します。API メソッドは、クライアントと API Gateway 間のプログラミングインターフェイスを表しています。

  4. メソッドとバックエンドエンドポイントの統合をセットアップします。統合は、API Gateway とバックエンドエンドポイント間のインターフェイスを表します。

ユーザーが API を介してバックエンドサービスにアクセスすると、クライアントは API Gateway に HTTP リクエストを送信します。この送信は、リクエストがバックエンドに到達する前に、Method Request、それから Integration Request に通します。バックエンドは API Gateway に応答を返します。レスポンスは、クライアントがレスポンスを受信する前に、Integration Response から Method Response に渡されます。このサンプル API で示されている MOCK 統合は、API Gateway によるリクエストまたはレスポンスの最も単純な前処理と後処理のケースかも知れません。これ以外のケースは、本ガイドの他の箇所で取り上げています。

次に、プロキシ統合で、より高速で強力な API を構築してテストする方法の学習に進みます。

以下の資料も参照してください。

API Gateway カスタムオーソライザーの使用API のデプロイ