# API Gateway에서 REST API에 대한 스테이지 설정
단계란 API의 스냅샷인 배포에 대한 명명된 참조입니다. [단계](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html)를 사용하여 특정 배포를 관리하고 최적화합니다. 예를 들어 캐싱을 활성화하거나, 요청 조절을 사용자 지정하거나, 로깅을 구성하거나, 스테이지 변수를 정의하거나, 테스트용 Canary 릴리스를 연결하도록 스테이지 설정을 구성할 수 있습니다. 다음 섹션에서는 스테이지를 생성하고 구성하는 방법을 보여줍니다.
## 새 단계 생성
처음 배포한 후 단계를 더 추가하고 이를 기존 배포에 연결할 수 있습니다. API Gateway 콘솔을 사용하여 새 단계를 생성하거나, API를 배포할 때 기존 단계를 선택할 수 있습니다. 일반적으로, API를 재배포하기 전에 API 배포에 새 단계를 추가할 수 있습니다. API Gateway 콘솔을 사용하여 새 스테이지를 생성하려면 다음 단계를 따릅니다.
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. 기본 탐색 창에서 API에 대해 **스테이지**를 선택합니다.
1. **스테이지** 탐색 창에서 **스테이지 생성**을 선택합니다.
1. **스테이지 이름**에 이름(예: **prod**)을 입력합니다.
**참고**
단계 이름에는 영숫자, 하이픈, 밑줄만 사용할 수 있습니다. 최대 길이는 128자입니다.
1. (선택 사항). **설명**에 간략한 설명을 입력합니다.
1. **배포**에서 이 스테이지와 연결하고자 하는 기존 API 배포의 날짜와 시간을 선택합니다.
1. **추가 설정**에서 스테이지에 대한 추가 설정을 지정할 수 있습니다.
1. **스테이지 생성**을 선택합니다.
## 스테이지 설정 수정
API 배포에 성공하면 해당 단계가 기본 설정으로 채워집니다. 콘솔 또는 API Gateway REST API를 사용하여 API 캐싱 및 로깅을 포함한 단계 설정을 변경할 수 있습니다. REST API의 기본 엔드포인트를 수정한 경우 스테이지를 업데이트하면 API의 모든 스테이지에 수정 사항이 전파됩니다. 다음 단계에서는 API Gateway 콘솔의 **스테이지 편집기**를 사용하여 이 작업을 수행하는 방법을 보여줍니다.
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. 기본 탐색 창에서 API에 대해 **스테이지**를 선택합니다.
1. **단계(Stages)** 창에서 단계 명칭을 선택합니다.
1. **스테이지 세부 정보** 섹션에서 **편집**을 선택합니다.
1. (선택 사항) **스테이지 설명**에서 설명을 편집합니다.
1. **추가 설정**에서 다음 설정을 수정합니다.
**캐시 설정**
스테이지에 API 캐싱을 활성화하려면 **프로비저닝 API 캐시**를 활성화합니다. 그런 다음 **기본 메서드 수준 캐싱**, **캐시 용량**, **캐시 데이터 암호화**, **캐시 수명 시간(TTL)** 및 키별 캐시 무효화에 대한 요구 사항을 구성합니다.
기본 메서드 수준 캐싱을 설정하거나 특정 메서드에 대해 메서드 수준 캐시를 켜야 캐시가 활성화됩니다.
캐시 설정에 관한 자세한 내용은 [API Gateway의 REST API 캐시 설정](api-gateway-caching.md) 섹션을 참조하세요.
API 단계에 대한 API 캐싱을 활성화하는 경우, AWS 계정에 API 캐싱 요금이 청구될 수 있습니다. 캐싱은 AWS 프리 티어에서 제공되지 않습니다.
**제한 설정**
이 API에 연결된 모든 메서드에 스테이지 수준 제한 대상을 설정하려면 **제한**을 켭니다.
**요율**에서 대상 요율을 입력합니다. 토큰이 토큰 버킷에 추가되는 속도(초당 요청 수)입니다. 스테이지 수준 속도는 [REST API 구성 및 실행에 대한 API Gateway 할당량](api-gateway-execution-service-limits-table.md)에 지정된 [계정 수준](api-gateway-request-throttling.md#apig-request-throttling-account-level-limits) 속도보다 클 수 없습니다.
**버스트**에 대상 버스트율을 입력합니다. 버스트율은 토큰 버킷의 용량입니다. 이렇게 하면 일정 기간 동안 목표 요율보다 더 많은 요청을 처리할 수 있습니다. 이 단계 수준 버스트율은 [REST API 구성 및 실행에 대한 API Gateway 할당량](api-gateway-execution-service-limits-table.md)에 지정된 [계정 수준](api-gateway-request-throttling.md#apig-request-throttling-account-level-limits) 버스트율보다 클 수 없습니다.
제한 속도는 엄격한 제한이 아니며 최선으로 적용됩니다. 경우에 따라 클라이언트가 설정한 대상을 초과할 수 있습니다. 비용을 제어하거나 API에 대한 액세스를 차단하기 위해 제한에 의존하지 마십시오. 비용을 모니터링하는 데 [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html)를 사용하고 API 요청을 관리하는 데 [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html)를 사용하는 것이 좋습니다.
**방화벽 및 인증서 설정**
AWS WAF 웹 ACL을 스테이지와 연결하려면 **웹 ACL** 드롭다운 목록에서 웹 ACL을 선택합니다. 원하는 경우 **Block API Request if WebACL cannot be evaluated (Fail- Close)(WebACL을 평가할 수 없는 경우 API 요청 차단(Fail-Close))**를 선택합니다.
스테이지의 클라이언트 인증서를 선택하려면 **클라이언트 인증서** 드롭다운 메뉴에서 인증서를 선택합니다.
1. **계속**을 선택합니다.
1. 변경 사항을 검토하고 **변경 사항 저장**을 선택합니다.
1. 이 API Gateway API의 이 스테이지와 연결된 모든 메서드에 대해 Amazon CloudWatch Logs를 활성화하려면 **로그 및 추적** 섹션에서 **편집**을 선택니다.
**참고**
CloudWatch Logs를 활성화하려면 API Gateway가 사용자를 대신하여 CloudWatch Logs에 정보를 기록할 수 있도록 하는 IAM 역할의 ARN도 지정해야 합니다. 이를 위해 **APIs(API)** 기본 탐색 창에서 **설정**을 선택합니다. 그런 다음 **CloudWatch 로그 역할**에 IAM 역할의 ARN을 입력합니다.
일반적인 애플리케이션 시나리오의 경우 IAM 역할은 [AmazonAPIGatewayPushToCloudWatchLogs](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAPIGatewayPushToCloudWatchLogs.html)의 관리형 정책을 연결할 수 있습니다.
IAM 역할에는 다음과 같은 신뢰 관계 설명도 포함되어야 합니다.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
CloudWatch에 대한 자세한 내용은 *[Amazon CloudWatch 사용 설명서](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)*를 참조하세요.
1. **CloudWatch Logs** 드롭다운 메뉴에서 로깅 수준을 선택합니다. 로깅 수준은 다음과 같습니다:
+ **끄기** - 이 단계에서는 로깅이 켜져 있지 않습니다.
+ **오류만** - 오류에 대해서만 로깅이 활성화됩니다.
+ **오류 및 정보 로그** - 모든 이벤트에 대해 로깅이 활성화됩니다.
1. API Gateway가 단계에 대한 데이터 추적 로깅을 CloudWatch에 보고하도록 하려면 **데이터 추적**을 선택합니다. 이 기능은 API 문제를 해결하는 데 유용하지만 민감한 데이터를 로깅할 수 있습니다.
**참고**
프로덕션 API에는 **데이터 추적**을 사용하지 않는 것이 좋습니다.
1. **세부 지표**플 선택하여 `API calls`, `Latency`, `Integration latency`, `400 errors`, `500 errors`의 API 지표를 클라우드에 보고하도록 API Gateway에 요청합니다. CloudWatch에 대한 자세한 내용은 Amazon CloudWatch 사용 설명서에서 [기본 모니터링 및 세부 모니터링](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-metrics-basic-detailed.html)을 참조하세요.
**중요**
메서드 수준 CloudWatch 지표 액세스에 대한 요금이 사용자 계정으로 청구되지만, API 수준 또는 단계 수준 지표에 대한 요금은 청구되지 않습니다.
1. 대상에 대한 액세스 로깅을 활성화하려면 **사용자 지정 액세스 로깅**을 켭니다.
1. **액세스 로그 대상 ARN**에 로그 그룹 또는 Firehose 스트림의 ARN을 입력합니다.
Firehose의 ARN 형식은 `arn:aws:firehose:{{{region}}}:{{{account-id}}}:deliverystream/amazon-apigateway-{{{your-stream-name}}}`입니다. Firehose 스트림의 이름은 `amazon-apigateway-{{{your-stream-name}}}`이어야 합니다.
1. **로그 형식**에 로그 형식을 입력합니다. 예제 로그 형식에 대한 자세한 내용은 [API Gateway에 대한 CloudWatch 로그 형식](set-up-logging.md#apigateway-cloudwatch-log-formats) 섹션을 참조하세요.
1. API 스테이지에 대해 [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) 추적을 활성화하려면 **X-Ray 추적**을 선택합니다. 자세한 내용은 [API Gateway에서 X-Ray를 사용하여 REST API에 대한 사용자 요청 추적](apigateway-xray.md) 섹션을 참조하세요.
1. [**변경 사항 저장(Save changes)**]을 선택합니다. API를 다시 배포하여 새 설정을 적용합니다.
## 스테이지 수준 설정 재정의
스테이지 수준 설정을 사용자 지정한 후 각 API 메서드에 대해 해당 설정을 재정의할 수 있습니다. 이러한 옵션 중 일부를 사용하면 AWS 계정에 추가 요금이 발생합니다.
1. 메서드 재정의를 구성하려면 보조 탐색 창 아래에서 스테이지를 확장한 다음 메서드를 선택합니다.
1. **메서드 재정의**에서 **편집**을 선택합니다.
1. 메서드 수준의 CloudWatch 설정을 켜려면 **CloudWatch Logs**에 대해 로깅 수준을 선택합니다.
1. 메서드의 데이터 추적 로깅을 활성화하려면 **데이터 추적**을 선택합니다.
**참고**
프로덕션 API에는 **데이터 추적**을 사용하지 않는 것이 좋습니다.
1. 메서드 수준의 세부 지표를 켜려면 **세부 지표**를 선택합니다. 메서드 수준 CloudWatch 지표 액세스에 대한 요금이 사용자 계정으로 청구되지만, API 수준 또는 단계 수준 지표에 대한 요금은 청구되지 않습니다.
1. 메서드 수준 제한을 켜려면 **제한**을 선택합니다. 적절한 메서드 수준 옵션을 입력합니다. 제한에 대한 자세한 내용은 [API Gateway의 처리량 향상을 위해 REST API에 대한 요청을 제한할 수 있습니다.](api-gateway-request-throttling.md)을 참조하십시오.
1. 메서드 수준 캐시를 구성하려면 **메서드 캐시 활성화**를 선택합니다. **스테이지 세부 정보**에서 기본 메서드 수준 캐싱 설정을 변경해도 이 설정에는 영향을 주지 않습니다.
1. **저장**을 선택합니다.