API Gateway の HTTP プロキシ統合を設定する HTTP カスタム統合をセットアップする

API Gateway での REST API の HTTP 統合

HTTP プロキシ統合または HTTP カスタム統合を使用して、API メソッドを HTTP エンドポイントに統合できます。

API Gateway は、次のエンドポイントポートをサポートします。80、443、および 1024-65535 です。

プロキシ統合では、セットアップは簡単です。コンテンツのエンコーディングやキャッシングが不要な場合は、バックエンド要件に従って HTTP メソッドと HTTP エンドポイント URI を設定するだけで済みます。

カスタム統合では、セットアップは複雑になります。プロキシ統合のセットアップ手順に加えて、受信リクエストデータがどのように統合リクエストにマッピングされるか、統合レスポンスデータの結果がメソッド応答にどのようにマッピングされるかを指定する必要があります。

API Gateway の HTTP プロキシ統合を設定する

HTTP プロキシ統合タイプを使用してプロキシリソースをセットアップするには、greedy パスパラメータ (/parent/{proxy+} など) を使用して API リソースを作成し、このリソースを https://petstore-demo-endpoint.execute-api.com/petstore/{proxy} メソッドで HTTP バックエンドのエンドポイント (ANY など) と統合します。greedy パスパラメーターは、リソースパスの末尾にある必要があります。

非プロキシリソースと同様に、API Gateway コンソールを使用するか、OpenAPI 定義ファイルをインポートするか、API Gateway REST API を直接呼び出すことによって、プロキシリソースに HTTP プロキシ統合をセットアップできます。API Gateway コンソールを使用して HTTP 統合でプロキシリソースを設定する詳しい手順については、「チュートリアル: HTTP プロキシ統合を使用して REST API を作成する」を参照してください。

以下の OpenAPI 定義ファイルは、PetStore ウェブサイトに統合された API とプロキシリソースの例を示しています。

OpenAPI 3.0


{
   "openapi": "3.0.0",
   "info": {
      "version": "2016-09-12T23:19:28Z",
      "title": "PetStoreWithProxyResource"
   },
   "paths": {
      "/{proxy+}": {
         "x-amazon-apigateway-any-method": {
            "parameters": [
               {
                  "name": "proxy",
                  "in": "path",
                  "required": true,
                  "schema": {
                     "type": "string"
                  }
               }
            ],
            "responses": {},
            "x-amazon-apigateway-integration": {
               "responses": {
                  "default": {
                     "statusCode": "200"
                  }
               },
               "requestParameters": {
                  "integration.request.path.proxy": "method.request.path.proxy"
               },
               "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}",
               "passthroughBehavior": "when_no_match",
               "httpMethod": "ANY",
               "cacheNamespace": "rbftud",
               "cacheKeyParameters": [
                  "method.request.path.proxy"
               ],
               "type": "http_proxy"
            }
         }
      }
   },
   "servers": [
      {
         "url": "https://4z9giyi2c1.execute-api.us-east-1.amazonaws.com/{basePath}",
         "variables": {
            "basePath": {
              "default": "/test"
            }
         }
      }
   ]
}

OpenAPI 2.0


{
  "swagger": "2.0",
  "info": {
    "version": "2016-09-12T23:19:28Z",
    "title": "PetStoreWithProxyResource"
  },
  "host": "4z9giyi2c1.execute-api.us-east-1.amazonaws.com",
  "basePath": "/test",
  "schemes": [
    "https"
  ],
  "paths": {
    "/{proxy+}": {
      "x-amazon-apigateway-any-method": {
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "proxy",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {},
        "x-amazon-apigateway-integration": {
          "responses": {
            "default": {
              "statusCode": "200"
            }
          },
          "requestParameters": {
            "integration.request.path.proxy": "method.request.path.proxy"
          },
          "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}",
          "passthroughBehavior": "when_no_match",
          "httpMethod": "ANY",
          "cacheNamespace": "rbftud",
          "cacheKeyParameters": [
            "method.request.path.proxy"
          ],
          "type": "http_proxy"
        }
      }
    }
  }
}

この例では、キャッシュのキーは、プロキシリソースの method.request.path.proxy パスパラメータで宣言されます。これにより、API Gateway コンソールを使用して API を作成するときのデフォルト設定です。API ベースパス (/test、ステージに対応) はウェブサイトの PetStore ページ (/petstore) にマッピングされます。単一の統合リクエストは、API の greedy パス変数とキャッチオールの ANY メソッドを使用して、PetStore ウェブサイト全体をミラーリング処理します。以下の例に、このミラーリングを示しています。

ANY を GET、{proxy+} を pets に設定

フロントエンドから開始されたメソッドリクエスト:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1
```
バックエンドに送信された統合リクエスト:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1
```
ANY メソッドの実行時インスタンスとプロキシリソースの両方が有効です。呼び出しは 200 OK レスポンスと、バックエンドから返されたペットの最初のバッチが含まれるペイロードを返します。
ANY を GET、{proxy+} を pets?type=dog に設定
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets?type=dog HTTP/1.1
```
バックエンドに送信された統合リクエスト:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=dog HTTP/1.1
```
ANY メソッドの実行時インスタンスとプロキシリソースの両方が有効です。呼び出しは 200 OK レスポンスと、バックエンドから返された特定の犬の最初のバッチが含まれるペイロードを返します。
ANY を GET、{proxy+} を pets/{petId} に設定

フロントエンドから開始されたメソッドリクエスト:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/1 HTTP/1.1
```
バックエンドに送信された統合リクエスト:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/1 HTTP/1.1
```
ANY メソッドの実行時インスタンスとプロキシリソースの両方が有効です。呼び出しは 200 OK レスポンスと、バックエンドから返された特定のペットが含まれるペイロードを返します。
ANY を POST、{proxy+} を pets に設定

フロントエンドから開始されたメソッドリクエスト:
```
POST https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1
Content-Type: application/json
Content-Length: ...

{
  "type" : "dog",
  "price" : 1001.00
}
```
バックエンドに送信された統合リクエスト:
```
POST http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1
Content-Type: application/json
Content-Length: ...

{
  "type" : "dog",
  "price" : 1001.00
}
```
ANY メソッドの実行時インスタンスとプロキシリソースの両方が有効です。呼び出しは 200 OK レスポンスと、バックエンドから返された新しく作成したペットが含まれるペイロードを返します。
ANY を GET、{proxy+} を pets/cat に設定

フロントエンドから開始されたメソッドリクエスト:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/cat
```
バックエンドに送信された統合リクエスト:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/cat
```
プロキシリソースパスの実行時インスタンスが、バックエンドのエンドポイントに対応しておらず、結果としいて生成されるリクエストは無効です。その結果、400 Bad Request レスポンスが次のエラーメッセージとともに返されます。
```
{
  "errors": [
    {
      "key": "Pet2.type",
      "message": "Missing required field"
    },
    {
      "key": "Pet2.price",
      "message": "Missing required field"
    }
  ]
}
```
ANY を GET、{proxy+} を null に設定

フロントエンドから開始されたメソッドリクエスト:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test
```
バックエンドに送信された統合リクエスト:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets
```
対象のリソースはプロキシリソースの親ですが、ANY メソッドを実行時インスタンスは、そのリソースの API に定義されていません。その結果、この GET リクエストは、403 Forbidden レスポンスと、API Gateway から返された Missing Authentication Token エラーを返します。API が親リソース (ANY) で GET または / メソッドを公開している場合、呼び出しからは 404 Not Found レスポンスと、バックエンドから返された Cannot GET /petstore メッセージが返されます。

クライアントリクエストの場合、対象のエンドポイント URL が無効であるか、HTTP 動詞が有効であってもサポートされていない場合、バックエンドは 404 Not Found レスポンスを返します。サポートされていない HTTP メソッドの場合は、403 Forbidden レスポンスが返されます。

API Gateway の HTTP カスタム統合をセットアップする

HTTP カスタム統合により、API メソッドと API 統合の間を行き来するデータと行き来の方法をより詳細に制御できます。これにはデータマッピングを使用します。

メソッドリクエストのセットアップの一環として、Method リソースの requestParameters プロパティを設定します。これにより、クライアントからプロビジョニングされるメソッドリクエストパラメーターのうち、バックエンドにディスパッチされる前に統合リクエストパラメーターや該当する本文プロパティにマッピングされるものが宣言されます。次に、統合リクエストのセットアップの一環として、対応する Integration リソースで requestParameters プロパティを設定し、パラメータ間のマッピングを指定します。また、requestTemplates プロパティを設定し、サポートされているコンテンツタイプにつき 1 つずつ、マッピングテンプレートを指定します。マッピングテンプレートは、メソッドリクエストパラメーターや本文を統合リクエストボディにマッピングします。

同様に、メソッドレスポンスのセットアップの一環として、MethodResponse リソースで responseParameters プロパティを設定します。これにより、クライアントにディスパッチされるメソッドレスポンスパラメーターのうち、統合レスポンスパラメーターからまたはバックエンドから返された該当する本文プロパティからマッピングされるものが宣言されます。次に、統合レスポンスのセットアップの一環として、対応する IntegrationResponse リソースで responseParameters プロパティを設定し、パラメータからパラメータへのマッピングを指定します。また、responseTemplates マップを設定し、サポートされているコンテンツタイプごとにマッピングテンプレートを 1 つずつ指定します。マッピングテンプレートは、統合レスポンスパラメーターや統合レスポンス本文のプロパティをメソッドレスポンス本文にマッピングします。

マッピングテンプレートの設定の詳細については、「API Gateway での REST API のデータ変換」を参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

API Gateway で Lambda エラーを処理する

プライベート統合