针对 API Gateway 中的 HTTP API 创建 AWS 服务集成 - Amazon API Gateway

针对 API Gateway 中的 HTTP API 创建 AWS 服务集成

您可以使用一流的集成将 HTTP API 与AWS服务集成。一流的集成会将 HTTP API 路由连接到AWS服务 API。当客户端调用由一流集成支持的路由时,API Gateway 会为您调用AWS服务 API。例如,您可以使用一流的集成向 Amazon Simple Queue Service 队列发送消息,或启动 AWS Step Functions 状态机。有关支持的服务操作,请参阅 集成子类型参考

映射请求参数

一流的集成具有必需和可选的参数。必须配置所有必需的参数才能创建集成。您可以使用在运行时动态评估的静态值或映射参数。有关支持的集成和参数的完整列表,请参阅集成子类型参考

下表描述了支持的映射请求参数。

类型 示例 备注
标头值 $request.header.name 标头名称不区分大小写。API Gateway 将多个标头值与逗号组合在一起,例如 "header1": "value1,value2"
查询字符串值 $request.querystring.name 查询字符串名称区分大小写。API Gateway 将多个值与逗号组合在一起,例如 "querystring1": "Value1,Value2"
路径参数 $request.path.name 请求中路径参数的值。例如,如果路由为 /pets/{petId},则可以从具有 $request.path.petId 的请求中映射 petId 参数。
请求正文传递 $request.body API Gateway 传递整个请求正文。
请求正文 $request.body.name JSON 路径表达式。不支持递归下降 ($request.body..name) 和筛选表达式 (?(expression))。
注意

当您指定 JSON 路径时,API Gateway 会在请求正文的 100 KB 处将其截断,然后应用选择表达式。要发送大于 100 KB 的负载,请指定 $request.body

上下文变量 $context.variableName 受支持的上下文变量的值。
阶段变量 $stageVariables.variableName 阶段变量的值。
静态值 string 常量值。

创建一流的集成

在创建一流集成之前,您必须创建一个 IAM 角色,该角色向 API Gateway 授予调用您要集成的AWS服务操作的权限。如需了解详情,请参阅为AWS服务创建角色

要创建一流集成,请选择受支持的AWS服务操作(例如 SQS-SendMessage),配置请求参数,然后提供一个角色来授予 API Gateway 调用集成的AWS服务 API 的权限。根据集成子类型,需要不同的请求参数。要了解更多信息,请参阅集成子类型参考

以下 AWS CLI 命令会创建一个用于发送 Amazon SQS 消息的集成。

aws apigatewayv2 create-integration \ --api-id abcdef123 \ --integration-subtype SQS-SendMessage \ --integration-type AWS_PROXY \ --payload-format-version 1.0 \ --credentials-arn arn:aws:iam::123456789012:role/apigateway-sqs \ --request-parameters '{"QueueUrl": "$request.header.queueUrl", "MessageBody": "$request.body.message"}'

使用 AWS CloudFormation 创建一流的集成

以下示例显示了一个 AWS CloudFormation 代码段,该代码段可创建一个与 Amazon EventBridge 进行一流集成的 /{source}/{detailType} 路径。

Source 参数映射到 {source} 路径参数,DetailType 映射到 {DetailType} 路径参数,Detail参数映射到请求正文。

该代码段不显示事件总线或授予 API Gateway 调用 PutEvents 操作的权限的 IAM 角色。

Route: Type: AWS::ApiGatewayV2::Route Properties: ApiId: !Ref HttpApi AuthorizationType: None RouteKey: 'POST /{source}/{detailType}' Target: !Join - / - - integrations - !Ref Integration Integration: Type: AWS::ApiGatewayV2::Integration Properties: ApiId: !Ref HttpApi IntegrationType: AWS_PROXY IntegrationSubtype: EventBridge-PutEvents CredentialsArn: !GetAtt EventBridgeRole.Arn RequestParameters: Source: $request.path.source DetailType: $request.path.detailType Detail: $request.body EventBusName: !GetAtt EventBus.Arn PayloadFormatVersion: "1.0"