API Gateway에서 HTTP API에 대한 AWS 서비스 통합 생성

1급 통합을 사용하여 AWS 서비스와 HTTP API를 통합할 수 있습니다. 1급 통합은 HTTP API 경로를 AWS 서비스 API에 연결합니다. 클라이언트가 1급 통합이 지원되는 경로를 호출하면 API Gateway에서 AWS 서비스 API를 자동으로 호출합니다. 예를 들어 1급 통합을 사용하여 Amazon Simple Queue Service 대기열에 메시지를 보내거나 AWS Step Functions 상태 시스템을 시작할 수 있습니다. 지원되는 서비스 작업은 통합 하위 유형 참조 단원을 참조하세요.

매핑 요청 파라미터

1급 통합에는 필수 및 선택적 파라미터가 사용됩니다. 통합을 생성하려면 필요한 모든 파라미터를 구성해야 합니다. 정적 값을 사용하거나 실행 시간에 동적으로 평가되는 파라미터를 매핑할 수 있습니다. 지원되는 통합 및 파라미터의 전체 목록은 통합 하위 유형 참조 단원을 참조하세요.

다음 표에서는 지원되는 매핑 요청 파라미터를 설명합니다.

유형	예	참고
헤더 값	$request.header.name	헤더 이름은 대/소문자를 구분하지 않습니다. API Gateway는 쉼표를 사용하여 여러 헤더 값을 결합합니다(예: "header1": "value1,value2").
쿼리 문자열 값	$request.querystring.name	쿼리 문자열 이름은 대/소문자를 구분합니다. API Gateway는 쉼표를 사용하여 여러 값을 결합합니다(예: "querystring1": "Value1,Value2").
경로 파라미터	$request.path.name	요청에 포함된 경로 파라미터의 값입니다. 예를 들어 라우팅이 /pets/{petId}인 경우 요청의 petId 파라미터를 $request.path.petId로 매핑할 수 있습니다.
요청 본문 패스스루	$request.body	API Gateway는 전체 요청 본문을 전달합니다.
요청 본문	$request.body.name	JSON 경로 표현식. 재귀적 하강($request.body..name) 및 필터 표현식(?(expression))은 지원되지 않습니다. 참고 JSON 경로를 지정하면 API Gateway가 요청 본문을 100KB로 잘라낸 다음 선택 표현식을 적용합니다. 100KB보다 큰 페이로드를 보내려면 $request.body을(를) 지정합니다.
컨텍스트 변수	$context.variableName	지원되는 컨텍스트 변수의 값입니다.
단계 변수	$stageVariables.variableName	스테이지 변수의 값입니다.
정적 값	string	상수 값입니다.

1급 통합 생성

1급 통합을 생성하기 전에 통합 중인 AWS 서비스 작업을 호출할 수 있는 권한을 API Gateway에 부여하는 IAM 역할을 생성해야 합니다. 자세한 내용은 AWS 서비스에 대한 역할 생성을 참조하세요.

1급 통합을 생성하려면 지원되는 AWS 서비스 작업(예: SQS-SendMessage)을 선택하고, 요청 파라미터를 구성하고, 통합된 AWS 서비스 API를 호출할 수 있는 권한을 API Gateway에 부여하는 역할을 제공합니다. 통합 하위 유형에 따라 다른 요청 파라미터가 필요합니다. 자세한 내용은 통합 하위 유형 참조 단원을 참조하세요.

다음 AWS CLI 명령은 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"}'

AWS CloudFormation를 사용하여 1급 통합 생성

다음 예시는 Amazon EventBridge과의 최고 수준의 통합을 통해 /{source}/{detailType} 경로를 생성하는 AWS 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"