针对 API Gateway 中的 REST API 的 HTTP 集成 - Amazon API Gateway

针对 API Gateway 中的 REST API 的 HTTP 集成

您可以使用 HTTP 代理集成或 HTTP 自定义集成将 API 方法与 HTTP 终端节点进行集成。

API Gateway 支持以下终端节点端口:80、443 和 1024-65535。

借助代理集成,进行设置非常简单。如果不考虑内容编码或缓存,则只需根据后端要求设置 HTTP 方法和 HTTP 终端节点 URI。

借助自定义集成,进行设置更为复杂。除了执行代理集成设置步骤,还需要指定如何将传入请求数据映射到集成请求以及如何将生成的集成响应数据映射到方法响应。

在 API Gateway 中设置 HTTP 代理集成

要设置具有 HTTP 代理集成类型的代理资源,请创建一个具有“贪婪”路径参数(例如,/parent/{proxy+})的 API 资源,并将该资源与 https://petstore-demo-endpoint.execute-api.com/petstore/{proxy} 方法上的 HTTP 后端终端节点(例如,ANY)集成。“贪婪”路径参数必须位于资源路径的末尾。

与处理非代理资源一样,您可以通过 API Gateway 控制台、导入 OpenAPI 定义文件或直接调用 API Gateway REST API 来设置具有 HTTP 代理集成的代理资源。有关使用 API Gateway 控制台配置与 HTTP 集成的代理资源的详细说明,请参阅 教程:利用 HTTP 代理集成创建 REST API

以下 OpenAPI 定义文件显示了一个 API 的示例,该 API 具有与 PetStore 网站集成的代理资源。

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 的“贪婪”路径变量和“捕获所有”的 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

    目标资源是代理资源的父资源,但未在该资源上的 API 中定义 ANY 方法的运行时实例。因此,此 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 属性,以指定映射模板,为每个支持的内容类型设置一个映射模板。映射模板将方法请求参数或正文映射到集成请求正文。

同样,作为方法响应设置的一部分,您可以在 MethodResponse 资源上设置 responseParameters 属性。这可声明哪些方法响应参数将分派到客户端,哪些将从已从后端返回的集成响应参数或某些适用的正文属性进行映射。然后,作为集成响应设置的一部分,在相应的 IntegrationResponse 资源上设置 responseParameters 属性,以指定参数到参数的映射。您还要设置 responseTemplates 映射,以指定映射模板,为每个支持的内容类型设置一个映射模板。映射模板将集成响应参数或集成响应正文属性映射到方法响应正文。

有关设置映射模板的更多信息,请参阅针对 API Gateway 中 REST API 的数据转换