本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在 APIs 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)。

下表說明受支援的映射請求參數。


| Type | 範例 | 備註 | 
| --- | --- | --- | 
| 標頭值 | \$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>

建立一級整合之前，您必須建立授予 API Gateway 許可的 IAM 角色，以叫用您要整合 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 | 
| Source | True | 
| Time | False | 
| EventBusName | False | 
| Resources | False | 
| Region | False | 
| TraceHeader | False | 

若要進一步了解，請參閱《Amazon EventBridge API 參考》**中的 [PutEvents](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 | 
| Region | 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 | 
| Region | 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 | 
| Region | 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 | 
| Region | 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>

接收組態的相關資訊。


| 參數 | 必要 | 
| --- | --- | 
| Application | True | 
| Environment | True | 
| Configuration | True | 
| ClientId | True | 
| ClientConfigurationVersion | False | 
| Region | 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 | 
| Data | True | 
| PartitionKey | True | 
| SequenceNumberForOrdering | False | 
| ExplicitHashKey | False | 
| Region | 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 | 
| Name | False | 
| Input | False | 
| Region | 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 | 
| Name | False | 
| Input | False | 
| Region | 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 | 
| Cause | False | 
| Error | False | 
| Region | False | 

如需進一步了解，請參閱《AWS Step Functions API 參考》**中的 [StopExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StopExecution.html)。