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

# 在 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 | 範例 | 備註 | 
| --- | --- | --- | 
| 標頭值 | $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 路徑表達式](https://goessner.net/articles/JsonPath/index.html#e2)。不支援遞迴下降 ($request.body..{{name}}) 和篩選表達式 (?({{expression}}))。 當您指定 JSON 路徑時，API Gateway 會在 100 KB 時截斷請求主體，然後套用選擇表達式。若要傳送大於 100 KB 的承載，請指定 `$request.body`。  | 
| 環境變數 | $context.{{variableName}} | 支援的[內容變數](http-api-logging-variables.md)值。 | 
| 階段變數 | $stageVariables.{{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"
```