チュートリアル: HTTP プロキシ統合を使用して REST API をビルドする - Amazon API Gateway

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

HTTP プロキシ統合は、API を構築するシンプルかつパワフルで、汎用性のあるメカニズムです。これにより、単一の API メソッドのセットアップを合理化することで、ウェブアプリケーションから、統合された HTTP エンドポイントの複数のリソースや機能 (例: ウェブサイト全体) にアクセスすることができます。HTTP プロキシ統合で、API Gateway はクライアントが送信したメソッドリクエストをバックエンドに渡します。渡されるリクエストデータには、リクエストヘッダー、クエリ文字列パラメータ、URL パス変数、ペイロードなどが含まれます。バックエンド HTTP エンドポイントまたはウェブサーバーでは、受信リクエストデータを解析して、返すレスポンスを決定します。HTTP プロキシ統合では、API メソッドの設定後に API Gateway からの介入なしで、クライアントとバックエンドが直接やり取りできます (「Amazon API Gateway に関する重要な注意点」に示されているサポートされない文字など、既知の問題が発生した場合を除く)。

また、網羅的なプロキシリソース ({proxy+}) と、多様な状況に対応できる HTTP メソッドの ANY 動詞を使用すれば、HTTP プロキシ統合を使用して、単一の API メソッドの API を作成することができます。このメソッドでは、ウェブサイトのパブリックにアクセス可能な HTTP リソースとオペレーションのセット全体を公開します。バックエンドのウェブサーバーでパブリックアクセス用のリソースが他にも開かれると、クライアントは、同じ API をセットアップしてこれらの新しいリソースを使用できます。このようにするために、ウェブサイトデベロッパーは、適用可能な新しいリソースやオペレーションについて、クライアントデベロッパーに明確に伝える必要があります。

以下のチュートリアルでは、HTTP プロキシ統合の概要について説明します。このチュートリアルでは、API Gateway コンソールを使用して API を作成し、汎用的なプロキシリソース {proxy+} から PetStore ウェブサイトと統合し、ANY の HTTP メソッドのプレースホルダーを作成します。

API Gateway コンソールを使用して HTTP プロキシ統合で API を作成する

次の手順では、API Gateway コンソールを使用して、HTTP バックエンド用のプロキシリソースで API を作成してテストする方法を説明します。HTTP バックエンドは、PetStorehttp://petstore-demo-endpoint.execute-api.com/petstore/pets ウェブサイト (チュートリアル: HTTP 非プロキシ統合を使用して REST API をビルドする) です。ここでは、スクリーンショットを視覚的な補助として使用し、API Gateway UI 要素を示します。はじめて API Gateway コンソールを使用して API を作成する場合は、まず該当セクションに従って行います。

API を作成するには
  1. API Gateway コンソール (https://console.aws.amazon.com/apigateway) にサインインします。

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

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

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

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

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

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

このステップでは、{proxy+} のプロキシリソースパスを作成します。これは、http://petstore-demo-endpoint.execute-api.com/ のいずれかのバックエンドエンドポイントのプレースホルダーです。たとえば、petstorepetstore/petspetstore/pets/{petId} のようになります。API Gateway は、{proxy+} リソースの作成時に ANY メソッドを作成し、ランタイムに、サポートされている HTTP 動詞のいずれかのプレースホルダーとして機能します。

/{proxy+} リソースを作成するには
  1. API を選択します。

  2. メインナビゲーションペインで、[リソース] を選択します。

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

  4. [プロキシのリソース] を有効にします。

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

  6. [リソース名] に「{proxy+}」と入力します。

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

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

    
                    子リソースを作成します。

このステップでは、プロキシ統合を使用して、ANY メソッドをバックエンド HTTP エンドポイントと統合します。プロキシ統合の場合、API Gateway はクライアントから送信されたメソッドリクエストを API Gateway の介入なしでバックエンドに渡します。

ANY メソッドを作成するには
  1. /{proxy+} リソースを選択します。

  2. ANY メソッドを選択します。

  3. 警告シンボルの下にある [統合を編集] を選択します。統合のないメソッドを含む API はデプロイできません。

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

  5. [HTTP プロキシ統合] を有効にします。

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

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

  8. [Save (保存)] を選択します。

HTTP プロキシ統合を使用して API をテストする

特定のクライアントリクエストが成功するかは次に応じて異なります。

  • バックエンドで、対応するバックエンドポイントエンドポイントが利用可能になった場合、または利用可能である場合は、必要なアクセス許可が付与されます。

  • クライアントから適切に入力が行われる場合。

たとえば、ここで使用した PetStore API には、/petstore リソースは表示されません。そのため、取得するレスポンス (404 Resource Not Found) には、エラーメッセージ (Cannot GET /petstore) が含まれます。

さらに、クライアントは、結果を正しく処理するために、バックエンドの出力形式を処理できるようにする必要があります。クライアントとバックエンドの間のやり取りを容易にするために API Gateway が仲介することはありません。

プロキシリソースを通じた HTTP プロキシ統合を使用して PetStore ウェブサイトと統合された API をテストするには
  1. [テスト] タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。

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

  3. [パス][プロキシ] に、「petstore/pets」と入力します。

  4. [クエリ文字列] に「type=fish」と入力します。

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

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

    バックエンドのウェブサイトは、GET /petstore/pets?type=fish リクエストをサポートするため、次のような成功のレスポンスを返します。

    [ { "id": 1, "type": "fish", "price": 249.99 }, { "id": 2, "type": "fish", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ]

    GET /petstore を呼び出そうとすると、404 レスポンスとエラーメッセージ Cannot GET /petstore が返されます。これは、指定したオペレーションがバックエンドでサポートされていないためです。GET /petstore/pets/1 を呼び出すと、リクエストは PetStore ウェブサイトでサポートされているため、200 OK レスポンスと次のペイロードが返されます。

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

ブラウザを使用して API をテストすることもできます。API をデプロイし、それをステージに関連付けて API の呼び出し URL を作成します。

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

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

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

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

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

これで、クライアントは API を呼び出すことができます。

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

  2. API を選択します。

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

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

    API の呼び出し URL をウェブブラウザに入力します。

    URL は次のようになります。https://abcdef123.execute-api.us-east-2.amazonaws.com/test/petstore/pets?type=fish

    ブラウザが API にGETリクエストを送信します。

  5. この結果は、API Gateway コンソールで [テスト] を使用したときに返される結果と同じであることが必要です。