기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# AWS::Serverless::Api
HTTPS 엔드포인트를 통해 간접 호출할 수 있는 Amazon API Gateway 리소스 및 메서드 컬렉션을 생성합니다.
AWS 서버리스 애플리케이션 정의 템플릿에 [AWS::Serverless::Api](#sam-resource-api) 리소스를 명시적으로 추가할 필요는 없습니다. 이 유형의 리소스는 [AWS::Serverless::Function](sam-resource-function.md) 리소스를 참조하지 않는 템플릿에 정의된 [AWS::Serverless::Api](#sam-resource-api) 리소스에 정의된 Api 이벤트를 결합하여 묵시적으로 생성됩니다.
기본 Amazon API Gateway 리소스를 구성할 수 있는 더 많은 기능을 제공하는 OpenAPI를 사용하여 API를 정의하고 문서화하려면 [AWS::Serverless::Api](#sam-resource-api)리소스를 사용해야 합니다.
CloudFormation 후크 또는 IAM 정책을 사용하여 API Gateway 리소스에 대한 액세스를 제어하는 권한 부여자가 연결되어 있는지 확인하는 것이 좋습니다.
CloudFormation 후크 사용에 대한 자세한 내용은 *CloudFormation CLI 사용 설명서*의 [후크 등록](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/registering-hook-python.html) 및 [apigw-enforce-authorizer](https://github.com/aws-cloudformation/aws-cloudformation-samples/tree/main/hooks/python-hooks/apigw-enforce-authorizer/) GitHub 리포지토리를 참조하세요.
IAM 정책 사용에 대한 자세한 내용은 [API 게이트웨이 개발자 가이드의](https://docs.aws.amazon.com/apigateway/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-require-authorization) *API 경로에 권한 부여 필요를* 참조하세요.
**참고**
에 배포하면가 AWS SAM 리소스를 CloudFormation 리소스로 AWS CloudFormation AWS SAM 변환합니다. 자세한 내용은 [에 대해 생성된 CloudFormation 리소스 AWS SAM](sam-specification-generated-resources.md) 단원을 참조하십시오.
## 구문
AWS Serverless Application Model (AWS SAM) 템플릿에서이 개체를 선언하려면 다음 구문을 사용합니다.
### YAML
```
Type: AWS::Serverless::Api
Properties:
[AccessLogSetting](#sam-api-accesslogsetting): {{[AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting)}}
AlwaysDeploy: {{Boolean}}
[ApiKeySourceType](#sam-api-apikeysourcetype): {{String}}
[Auth](#sam-api-auth): {{ApiAuth}}
[BinaryMediaTypes](#sam-api-binarymediatypes): {{List}}
[CacheClusterEnabled](#sam-api-cacheclusterenabled): {{Boolean}}
[CacheClusterSize](#sam-api-cacheclustersize): {{String}}
[CanarySetting](#sam-api-canarysetting): {{[CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting)}}
[Cors](#sam-api-cors): {{String | CorsConfiguration}}
[DefinitionBody](#sam-api-definitionbody): {{JSON}}
[DefinitionUri](#sam-api-definitionuri): {{String | ApiDefinition}}
[Description](#sam-api-description): {{String}}
[DisableExecuteApiEndpoint](#sam-api-disableexecuteapiendpoint): {{Boolean}}
[Domain](#sam-api-domain): {{DomainConfiguration}}
[EndpointAccessMode](#sam-api-endpointaccessmode): {{String}}
[EndpointConfiguration](#sam-api-endpointconfiguration): {{EndpointConfiguration}}
[FailOnWarnings](#sam-api-failonwarnings): {{Boolean}}
[GatewayResponses](#sam-api-gatewayresponses): {{Map}}
MergeDefinitions: {{Boolean}}
[MethodSettings](#sam-api-methodsettings): {{MethodSettings}}
[MinimumCompressionSize](#sam-api-minimumcompressionsize): {{Integer}}
[Mode](#sam-api-mode): {{String}}
[Models](#sam-api-models): {{Map}}
[Name](#sam-api-name): {{String}}
[OpenApiVersion](#sam-api-openapiversion): {{String}}
PropagateTags: {{Boolean}}
[Policy](#sam-api-policy): {{JSON}}
[SecurityPolicy](#sam-api-securitypolicy): {{String}}
[StageName](#sam-api-stagename): {{String}}
[Tags](#sam-api-tags): {{Map}}
[TracingEnabled](#sam-api-tracingenabled): {{Boolean}}
[Variables](#sam-api-variables): {{Map}}
```
## 속성
`AccessLogSetting`
특정 단계를 위한 액세스 로그 세팅 구성에 대한 설정입니다.
*유형*: [AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting)
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::Stage` 리소스의 `[AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting)` 속성으로 직접 전달됩니다.
`AlwaysDeploy`
API에 대한 변경 사항이 감지되지 않은 경우에도 항상 API를 배포합니다.
*유형*: 부울
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은에 고유 AWS SAM 하며 CloudFormation 동등한 속성이 없습니다.
`ApiKeySourceType`
사용량 계획에 따라 측정 요청을 위한 API 키의 원본입니다. 유효한 값은 `HEADER` 및 `AUTHORIZER`입니다.
*유형*: 문자열
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::RestApi` 리소스의 `[ApiKeySourceType](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-apikeysourcetype)` 속성으로 직접 전달됩니다.
`Auth`
권한 부여를 구성하여 API Gateway API에 대한 액세스를 제어합니다.
를 사용하여 액세스를 구성하는 방법에 대한 자세한 내용은 단원을 AWS SAM 참조하십시오[AWS SAM 템플릿을 사용하여 API 액세스 제어](serverless-controlling-access-to-apis.md). 글로벌 권한 부여자를 재정의하는 방법을 보여주는 예시는 [Amazon API Gateway REST API에 대한 글로벌 권한 부여자 재정의](sam-property-function-apifunctionauth.md#sam-property-function-apifunctionauth--examples--override)에서 확인하세요.
*유형*: [APIAuth](sam-property-api-apiauth.md)
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은에 고유 AWS SAM 하며 CloudFormation 동등한 속성이 없습니다.
`BinaryMediaTypes`
API가 반환할 수 있는 MIME 유형 목록입니다. 이를 사용하여 API에 대한 바이너리 지원을 활성화할 수 있습니다.
*유형*: 목록
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::RestApi` 리소스의 `[BinaryMediaTypes](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-binarymediatypes)` 속성과 유사합니다. BinaryMediaTypes 목록이 CloudFormation 리소스와 OpenAPI 문서 모두에 추가됩니다.
`CacheClusterEnabled`
해당 단계에 대해 캐싱이 활성화되는지를 나타냅니다. 응답을 캐시하려면 `CachingEnabled`에 따라 `true`을 `MethodSettings`으로 설정해야 합니다.
*유형*: 부울
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::Stage` 리소스의 `[CacheClusterEnabled](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-cacheclusterenabled)` 속성으로 직접 전달됩니다.
`CacheClusterSize`
해당 단계의 캐시 클러스터 크기입니다.
*유형*: 문자열
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::Stage` 리소스의 `[CacheClusterSize](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-cacheclustersize)` 속성으로 직접 전달됩니다.
`CanarySetting`
canary 설정을 정규 배포 단계로 구성합니다.
*유형*: [CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting)
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::Stage` 리소스의 `[CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting)` 속성으로 직접 전달됩니다.
`Cors`
모든 API 게이트웨이 API에 대한 CORS(Cross-Origin Resource Sharing)를 관리합니다. 허용할 도메인을 문자열로 지정하거나 추가 Cors 구성을 사용하여 사전을 지정합니다.
CORS AWS SAM 를 사용하려면 OpenAPI 정의를 수정해야 합니다. `DefinitionBody`에서 인라인 OpenAPI 정의를 생성하여 CORS를 켭니다.
자세한 내용은 [API 게이트웨이 개발자 가이드](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-cors.html)의 *API 게이트웨이 REST API 리소스 활성화*를 참조하세요.
*형식*: 문자열 \| [CorsConfiguration](sam-property-api-corsconfiguration.md)
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은에 고유 AWS SAM 하며 CloudFormation 동등한 속성이 없습니다.
`DefinitionBody`
API를 설명하는 OpenAPI 사양입니다. `DefinitionUri`이나 `DefinitionBody` 어느 것도 지정되지 않은 경우 SAM은 템플릿 구성을 기반으로 `DefinitionBody`을 생성합니다.
API를 정의하는 로컬 OpenAPI 파일을 참조하려면 `AWS::Include` 변환을 사용하십시오. 자세한 내용은 [가 로컬 파일을 AWS SAM 업로드하는 방법](deploy-upload-local-files.md)을 참조하십시오.
*유형*: JSON
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::RestApi` 리소스의 `[Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body)` 속성과 유사합니다. 특정 속성이 제공되는 경우, 콘텐츠는 CloudFormation으로 전달되기 전에 DefinitionBody에 삽입되거나 수정될 수 있습니다. 속성에는 `Auth`, `BinaryMediaTypes`, `Cors`, `GatewayResponses`, `Models` 및 해당 `EventSource`에 대한 `AWS::Serverless::Function` 유형의 Api가 포함됩니다.
`DefinitionUri`
Amazon S3 Uri, 로컬 파일 경로 또는 API를 정의하는 OpenAPI 문서의 위치 객체입니다. 이 속성이 참조하는 Amazon S3 객체는 유효한 OpenAPI 파일이어야 합니다. `DefinitionUri`이나 `DefinitionBody` 어느 것도 지정되지 않은 경우 SAM은 템플릿 구성을 기반으로 `DefinitionBody`을 생성합니다.
로컬 파일 경로를 제공하는 경우 템플릿은 `sam deploy` 또는 `sam package`명령이 포함된 워크플로를 거쳐야 정의가 제대로 변환됩니다.
`DefinitionUri`이 참조하는 외부 OpenAPI 파일에서는 내장 함수가 지원되지 않습니다. 대신 `DefinitionBody`변환 포함과 함께 [ 속성](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/create-reusable-transform-function-snippets-and-add-to-your-template-with-aws-include-transform.html)을 사용하여 OpenAPI 정의를 템플릿으로 가져오십시오.
*형식*: 문자열 \| [APIdeEfinition](sam-property-api-apidefinition.md)
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::RestApi` 리소스의 `[BodyS3Location](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-bodys3location)` 속성과 유사합니다. 중첩된 Amazon S3 속성은 다르게 지정됩니다.
`Description`
Api 리소스에 대한 설명입니다.
*유형*: 문자열
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::RestApi` 리소스의 `[Description](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-description)` 속성으로 직접 전달됩니다.
`DisableExecuteApiEndpoint`
클라이언트가 기본 `execute-api` 엔드포인트를 사용하여 API를 간접 호출할 수 있는지를 지정합니다. 기본적으로 클라이언트는 기본 `https://{api_id}.execute-api.{region}.amazonaws.com`(으)로 API를 간접 호출할 수 있습니다. 클라이언트가 사용자 지정 도메인 이름을 사용하여 API를 간접 호출하도록 요구하려면 `True`을(를) 지정합니다.
*유형*: 부울
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::RestApi` 리소스의 `[ DisableExecuteApiEndpoint](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-disableexecuteapiendpoint)` 속성과 유사합니다. 이것은 `[ x-amazon-apigateway-endpoint-configuration](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-endpoint-configuration.html)` 확장의 `disableExecuteApiEndpoint` 속성으로 직접 전달되며, 이것은 ` [ Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body)` 리소스의 `AWS::ApiGateway::RestApi` 속성에 추가됩니다.
`Domain`
이 API 게이트웨이 API의 사용자 지정 도메인을 구성합니다.
*유형*: [DomainConfiguration](sam-property-api-domainconfiguration.md)
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은에 고유 AWS SAM 하며 CloudFormation 동등한 속성이 없습니다.
`EndpointConfiguration`
REST API의 엔드포인트 유형.
*유형*: [EndpointConfiguration](sam-property-api-endpointconfiguration.md)
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::RestApi` 리소스의 `[EndpointConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-endpointconfiguration)` 속성과 유사합니다. 중첩된 구성 속성들의 이름은 각각 다르게 지정됩니다.
`EndpointAccessMode`
REST API 엔드포인트의 액세스 모드입니다. 향상된 보안 정책( 접두사 )을 사용할 때 필요합니다`SecurityPolicy_`.
*유효한 값*: `STRICT` 또는 `BASIC`
*유형*: 문자열
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::RestApi` 리소스의 `[EndpointAccessMode](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-endpointaccessmode)` 속성으로 직접 전달됩니다.
`FailOnWarnings`
경고가 발생할 때 API 생성을 롤백할 것인지(`true`) 하지 않을 것인지(`false`) 지정합니다. 기본값은 `false`입니다.
*유형*: 부울
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::RestApi` 리소스의 `[FailOnWarnings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-failonwarnings)` 속성으로 직접 전달됩니다.
`GatewayResponses`
API에 대한 게이트웨이 응답을 구성합니다. 게이트웨이 응답은 API 게이트웨이에서 직접 또는 Lambda 권한 부여자를 통해 반환한 응답입니다. 자세한 내용은 [게이트웨이 응답을 위한 Api Gateway OpenAPI 확장](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-gateway-responses.html) 설명서를 참조하세요.
*유형*: 맵
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은에 고유 AWS SAM 하며 CloudFormation 동등한 속성이 없습니다.
`MergeDefinitions`
AWS SAM 는 API 이벤트 소스에서 OpenAPI 사양을 생성합니다. 이를 `AWS::Serverless::Api` 리소스에 정의된 인라인 OpenAPI 사양에 AWS SAM 병합`true`하도록를 지정합니다. 병합하지 않도록 `false`을 지정하십시오.
`MergeDefinitions`은 `DefinitionBody` 속성이 `AWS::Serverless::Api`을 정의할 것을 요구합니다. `MergeDefinitions`는 `DefinitionUri`에 관하여 `AWS::Serverless::Api` 속성과 호환되지 않습니다.
*기본값:* `false`
*유형*: 부울
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은에 고유 AWS SAM 하며 CloudFormation 동등한 속성이 없습니다.
`MethodSettings`
로깅, 지표, Cache TTL, 제한을 포함하여 API 단계의 모든 설정을 구성합니다.
*유형*: [MethodSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-stage-methodsetting.html)의 목록
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::Stage` 리소스의 `[MethodSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-methodsettings)` 속성으로 직접 전달됩니다.
`MinimumCompressionSize`
클라이언트의 Accept-Encoding 헤더를 기반으로 응답 본문을 압축할 수 있습니다. 응답 본문 크기가 구성된 임계값보다 크거나 같으면 압축이 트리거됩니다. 최대 본문 크기 임계값은 10MB(10,485,760바이트)입니다. - 지원되는 압축 유형은 gzip, deflate 및 identity입니다.
*유형*: 정수
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::RestApi` 리소스의 `[MinimumCompressionSize](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-minimumcompressionsize)` 속성으로 직접 전달됩니다.
`Mode`
이 속성은 OpenAPI를 사용하여 REST API를 정의하는 경우에만 적용됩니다. `Mode`는 API 게이트웨이에서 리소스 업데이트를 처리하는 방법을 결정합니다. 자세한 내용은 [ 리소스](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-mode)의 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html)모드 속성을 참조하세요.
*유효한 값*: `overwrite` 또는 `merge`
*유형*: 문자열
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::RestApi` 리소스의 `[Mode](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-mode)` 속성으로 직접 전달됩니다.
`Models`
API 메서드에서 사용할 스키마입니다. 이러한 스키마는 JSON 또는 YAML을 사용하여 설명할 수 있습니다. 예제 모델은 이 페이지 하단의 예제 섹션을 참조하세요.
*유형*: 맵
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은에 고유 AWS SAM 하며 CloudFormation 동등한 속성이 없습니다.
`Name`
API 게이트웨이 RestApi 리소스의 이름
*유형*: 문자열
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::RestApi` 리소스의 `[Name](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-name)` 속성으로 직접 전달됩니다.
`OpenApiVersion`
사용할 OpenApi의 버전입니다. Swagger 사양의 경우 `2.0`를 사용할 수도 있고, `3.0.1`와 같은 OpenApi 3.0 버전 중 하나를 사용할 수도 있습니다. OpenAPI에 대한 자세한 내용은 [OpenAPI 사양](https://swagger.io/specification/)을 참조하세요.
AWS SAM 는 `Stage` 기본적으로 라는 스테이지를 생성합니다. 이 속성을 임의의 유효한 값으로 설정하면 스테이지 `Stage`가 생성되지 않습니다.
*유형*: 문자열
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은에 고유 AWS SAM 하며 CloudFormation 동등한 속성이 없습니다.
`PropagateTags`
`Tags`속성의 태그를 [AWS::Serverless::Api](sam-specification-generated-resources-api.md) 생성된 리소스로 전달할지 여부를 지정합니다. 귀하의 생성된 리소스에 태그를 전파하도록 `True`을 지정합니다.
*유형*: 부울
*필수 항목 여부*: 아니요
*기본값*: `False`
*CloudFormation 호환성*:이 속성은에 고유 AWS SAM 하며 CloudFormation 동등한 속성이 없습니다.
`Policy`
API에 대한 권한이 포함된 정책 문서입니다. 정책의 ARN을 설정하려면 `!Join` 내장 함수를 구분 기호 `""`, 값 `"execute-api:/"` 및 `"*"`와 함께 사용합니다.
*유형*: JSON
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::RestApi` 리소스의 [ 정책](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-policy) 속성으로 직접 전달됩니다.
`SecurityPolicy`
REST API의 TLS 버전 및 암호 제품군입니다. 향상된 보안 정책( 접두사 `SecurityPolicy>`)을 사용하는 경우 도 설정해야 합니다`EndpointAccessMode`.
*유형*: 문자열
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::RestApi` 리소스의 `[SecurityPolicy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-securitypolicy)` 속성으로 직접 전달됩니다.
`StageName`
API 게이트웨이에서 간접 호출된 URI(Uniform Resource Identifier)의 첫 번째 경로 세그먼트로 사용하는 단계의 이름입니다.
스테이지 리소스를 참조하려면 `{{}}.Stage`를 사용하십시오. [AWS::Serverless::Api](#sam-resource-api) 리소스를 지정할 때 생성된 리소스를 참조하는 방법에 대한 자세한 내용은 [CloudFormation AWS::Serverless::Api가 지정될 때 생성되는 리소스](sam-specification-generated-resources-api.md) 섹션을 참조하세요. 생성된 CloudFormation 리소스에 대한 일반적인 내용은 섹션을 참조하세요[에 대해 생성된 CloudFormation 리소스 AWS SAM](sam-specification-generated-resources.md).
*유형*: 문자열
*필수 항목 여부:* 예
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::Stage` 리소스의 `[StageName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-stagename)` 속성과 유사합니다. SAM에서는 필수이지만 API 게이트웨이에서는 필요하지 않습니다
*추가 참고 사항*: 묵시적 API의 단계 이름은 “Prod”입니다.
`Tags`
이 API 게이트웨이 단계에 추가할 태그를 지정하는 맵(문자열 간)입니다. 태그의 유효한 키와 값에 대한 자세한 내용은 [ 사용자 가이드](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html)의 *AWS CloudFormation 리소스 태그를* 참조하세요.
*유형*: 맵
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::Stage` 리소스의 `[Tags](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-tags)` 속성과 유사합니다. SAM의 태그 속성은 키:값의 쌍으로 구성되고, CloudFormation에서는 태그 객체 목록으로 구성됩니다.
`TracingEnabled`
해당 단계에 대해 X-Ray를 사용한 활성 추적을 활성화하는지를 지시합니다. X-Ray에 대한 자세한 내용은 [API 게이트웨이 개발자 가이드](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-xray.html)의 *X-Ray를 사용하여 REST API에 대한 사용자 요청 추적*을 참조하세요.
*유형*: 부울
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::Stage` 리소스의 `[TracingEnabled](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-tracingenabled)` 속성으로 직접 전달됩니다.
`Variables`
단계 변수를 정의하는 맵(문자열 대 문자열)으로서, 여기서 변수 이름이 키가 되고 변수 값이 값이 됩니다. 변수 이름에는 영숫자 문자만 사용할 수 있습니다. 값은 정규식 `[A-Za-z0-9._~:/?#&=,-]+`과 일치해야 합니다.
*유형*: 맵
*필수 항목 여부*: 아니요
*CloudFormation 호환성*:이 속성은 `AWS::ApiGateway::Stage` 리소스의 `[Variables](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-variables)` 속성으로 직접 전달됩니다.
## 반환 값
### Ref
`Ref` 내장 함수에 이 리소스의 논리적 ID가 제공되면 그것은 기저의 API 게이트웨이 API의 ID를 반환합니다.
`Ref` 함수의 사용에 대한 자세한 내용은 *AWS CloudFormation 사용자 가이드*의 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html) 섹션을 참조하세요.
### Fn::GetAtt
`Fn::GetAtt`은 이 유형의 지정된 속성에 대한 값을 반환합니다. 다음은 사용 가능한 속성과 반환되는 샘플 값.
`Fn::GetAtt`의 사용에 대한 자세한 내용은 *AWS CloudFormation 사용자 가이드*의 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html) 섹션을 참조하세요.
`RootResourceId`
`RestApi` 리소스의 루트 리소스 ID입니다(예: `a0bc123d4e`).
## 예제
### SimpleApi예시
API 엔드포인트가 있는 Lambda 함수가 포함된 Hello World AWS SAM 템플릿 파일입니다. 이는 작동하는 서버리스 애플리케이션을 위한 전체 AWS SAM 템플릿 파일입니다.
#### YAML
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template with a simple API definition
Resources:
ApiGatewayApi:
Type: AWS::Serverless::Api
Properties:
StageName: prod
ApiFunction: # Adds a GET method at the root resource via an Api event
Type: AWS::Serverless::Function
Properties:
Events:
ApiEvent:
Type: Api
Properties:
Path: /
Method: get
RestApiId:
Ref: ApiGatewayApi
Runtime: python3.10
Handler: index.handler
InlineCode: |
def handler(event, context):
return {'body': 'Hello World!', 'statusCode': 200}
```
### ApiCors예시
Lambda 통합 및 CORS 구성과 함께 외부 Swagger 파일에 정의된 API가 있는 AWS SAM 템플릿 코드 조각입니다. 이는 [AWS::Serverless::Api](#sam-resource-api)정의를 보여주는 AWS SAM 템플릿 파일의 일부일 뿐입니다.
#### YAML
```
Resources:
ApiGatewayApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
# Allows www.example.com to call these APIs
# SAM will automatically add AllowMethods with a list of methods for this API
Cors: "'www.example.com'"
DefinitionBody: # Pull in an OpenApi definition from S3
'Fn::Transform':
Name: 'AWS::Include'
# Replace "bucket" with your bucket name
Parameters:
Location: s3://bucket/swagger.yaml
```
### ApiCognitoAuth예시
Amazon Cognito를 사용하여 API에 대한 요청을 승인하는 API가 포함된 AWS SAM 템플릿 코드 조각입니다. 이는 [AWS::Serverless::Api](#sam-resource-api)정의를 보여주는 AWS SAM 템플릿 파일의 일부일 뿐입니다.
#### YAML
```
Resources:
ApiGatewayApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
Cors: "'*'"
Auth:
DefaultAuthorizer: MyCognitoAuthorizer
Authorizers:
MyCognitoAuthorizer:
UserPoolArn:
Fn::GetAtt: [MyCognitoUserPool, Arn]
```
### ApiModels예시
모델 스키마가 포함된 API가 포함된 AWS SAM 템플릿 코드 조각입니다. 템플릿 AWS SAM 파일의 일부일 뿐이며 두 모델 스키마가 있는 [AWS::Serverless::Api](#sam-resource-api)정의를 보여줍니다.
#### YAML
```
Resources:
ApiGatewayApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
Models:
User:
type: object
required:
- username
- employee_id
properties:
username:
type: string
employee_id:
type: integer
department:
type: string
Item:
type: object
properties:
count:
type: integer
category:
type: string
price:
type: integer
```
### 캐싱 예제
API 엔드포인트가 있는 Lambda 함수가 포함된 Hello World AWS SAM 템플릿 파일입니다. API에는 하나의 리소스와 메서드에 대한 캐싱이 활성화되어 있습니다. 캐싱에 대한 자세한 내용은 *API 게이트웨이 개발자 가이드*의 [응답성 향상을 위한 API 캐싱 활성화](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-caching.html) 를 참조하세요.
#### YAML
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template with a simple API definition with caching turned on
Resources:
ApiGatewayApi:
Type: AWS::Serverless::Api
Properties:
StageName: prod
CacheClusterEnabled: true
CacheClusterSize: '0.5'
MethodSettings:
- ResourcePath: /
HttpMethod: GET
CachingEnabled: true
CacheTtlInSeconds: 300
Tags:
CacheMethods: All
ApiFunction: # Adds a GET method at the root resource via an Api event
Type: AWS::Serverless::Function
Properties:
Events:
ApiEvent:
Type: Api
Properties:
Path: /
Method: get
RestApiId:
Ref: ApiGatewayApi
Runtime: python3.10
Handler: index.handler
InlineCode: |
def handler(event, context):
return {'body': 'Hello World!', 'statusCode': 200}
```
### 프라이빗 API를 사용한 사용자 지정 도메인 예시
프라이빗 도메인에 매핑된 API 엔드포인트가 있는 Lambda 함수가 포함된 Hello World AWS SAM 템플릿 파일입니다. 이 템플릿은 VPC 엔드포인트와 프라이빗 도메인 사이에 도메인 액세스 연결을 생성합니다. 자세한 내용은 [API 게이트웨이의 프라이빗 API의 사용자 지정 도메인 이름](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-custom-domains.html)을 참조하세요.
#### YAML
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template configured with a custom domain using a private API
Parameters:
DomainName:
Type: String
Default: mydomain.example.com
CertificateArn:
Type: String
HostedZoneId:
Type: String
VpcEndpointId:
Type: String
VpcEndpointDomainName:
Type: String
VpcEndpointHostedZoneId:
Type: String
Resources:
MyFunction:
Type: AWS::Serverless::Function
Properties:
InlineCode: |
def handler(event, context):
return {'body': 'Hello World!', 'statusCode': 200}
Handler: index.handler
Runtime: python3.13
Events:
Fetch:
Type: Api
Properties:
RestApiId:
Ref: MyApi
Method: Get
Path: /get
MyApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
EndpointConfiguration:
Type: PRIVATE
VPCEndpointIds:
- !Ref VpcEndpointId
Policy:
Version: '2012-10-17 '
Statement:
- Effect: Allow
Principal: '*'
Action: execute-api:Invoke
Resource: execute-api:/*
- Effect: Deny
Principal: '*'
Action: execute-api:Invoke
Resource: execute-api:/*
Condition:
StringNotEquals:
aws:SourceVpce: !Ref VpcEndpointId
Domain:
DomainName: !Ref DomainName
CertificateArn: !Ref CertificateArn
EndpointConfiguration: PRIVATE
BasePath:
- /
Route53:
HostedZoneId: !Ref HostedZoneId
VpcEndpointDomainName: !Ref VpcEndpointDomainName
VpcEndpointHostedZoneId: !Ref VpcEndpointHostedZoneId
AccessAssociation:
VpcEndpointId: !Ref VpcEndpointId
Policy:
Version: '2012-10-17 '
Statement:
- Effect: Allow
Principal: '*'
Action: execute-api:Invoke
Resource: execute-api:/*
- Effect: Deny
Principal: '*'
Action: execute-api:Invoke
Resource: execute-api:/*
Condition:
StringNotEquals:
aws:SourceVpce: !Ref VpcEndpointId
```