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

您可以使用*一流的集成*将 HTTP API 与AWS服务集成。一流的集成会将 HTTP API 路由连接到AWS服务 API。当客户端调用由一流集成支持的路由时，API Gateway 会为您调用AWS服务 API。例如，您可以使用一流的集成向 Amazon Simple Queue Service 队列发送消息，或启动 AWS 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)的值。 | 
| 静态值 | string | 常量值。 | 

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

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

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

以下 [create-integration](https://docs.aws.amazon.com/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"}'
```

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

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

# 集成子类型参考
<a name="http-api-develop-integrations-aws-services-reference"></a>

HTTP API 支持以下[集成子类型](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationsubtype)。

**Topics**
+ [EventBridge-PutEvents 1.0](#EventBridge-PutEvents)
+ [SQS-SendMessage 1.0](#SQS-SendMessage)
+ [SQS-ReceiveMessage 1.0](#SQS-ReceiveMessage)
+ [SQS-DeleteMessage 1.0](#SQS-DeleteMessage)
+ [SQS-PurgeQueue 1.0](#SQS-PurgeQueue)
+ [AppConfig-GetConfiguration 1.0](#AppConfig-GetConfiguration)
+ [Kinesis-PutRecord 1.0](#Kinesis-PutRecord)
+ [StepFunctions-StartExecution 1.0](#StepFunctions-StartExecution)
+ [StepFunctions-StartSyncExecution 1.0](#StepFunctions-StartSyncExecution)
+ [StepFunctions-StopExecution 1.0](#StepFunctions-StopExecution)

## EventBridge-PutEvents 1.0
<a name="EventBridge-PutEvents"></a>

将自定义事件发送到 Amazon EventBridge，以便将其与规则进行匹配。


| 参数 | 必需 | 
| --- | --- | 
| Detail | True | 
| DetailType | True | 
| 源 | True | 
| Time | False | 
| EventBusName | False | 
| 资源 | False | 
| 区域 | False | 
| TraceHeader | False | 

要了解更多信息，请参阅 *Amazon EventBridge API 参考* 中的 [PuteVentts](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutEvents.html)。

## SQS-SendMessage 1.0
<a name="SQS-SendMessage"></a>

向指定的队列传送了一条消息。


| 参数 | 必需 | 
| --- | --- | 
| QueueUrl | True | 
| MessageBody | True | 
| DelaySeconds | False | 
| MessageAttributes | False | 
| MessageDeduplicationId | False | 
| MessageGroupId | False | 
| MessageSystemAttributes | False | 
| 区域 | False | 

要了解更多信息，请参阅 *Amazon Simple Queue Service API 参考* 中的 [SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html)。

## SQS-ReceiveMessage 1.0
<a name="SQS-ReceiveMessage"></a>

从指定的队列中检索一条或多条消息（最多 10 条）。


| 参数 | 必需 | 
| --- | --- | 
| QueueUrl | True | 
| AttributeNames | False | 
| MaxNumberOfMessages | False | 
| MessageAttributeNames | False | 
| ReceiveRequestAttemptId | False | 
| VisibilityTimeout | False | 
| WaitTimeSeconds | False | 
| 区域 | False | 

要了解更多信息，请参阅 *Amazon Simple Queue Service API 参考* 中的 [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html)。

## SQS-DeleteMessage 1.0
<a name="SQS-DeleteMessage"></a>

从指定的队列中删除指定的消息。


| 参数 | 必需 | 
| --- | --- | 
| ReceiptHandle | True | 
| QueueUrl | True | 
| 区域 | False | 

要了解更多信息，请参阅 *Amazon Simple Queue Service API 参考* 中的 [DeleteMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessage.html)。

## SQS-PurgeQueue 1.0
<a name="SQS-PurgeQueue"></a>

删除指定队列中的所有消息。


| 参数 | 必需 | 
| --- | --- | 
| QueueUrl | True | 
| 区域 | False | 

要了解更多信息，请参阅 *Amazon Simple Queue Service API 参考* 中的 [PurgeQueue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_PurgeQueue.html)。

## AppConfig-GetConfiguration 1.0
<a name="AppConfig-GetConfiguration"></a>

接收有关配置的信息。


| 参数 | 必需 | 
| --- | --- | 
| 应用程序 | True | 
| 环境 | True | 
| 配置 | True | 
| ClientId | True | 
| ClientConfigurationVersion | False | 
| 区域 | False | 

如需了解详情，请参阅*AWS AppConfig API 参考*中的 [GetConfiguration](https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_GetConfiguration.html)。

## Kinesis-PutRecord 1.0
<a name="Kinesis-PutRecord"></a>

将单个数据记录写入 Amazon Kinesis 数据流。


| 参数 | 必需 | 
| --- | --- | 
| StreamName | True | 
| 数据 | True | 
| PartitionKey | True | 
| SequenceNumberForOrdering | False | 
| ExplicitHashKey | False | 
| 区域 | False | 

要了解更多信息，请参阅 *Amazon Kinesis Data Streams API 参考* 中的 [PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html)。

## StepFunctions-StartExecution 1.0
<a name="StepFunctions-StartExecution"></a>

启动状态机的一次执行。


| 参数 | 必需 | 
| --- | --- | 
| StateMachineArn | True | 
| 名称 | False | 
| 输入 | False | 
| 区域 | False | 

如需了解详情，请参阅 *AWS Step Functions API 参考*中的 [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)。

## StepFunctions-StartSyncExecution 1.0
<a name="StepFunctions-StartSyncExecution"></a>

启动同步状态机执行。


| 参数 | 必需 | 
| --- | --- | 
| StateMachineArn | True | 
| 名称 | False | 
| 输入 | False | 
| 区域 | False | 
| TraceHeader | False | 

如需了解详情，请参阅 *AWS Step Functions API 参考*中的 [StartSyncExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html)。

## StepFunctions-StopExecution 1.0
<a name="StepFunctions-StopExecution"></a>

停止一次执行。


| 参数 | 必需 | 
| --- | --- | 
| ExecutionArn | True | 
| 原因 | False | 
| 错误 | False | 
| 区域 | False | 

如需了解详情，请参阅 *AWS Step Functions API 参考*中的 [StopExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StopExecution.html)。