AWS::Serverless::HttpApi

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

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

AWS CloudFormation 후크 사용에 대한 자세한 내용은 AWS CloudFormation CLI 사용 설명서 및 리포지토리의 후크 등록을 참조하십시오. apigw-enforce-authorizer GitHub

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

참고

에 AWS CloudFormation배포하면 AWS SAM 리소스를 리소스로 AWS SAM AWS CloudFormation 변환합니다. 자세한 정보는 에 대한 AWS CloudFormation 리소스 생성 AWS SAM을 참조하세요.

구문

AWS Serverless Application Model (AWS SAM) 템플릿에서 이 엔티티를 선언하려면 다음 구문을 사용하십시오.

YAML


Type: AWS::Serverless::HttpApi
Properties:
  AccessLogSettings: AccessLogSettings
  Auth: HttpApiAuth
  CorsConfiguration: String | HttpApiCorsConfiguration
  DefaultRouteSettings: RouteSettings
  DefinitionBody: JSON
  DefinitionUri: String | HttpApiDefinition
  Description: String
  DisableExecuteApiEndpoint: Boolean
  Domain: HttpApiDomainConfiguration
  FailOnWarnings: Boolean
  Name: String
  PropagateTags: Boolean
  RouteSettings: RouteSettings
  StageName: String
  StageVariables: Json
  Tags: Map

속성

AccessLogSettings

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

유형: AccessLogSettings

필수 항목 여부: 아니요

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

Auth

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

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

유형: HttpApiAuth

필수 항목 여부: 아니요

AWS CloudFormation 호환성: 이 속성은 AWS SAM 고유하며 AWS CloudFormation 이에 상응하는 속성이 없습니다.

CorsConfiguration

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

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

참고

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

유형: 문자열 | HttpApiCorsConfiguration

필수 항목 여부: 아니요

AWS CloudFormation 호환성: 이 속성은 AWS SAM 고유하며 AWS CloudFormation 이에 상응하는 속성이 없습니다.

DefaultRouteSettings

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

유형: RouteSettings

필수 항목 여부: 아니요

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

DefinitionBody

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

유형: JSON

필수 항목 여부: 아니요

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

DefinitionUri

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

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

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

유형: 문자열 | HttpApiDefinition

필수 항목 여부: 아니요

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

Description

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

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

DefinitionBody속성은 Open API 정의에 설정된 description 필드로 지정됩니다. 이 경우 description 필드 충돌이 발생하지만 해결되지 AWS SAM 않습니다.
DefinitionUri속성이 지정되었으므로 Amazon S3에서 검색된 오픈 API 정의를 수정하지 AWS SAM 않습니다.

타입: 문자열

필수 항목 여부: 아니요

AWS CloudFormation 호환성: 이 속성은 AWS SAM 고유하며 AWS CloudFormation 이에 상응하는 속성이 없습니다.

DisableExecuteApiEndpoint

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

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

유형: 부울

필수 항목 여부: 아니요

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

Domain

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

유형: HttpApiDomainConfiguration

필수 항목 여부: 아니요

AWS CloudFormation 호환성: 이 속성은 AWS SAM 고유하며 AWS CloudFormation 이에 상응하는 속성이 없습니다.

FailOnWarnings

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

유형: 부울

필수 항목 여부: 아니요

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

Name

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

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

DefinitionBody속성은 Open API 정의에 설정된 title 필드로 지정됩니다. 이 경우 title 필드 충돌이 발생하지만 해결되지 AWS SAM 않습니다.
DefinitionUri속성이 지정되었으므로 Amazon S3에서 검색된 오픈 API 정의를 수정하지 AWS SAM 않습니다.

타입: 문자열

필수 항목 여부: 아니요

AWS CloudFormation 호환성: 이 속성은 AWS SAM 고유하며 AWS CloudFormation 이에 상응하는 속성이 없습니다.

PropagateTags

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

유형: 부울

필수 항목 여부: 아니요

기본값: False

AWS CloudFormation 호환성: 이 속성은 AWS SAM 고유하며 AWS CloudFormation 이에 상응하는 속성이 없습니다.

RouteSettings

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

유형: RouteSettings

필수 항목 여부: 아니요

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

StageName

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

타입: 문자열

필수 항목 여부: 아니요

기본값: $default

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

StageVariables

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

유형: Json

필수 항목 여부: 아니요

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

Tags

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

유형: 맵

필수 항목 여부: 아니요

AWS CloudFormation 호환성: 이 속성은 AWS SAM 고유하며 AWS CloudFormation 이에 상응하는 속성이 없습니다.

추가 참고 사항: Tags 속성은 OpenAPI 정의를 AWS SAM 수정해야 하므로 속성이 지정된 경우에만 태그가 추가되고 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 항목을 참조하십시오.

예

심플 HttpApi

다음 예는 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"

HttpApiOpenAPI 정의 포함

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

참고로, 이 HTTP API를 참조하는 이벤트에 HttpApi 대해 누락된 Lambda 통합을 모두 AWS SAM 채웁니다. 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

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

런타임

HttpApiAuth