# 针对 API Gateway 中的 HTTP API 创建 Amazon 服务集成
<a name="http-api-develop-integrations-aws-services"></a>

您可以使用*一流的集成*将 HTTP API 与Amazon服务集成。一流的集成会将 HTTP API 路由连接到Amazon服务 API。当客户端调用由一流集成支持的路由时，API Gateway 会为您调用Amazon服务 API。例如，您可以使用一流的集成向 Amazon Simple Queue Service 队列发送消息，或启动 Amazon Step Functions 状态机。有关支持的服务操作，请参阅 [集成子类型参考](http-api-develop-integrations-aws-services-reference.md)。

## 映射请求参数
<a name="http-api-develop-integrations-aws-services-parameter-mapping"></a>

一流的集成具有必需和可选的参数。必须配置所有必需的参数才能创建集成。您可以使用在运行时动态评估的静态值或映射参数。有关支持的集成和参数的完整列表，请参阅[集成子类型参考](http-api-develop-integrations-aws-services-reference.md)。

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


| 类型 | 示例 | 备注 | 
| --- | --- | --- | 
| 标头值 | \$1request.header.name | 标头名称不区分大小写。API Gateway 将多个标头值与逗号组合在一起，例如 "header1": "value1,value2"。 | 
| 查询字符串值 | \$1request.querystring.name | 查询字符串名称区分大小写。API Gateway 将多个值与逗号组合在一起，例如 "querystring1": "Value1,Value2"。 | 
| 路径参数 | \$1request.path.name | 请求中路径参数的值。例如，如果路由为 /pets/\$1petId\$1，则可以从具有 \$1request.path.petId 的请求中映射 petId 参数。 | 
| 请求正文传递 | \$1request.body | API Gateway 传递整个请求正文。 | 
| 请求正文 | \$1request.body.name | [JSON 路径表达式](https://goessner.net/articles/JsonPath/index.html#e2)。不支持递归下降 (\$1request.body..name) 和筛选表达式 (?(expression))。 当您指定 JSON 路径时，API Gateway 会在请求正文的 100 KB 处将其截断，然后应用选择表达式。要发送大于 100 KB 的负载，请指定 `$request.body`。  | 
| 上下文变量 | \$1context.variableName | 受支持的[上下文变量](http-api-logging-variables.md)的值。 | 
| 阶段变量 | \$1stageVariables.variableName | [阶段变量](http-api-stages.stage-variables.md)的值。 | 
| 静态值 | 字符串 | 常量值。 | 

## 创建一流的集成
<a name="http-api-develop-integrations-aws-services-example"></a>

在创建一流集成之前，您必须创建一个 IAM 角色，该角色向 API Gateway 授予调用您要集成的Amazon服务操作的权限。如需了解详情，请参阅[为Amazon服务创建角色](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_roles_create_for-service.html)。

要创建一流集成，请选择受支持的Amazon服务操作（例如 `SQS-SendMessage`），配置请求参数，然后提供一个角色来授予 API Gateway 调用集成的Amazon服务 API 的权限。根据集成子类型，需要不同的请求参数。要了解更多信息，请参阅[集成子类型参考](http-api-develop-integrations-aws-services-reference.md)。

以下 [create-integration](https://docs.amazonaws.cn/cli/latest/reference/apigatewayv2/create-integration.html) 命令创建发送 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"}'
```

## 使用 Amazon CloudFormation 创建一流的集成
<a name="http-api-develop-integrations-aws-services-example-cfn"></a>

以下示例显示了一个 Amazon 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"
```