针对 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
在本示例中,代理资源的 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 的数据转换。