AWS::Serverless::HttpApi - AWS Serverless Application Model
구문속성반환 값예시

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

AWS::Serverless::HttpApi

Amazon API Gateway HTTP API를 생성함으로써 귀하는 REST API보다 지연 시간이 짧고 비용이 저렴한 RESTful API를 생성할 수 있습니다. 자세한 내용을 알아보려면 API Gateway 개발자 안내서의 HTTP API로 작업하기를 참조하세요.

CloudFormation 후크 또는 IAM 정책을 사용하여 API Gateway 리소스에 액세스를 제어할 권한 부여자가 연결되어 있는지 확인하는 것이 좋습니다.

CloudFormation 후크 사용에 대한 자세한 내용은 CLI 사용자 가이드의 CloudFormation후크 등록 및 apigw-enforce-authorizer GitHub 리포지토리를 참조하세요.

IAM 정책 사용에 대한 자세한 내용은 API 게이트웨이 개발자 가이드의 API 경로에 권한 부여 필요를 참조하세요.

참고

AWS CloudFormation에 배포하면 AWS SAM는 귀하의 AWS SAM 리소스를 CloudFormation 리소스로 변환됩니다. 자세한 내용은 AWS SAM용으로 생성된 CloudFormation 리소스 섹션을 참조하십시오.

구문

귀하의 AWS Serverless Application Model(AWS SAM) 템플릿에서 이 객체를 선언하려면 다음 명령문을 사용합니다.

속성

AccessLogSettings

단계의 로깅 액세스에 대한 설정입니다.

유형: AccessLogSettings

필수 항목 여부: 아니요

CloudFormation호환성: 이 속성은 AWS::ApiGatewayV2::Stage 리소스의 AccessLogSettings 속성으로 직접 전달됩니다.

Auth

API Gateway HTTP API에 대한 액세스를 제어하기 위한 권한 부여를 구성합니다.

자세한 내용은 API Gateway 개발자 가이드에서 JWT 권한 부여자를 사용하여 HTTP API에 대한 액세스 제어를 참조하십시오.

유형: HTTP/APIAuth

필수 항목 여부: 아니요

CloudFormation호환성: 이 속성은 AWS SAM에 고유하며 CloudFormation 동등한 속성이 없습니다.

CorsConfiguration

귀하의 모든 API Gateway HTTP API를 위하여 교차 오리진 리소스 공유(CORS)를 관리합니다. 허용할 도메인을 문자열로 지정하거나 HttpApiCorsConfiguration 객체를 지정합니다. 단, CORS는 AWS SAM로 하여금 OpenAPI 정의를 수정하도록 해야 하므로 CORS는 DefinitionBody 속성이 지정된 경우에만 작동합니다.

자세한 내용은 API Gateway 개발자 안내서의 HTTP API에 대한 CORS 구성을 참조하세요.

참고

CorsConfiguration이 OpenAPI 정의와 속성 수준에서 모두 설정된 경우 AWS SAM는 두 구성 소스를 우선 순위가 있는 속성과 병합합니다. 이 속성을 true로 설정하면 모든 오리진이 허용됩니다.

유형: 문자열 |HttpApiCorsConfiguration

필수 항목 여부: 아니요

CloudFormation호환성: 이 속성은 AWS SAM에 고유하며 CloudFormation 동등한 속성이 없습니다.

DefaultRouteSettings

이 HTTP API에 대한 기본 라우팅 설정입니다. 이 설정은 특정 경로에 대해 RouteSettings 속성에서 재정의하지 않는 한 모든 경로에 적용됩니다.

유형: RouteSettings

필수 항목 여부: 아니요

CloudFormation호환성: 이 속성은 AWS::ApiGatewayV2::Stage 리소스의 RouteSettings 속성으로 직접 전달됩니다.

DefinitionBody

HTTP API를 설명하는 OpenAPI 정의. 귀하가 DefinitionUri 또는 DefinitionBody 를 지정하지 않으면 AWS SAM이 귀하의 템플릿 구성을 기반으로 귀하의 DefinitionBody를 자동으로 생성합니다.

유형: JSON

필수 항목 여부: 아니요

CloudFormation호환성: 이 속성은 AWS::ApiGatewayV2::Api 리소스의 Body 속성과 유사합니다. 특정 속성이 제공되는 경우, AWS SAM은 CloudFormation에 전달되기 전에 DefinitionBody에 콘텐츠를 삽입하거나 수정할 수 있습니다. 속성들에는 Auth 및 해당 AWS::Serverless::Function 속성을 위한 HttpApi 유형의 EventSource가 포함됩니다.

DefinitionUri

HTTP API를 정의할 수 있는 OpenAPI 정의의 Amazon Simple Storage Service(S3) URI이거나 로컬 파일 경로이거나 위치 객체입니다. 이 속성이 참조하는 Amazon S3 객체는 유효한 OpenAPI 정의 파일이어야 합니다. 귀하가 DefinitionUri 또는 DefinitionBody를 지정하지 않으면 AWS SAM이 귀하의 템플릿 구성을 기반으로 귀하의 DefinitionBody를 생성합니다.

귀하가 로컬 파일 경로를 제공하는 경우 템플릿은 sam deploy 또는 sam package 명령이 포함된 워크플로를 거쳐야 정의가 제대로 변환됩니다.

귀하가 DefinitionUri로 참조하는 외부 OpenAPI 정의 파일에서는 내장 함수가 지원되지 않습니다. OpenAPI 정의를 템플릿으로 들여오려면 해당 DefinitionBody 속성을 Include 변환과 함께 사용합니다.

유형: 문자열 | HttpApiDefinition

필수 항목 여부: 아니요

CloudFormation호환성: 이 속성은 AWS::ApiGatewayV2::Api 리소스의 BodyS3Location 속성과 유사합니다. 중첩된 Amazon S3 속성은 다르게 지정됩니다.

Description

HTTP API 리소스 그룹에 대한 설명입니다.

귀하가 Description을 지정하면 AWS SAM는 description필드를 설정하여 HTTP API 리소스의 OpenAPI 정의를 수정합니다. 다음 시나리오에서는 오류가 발생합니다.

  • DefinitionBody 속성이 Open API 정의에 설정된 description 필드로 지정됨 – 이로 인해 description 필드 충돌이 발생하지만 AWS SAM가 이를 해결하지 못합니다.

  • DefinitionUri 속성이 지정되었으므로 AWS SAM는 Amazon S3에서 검색된 오픈 API 정의를 수정하지 않습니다.

유형: 문자열

필수 항목 여부: 아니요

CloudFormation호환성: 이 속성은 AWS SAM에 고유하며 CloudFormation 동등한 속성이 없습니다.

DisableExecuteApiEndpoint

클라이언트가 기본 execute-api 엔드포인트https://{api_id}.execute-api.{region}.amazonaws.com를 사용하여 HTTP API를 호출할 수 있는지 여부를 지정합니다. 기본적으로 클라이언트는 기본 엔드포인트로 API를 호출할 수 있습니다. 클라이언트가 단지 사용자 지정 도메인 이름을 사용하여 API를 호출하도록 요구하려면 기본 엔드포인트를 비활성화합니다.

이 속성을 사용하려면 DefinitionUri 속성 대신 DefinitionBody 속성을 지정하거나 OpenAPI 정의에서 x-amazon-apigateway-endpoint-configuration을 disableExecuteApiEndpoint로 정의해야 합니다.

유형: 부울

필수 항목 여부: 아니요

CloudFormation호환성: 이 속성은 AWS::ApiGatewayV2::Api 리소스의 DisableExecuteApiEndpoint 속성과 유사합니다. 이것은 x-amazon-apigateway-endpoint-configuration 확장의 disableExecuteApiEndpoint 속성으로 직접 전달되며, 이것은 AWS::ApiGatewayV2::Api 리소스의 Body 속성에 추가됩니다.

Domain

이 API Gateway HTTP API의 사용자 지정 도메인을 구성합니다.

유형: HttpApiDomainConfiguration

필수 항목 여부: 아니요

CloudFormation호환성: 이 속성은 AWS SAM에 고유하며 CloudFormation 동등한 속성이 없습니다.

FailOnWarnings

경고가 발생할 때 HTTP API 생성을 롤백할 것인지(true), 아니면 롤백하지 않을 것인지(false) 지정합니다. 기본값은 false입니다.

유형: 부울

필수 항목 여부: 아니요

CloudFormation호환성: 이 속성은 AWS::ApiGatewayV2::Api 리소스의 FailOnWarnings 속성으로 직접 전달됩니다.

Name

HTTP API 리소스의 이름입니다.

귀하가 Name을 지정하면 AWS SAM는 title필드를 설정하여 HTTP API 리소스의 OpenAPI 정의를 수정합니다. 다음 시나리오에서는 오류가 발생합니다.

  • DefinitionBody 속성이 Open API 정의에 설정된 title 필드로 지정됨 – 이로 인해 title 필드 충돌이 발생하지만 AWS SAM가 이를 해결하지 못합니다.

  • DefinitionUri 속성이 지정되었으므로 AWS SAM는 Amazon S3에서 검색된 오픈 API 정의를 수정하지 않습니다.

유형: 문자열

필수 항목 여부: 아니요

CloudFormation호환성: 이 속성은 AWS SAM에 고유하며 CloudFormation 동등한 속성이 없습니다.

PropagateTags

Tags속성의 태그를 AWS::Serverless::HttpApi 생성된 리소스로 전달할지 여부를 지정합니다. 귀하의 생성된 리소스에 태그를 전파하도록 True을 지정합니다.

유형: 부울

필수 항목 여부: 아니요

기본값: False

CloudFormation호환성: 이 속성은 AWS SAM에 고유하며 CloudFormation 동등한 속성이 없습니다.

RouteSettings

이 HTTP API의 경로별 경로 설정입니다. 자세한 내용을 알아보려면 API Gateway 개발자 안내서의 HTTP API에 대한 루트 작업을 참조하세요.

유형: RouteSettings

필수 항목 여부: 아니요

CloudFormation호환성: 이 속성은 AWS::ApiGatewayV2::Stage 리소스의 RouteSettings 속성으로 직접 전달됩니다.

StageName

API 단계의 이름. 이름을 지정하지 않은 경우 AWS SAM은 API Gateway로부터 $default 스테이지를 사용합니다.

유형: 문자열

필수 항목 여부: 아니요

기본값: $default

CloudFormation호환성: 이 속성은 AWS::ApiGatewayV2::Stage 리소스의 StageName 속성으로 직접 전달됩니다.

StageVariables

단계 변수를 정의하는 맵입니다. 변수 이름은 영숫자와 밑줄 문자를 사용할 수 있습니다. 값은 [A-Za-z0-9-._~:/?#&=,]+와 일치해야 합니다.

유형: Json

필수 항목 여부: 아니요

CloudFormation호환성: 이 속성은 AWS::ApiGatewayV2::Stage 리소스의 StageVariables 속성으로 직접 전달됩니다.

Tags

이 API Gateway 단계에 추가할 태그를 지정하는 맵(문자열에 문자열)입니다. 키는 길이가 1~128자인 유니코드 문자이며 aws:로 시작할 수 없습니다. 유니코드 문자 세트, 숫자, 공백, _, ., /, =, +, - 등의 문자를 무엇이든 사용할 수 있습니다. 값은 길이가 1~256자인 유니코드 문자입니다.

유형: 맵

필수 항목 여부: 아니요

CloudFormation호환성: 이 속성은 AWS SAM에 고유하며 CloudFormation 동등한 속성이 없습니다.

추가 참고 사항: Tags 속성은 AWS SAM에게 OpenAPI 정의를 수정할 것을 요구하므로 DefinitionBody속성이 지정된 경우에만 태그가 추가되고 DefinitionUri속성이 지정된 경우에는 태그가 추가되지 않습니다. AWS SAM은 httpapi:createdBy:SAM태그를 자동으로 추가합니다. AWS::ApiGatewayV2::Stage리소스와 AWS::ApiGatewayV2::DomainName리소스(DomainName이 지정된 경우)에도 태그가 추가됩니다.

반환 값

Ref

이 리소스의 논리적 ID를 내장 Ref 함수에 전달하면 Ref가 기저의 AWS::ApiGatewayV2::Api 리소스의 API ID를 반환합니다(예:a1bcdef2gh)

Ref 함수의 사용에 대한 자세한 내용은 AWS CloudFormation사용자 안내서의 Ref 항목을 참조하십시오.

예시

단순 HTTP API

다음 예는 Lambda 함수가 지원하는 HTTP API 엔드포인트를 설정하는 데 필요한 최소값을 보여줍니다. 이 예제에서는 AWS SAM이 생성하는 기본 HTTP API를 사용합니다.

YAML

AWSTemplateFormatVersion: '2010-09-09'
Description: AWS SAM template with a simple API definition
Resources:
  ApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: HttpApi
      Handler: index.handler
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}
      Runtime: python3.7
Transform: AWS::Serverless-2016-10-31

권한 부여가 있는 HttpApi

다음 예에서는 HTTP API 엔드포인트에서 권한 부여를 설정하는 방법을 보여드립니다.

YAML

Properties:
  FailOnWarnings: true
  Auth:
    DefaultAuthorizer: OAuth2
    Authorizers:
      OAuth2:
        AuthorizationScopes:
          - scope4
        JwtConfiguration:
          issuer: "https://www.example.com/v1/connect/oauth2"
          audience:
            - MyApi
        IdentitySource: "$request.querystring.param"

OpenAPI 정의를 포함하는 HttpApi

다음 예에서는 OpenAPI 정의를 템플릿에 추가하는 방법을 보여드립니다.

참고로, AWS SAM은 이 HTTP API를 참조하는 HttpApi 이벤트에 대해 누락된 Lambda 통합을 모두 채웁니다. AWS SAM 역시 HttpApi 이벤트가 참조하는 누락된 경로도 모두 추가합니다.

YAML

Properties:
  FailOnWarnings: true
  DefinitionBody:
    info:
      version: '1.0'
      title:
        Ref: AWS::StackName
    paths:
      "/":
        get:
          security:
          - OpenIdAuth:
            - scope1
            - scope2
          responses: {}
    openapi: 3.0.1
    securitySchemes:
      OpenIdAuth:
        type: openIdConnect
        x-amazon-apigateway-authorizer:
          identitySource: "$request.querystring.param"
          type: jwt
          jwtConfiguration:
            audience:
            - MyApi
            issuer: https://www.example.com/v1/connect/oidc
          openIdConnectUrl: https://www.example.com/v1/connect/oidc/.well-known/openid-configuration

구성 설정을 포함하는 HttpApi

다음 예에서는 템플릿에 HTTP API 및 단계 구성을 추가하는 방법을 보여드립니다.

YAML

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Parameters:
  StageName:
    Type: String
    Default: Prod
    
Resources:
  HttpApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      InlineCode: |
          def handler(event, context):
              import json
              return {
                  "statusCode": 200,
                  "body": json.dumps(event),
              }
      Handler: index.handler
      Runtime: python3.7
      Events:
        ExplicitApi: # warning: creates a public endpoint
          Type: HttpApi
          Properties:
            ApiId: !Ref HttpApi
            Method: GET
            Path: /path
            TimeoutInMillis: 15000
            PayloadFormatVersion: "2.0"
            RouteSettings:
              ThrottlingBurstLimit: 600

  HttpApi:
    Type: AWS::Serverless::HttpApi
    Properties:
      StageName: !Ref StageName
      Tags:
        Tag: Value
      AccessLogSettings:
        DestinationArn: !GetAtt AccessLogs.Arn
        Format: $context.requestId
      DefaultRouteSettings:
        ThrottlingBurstLimit: 200
      RouteSettings:
        "GET /path":
          ThrottlingBurstLimit: 500 # overridden in HttpApi Event
      StageVariables:
        StageVar: Value
      FailOnWarnings: true

  AccessLogs:
    Type: AWS::Logs::LogGroup

Outputs:
  HttpApiUrl:
    Description: URL of your API endpoint
    Value:
      Fn::Sub: 'https://${HttpApi}.execute-api.${AWS::Region}.${AWS::URLSuffix}/${StageName}/'
  HttpApiId:
    Description: Api id of HttpApi
    Value:
      Ref: HttpApi