使用针对 HTTP API 的 AWS 服务集成 - Amazon 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"