# API Gateway에서 HTTP API에 대한 AWS 서비스 통합 생성
<a name="http-api-develop-integrations-aws-services"></a>

*1급 통합*을 사용하여 AWS 서비스와 HTTP API를 통합할 수 있습니다. 1급 통합은 HTTP API 경로를 AWS 서비스 API에 연결합니다. 클라이언트가 1급 통합이 지원되는 경로를 호출하면 API Gateway에서 AWS 서비스 API를 자동으로 호출합니다. 예를 들어 1급 통합을 사용하여 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>

1급 통합에는 필수 및 선택적 파라미터가 사용됩니다. 통합을 생성하려면 필요한 모든 파라미터를 구성해야 합니다. 정적 값을 사용하거나 실행 시간에 동적으로 평가되는 파라미터를 매핑할 수 있습니다. 지원되는 통합 및 파라미터의 전체 목록은 [통합 하위 유형 참조](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인 경우 요청의 petId 파라미터를 \$1request.path.petId로 매핑할 수 있습니다. | 
| 요청 본문 패스스루 | \$1request.body | API Gateway는 전체 요청 본문을 전달합니다. | 
| 요청 본문 | \$1request.body.name | [JSON 경로 표현식](https://goessner.net/articles/JsonPath/index.html#e2). 재귀적 하강(\$1request.body..name) 및 필터 표현식(?(expression))은 지원되지 않습니다. JSON 경로를 지정하면 API Gateway가 요청 본문을 100KB로 잘라낸 다음 선택 표현식을 적용합니다. 100KB보다 큰 페이로드를 보내려면 `$request.body`을(를) 지정합니다.  | 
| 컨텍스트 변수 | \$1context.variableName | 지원되는 [컨텍스트 변수](http-api-logging-variables.md)의 값입니다. | 
| 단계 변수 | \$1stageVariables.variableName | [스테이지 변수](http-api-stages.stage-variables.md)의 값입니다. | 
| 정적 값 | string | 상수 값입니다. | 

## 1급 통합 생성
<a name="http-api-develop-integrations-aws-services-example"></a>

1급 통합을 생성하기 전에 통합 중인 AWS 서비스 작업을 호출할 수 있는 권한을 API Gateway에 부여하는 IAM 역할을 생성해야 합니다. 자세한 내용은 [AWS 서비스에 대한 역할 생성](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)을 참조하세요.

1급 통합을 생성하려면 지원되는 AWS 서비스 작업(예: `SQS-SendMessage`)을 선택하고, 요청 파라미터를 구성하고, 통합된 AWS 서비스 API를 호출할 수 있는 권한을 API Gateway에 부여하는 역할을 제공합니다. 통합 하위 유형에 따라 다른 요청 파라미터가 필요합니다. 자세한 내용은 [통합 하위 유형 참조](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를 사용하여 1급 통합 생성
<a name="http-api-develop-integrations-aws-services-example-cfn"></a>

다음 예시는 Amazon EventBridge과의 최고 수준의 통합을 통해 `/{source}/{detailType}` 경로를 생성하는 CloudFormation 스니펫을 보여줍니다.

`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로 보냅니다.


| 파라미터 | 필수 | 
| --- | --- | 
| 세부 정보 | True | 
| DetailType | True | 
| 소스 | True | 
| 시간 | False | 
| EventBusName | False | 
| 리소스 | 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>

구성에 대한 정보를 수신합니다.


| 파라미터 | 필수 | 
| --- | --- | 
| 애플리케이션 | 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 | 
| 이름 | False | 
| 입력 | 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 | 
| 이름 | False | 
| 입력 | 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 | 
| 원인 | False | 
| 오류 | False | 
| Region | False | 

자세한 내용은 *AWS Step Functions API 참조*의 [StopExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StopExecution.html)을 참조하세요.