# API Gateway의 REST API 사용량 계획 및 API 키
API를 생성, 테스트 및 배포한 후 API Gateway 사용량 계획을 사용하여 API를 고객을 위한 제품 혜택으로 제공할 수 있습니다. 고객이 선택한 API에 액세스할 수 있도록 사용 계획 및 API 키를 구성하고 정의된 제한 및 할당량에 따라 해당 API에 대한 요청 제한을 시작할 수 있습니다. API 또는 API 메서드 수준에서 설정할 수 있습니다.
## 사용량 계획과 API 키란 무엇인가?
*사용 계획*은 배포된 하나 이상의 API 단계 및 메서드에 액세스할 수 있는 사용자를 지정하고 선택적으로 요청 제한을 시작하도록 대상 요청 속도를 설정합니다. 계획은 API 키를 사용하여 API 클라이언트와 각 키에 대해 연결된 API 단계에 액세스할 수 있는 사용자를 식별합니다.
*API 키*는 앱 개발자 고객에게 API 액세스 권한을 부여하기 위해 배포하는 영숫자 문자열 값입니다. API 키를 [Lambda 권한 부여자](apigateway-use-lambda-authorizer.md), [IAM 역할](permissions.md) 또는 [Amazon Cognito](apigateway-integrate-with-cognito.md)와 함께 사용하여 API에 대한 액세스를 제어할 수 있습니다. API Gateway가 사용자 대신 API 키를 생성하거나, 사용자가 [CSV 파일](api-key-file-format.md)에서 API 키를 가져올 수 있습니다. API Gateway에서 API 키를 생성하거나, 외부 소스에서 API Gateway로 API 키를 가져올 수 있습니다. 자세한 내용은 [API Gateway의 REST API를 사용하여 API 키 설정](api-gateway-setup-api-keys.md) 섹션을 참조하세요.
API 키는 이름과 값을 갖습니다. ("API 키"와 "API 키 값"은 종종 서로 바꿔 사용됩니다.) 이름은 1,024자를 초과할 수 없습니다. 값은 20\$1128자의 영숫자 문자열입니다(예: `apikey1234abcdefghij0123456789`).
**중요**
API 키 값은 고유해야 합니다. 이름은 다르고 값은 동일한 두 개의 API 키를 생성하려고 하면 API Gateway는 이 두 키를 동일한 API 키로 인식합니다.
API 키는 하나 이상의 사용량 계획과 연결할 수 있습니다. 사용량 계획은 하나 이상의 단계와 연결할 수 있습니다. 그러나 지정된 API 키는 API의 각 단계에 대하여 단 하나의 사용량 계획에만 연결할 수 있습니다.
*제한 한도*는 요청 제한이 시작되어야 하는 대상 지점을 설정합니다. 이는 API 또는 API 메서드 수준에서 설정할 수 있습니다.
*할당량 한도*는 지정된 시간 간격 내에 제출할 수 있는 지정된 API 키로 최대 요청 수를 설정합니다. 사용량 계획 구성에 따라 API 키 권한 부여를 요구하도록 개별 API 메서드를 구성할 수 있습니다.
조절 및 할당량 한도는 한 가지 사용량 계획의 모든 API 단계에서 집계된 요청의 개별 API 키에 적용됩니다.
**참고**
사용량 계획 조절 및 할당량은 엄격한 제한이 아니며 최선으로 적용됩니다. 경우에 따라 클라이언트가 설정한 할당량을 초과할 수 있습니다. 비용을 제어하거나 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) 를 사용하는 것이 좋습니다.
## API 키 및 사용량 계획의 위한 모범 사례
다음은 API 키 및 사용량 계획을 사용할 때 따를 수 있는 모범 사례입니다.
**중요**
API에 대한 액세스를 제어하기 위해 인증 또는 권한 부여에 API 키를 사용하지 않도록 합니다. 사용 계획에 API가 여러 개 있는 경우, 해당 사용 계획의 한 API에 대해 유효한 API 키가 있는 사용자는 해당 사용 계획의 *모든* API에 액세스할 수 있습니다. 대신, API에 대한 액세스를 제어하려면 IAM 역할, [Lambda 권한 부여자](apigateway-use-lambda-authorizer.md) 또는 [Amazon Cognito 사용자 풀](apigateway-integrate-with-cognito.md)을 사용합니다.
API 게이트웨이에서 생성되는 API 키를 사용합니다. API 키에는 기밀 정보가 포함되어서는 안 됩니다. 클라이언트에서는 일반적으로 로깅될 수 있는 헤더에 이를 전송합니다.
+ 개발자 포털을 사용하여 API를 게시하는 경우, 지정된 사용량 계획의 모든 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)를 사용하는 것이 좋습니다.
+ 사용량 계획에 API 키를 추가한 후 업데이트 작업을 완료하는 데 몇 분 정도 걸릴 수 있습니다.
# API Gateway에서 API 키 소스 선택
사용량 계획을 API와 연결하고 API 메서드에서 API 키를 활성화할 때 API에 수신되는 모든 요청에는 [API 키](api-gateway-basic-concept.md#apigateway-definition-api-key)가 포함되어야 합니다. API Gateway는 이 키를 읽고 사용량 계획에 있는 키와 비교합니다. 일치하는 항목이 있으면 API Gateway는 계획의 요청 한도와 할당량에 따라 요청을 제한합니다. 그렇지 않으면 `InvalidKeyParameter` 예외가 발생합니다. 그 결과, 호출자는 `403 Forbidden` 응답을 수신합니다.
API Gateway API는 다음 둘 중 하나의 소스에서 API 키를 수신할 수 있습니다.
**`HEADER`**
고객에게 API 키를 배포하고 수신되는 각 요청의 `X-API-Key` 헤더로서 이 API 키를 전달하도록 요청합니다.
**`AUTHORIZER`**
Lambda 권한 부여자가 권한 부여 응답의 일부로 API 키를 반환하도록 할 수 있습니다. 권한 부여 응답에 대한 자세한 내용은 [API Gateway Lambda 권한 부여자의 출력](api-gateway-lambda-authorizer-output.md) 단원을 참조하세요.
**참고**
고려해야 할 모범 사례는 [API 키 및 사용량 계획의 위한 모범 사례](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices) 섹션을 참조하세요.
다음 절차에서는 API에 대한 API 키 소스를 선택하는 방법을 보여줍니다.
------
#### [ AWS Management Console ]
**API에 대한 API 키 소스를 선택하려면**
1. API Gateway 콘솔에 로그인합니다.
1. 기존 API를 선택하거나 새 API를 생성합니다.
1. 기본 탐색 창에서 **API 설정**을 선택합니다.
1. **API 세부 정보** 섹션에서 **편집**을 선택합니다.
1. **API 키 소스**의 드롭다운 목록에서 `Header` 또는 `Authorizer`를 선택합니다.
1. **변경 사항 저장**을 선택합니다.
------
#### [ AWS CLI ]
다음 [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) 명령은 API 키 소스를 `AUTHORIZER`로 설정하도록 API를 업데이트합니다.
```
aws apigateway update-rest-api --rest-api-id 1234123412 --patch-operations op=replace,path=/apiKeySource,value=AUTHORIZER
```
클라이언트가 API 키를 제출하도록 하려면 이전의 CLI 명령에서 `value`를 `HEADER`로 설정합니다.
------
#### [ REST API ]
API Gateway REST API를 사용하여 API의 API 키 소스를 선택하려면 다음과 같이 [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html)를 호출합니다.
```
PATCH /restapis/fugvjdxtri/ HTTP/1.1
Content-Type: application/json
Host: apigateway.us-east-1.amazonaws.com
X-Amz-Date: 20160603T205348Z
Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160603/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={sig4_hash}
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/apiKeySource",
"value" : "HEADER"
}
]
}
```
권한 부여자가 API 키를 반환하도록 하려면 앞의 `value` 입력에서 `AUTHORIZER`를 `patchOperations`로 설정합니다.
------
# API Gateway API 키 파일 형식
API Gateway는 쉼표로 분리된 값(CSV) 형식의 외부 파일에서 API 키를 가져온 다음, 가져온 키를 하나 이상의 사용량 계획과 연결할 수 있습니다. 가져온 파일에는 `Name` 및 `Key`열이 포함되어 있어야 합니다. 다음 예에서 보듯 열 헤더 이름은 대/소문자를 구분하지 않으며, 열 순서는 상관없습니다.
```
Key,name
apikey1234abcdefghij0123456789,MyFirstApiKey
```
`Key` 값은 20\$1128자여야 합니다. `Name` 값은 1024자를 초과할 수 없습니다.
또한 API 키 파일은 다음과 같이 `Description`열, `Enabled` 열 또는 `UsagePlanIds`열을 포함할 수 있습니다.
```
Name,key,description,Enabled,usageplanIds
MyFirstApiKey,apikey1234abcdefghij0123456789,An imported key,TRUE,c7y23b
```
키 1개가 둘 이상의 사용량 계획과 연결된 경우, 다음 예에서 보듯 `UsagePlanIds` 값은 큰따옴표나 작은따옴표로 묶인 사용량 계획 ID를 쉼표로 구분한 문자열입니다.
```
Enabled,Name,key,UsageplanIds
true,MyFirstApiKey,apikey1234abcdefghij0123456789,"c7y23b,glvrsr"
```
인식할 수 없는 열도 사용할 수 있지만 무시됩니다. 기본값은 빈 문자열 또는 `true` 부울 값입니다.
최신 버전으로 이전 버전을 덮어쓰면 동일한 API 키를 여러 번 가져올 수 있습니다. `key` 값이 동일한 경우 두 API 키는 동일합니다.
**참고**
고려해야 할 모범 사례는 [API 키 및 사용량 계획의 위한 모범 사례](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices) 섹션을 참조하세요.
# API Gateway의 REST API를 사용하여 API 키 설정
API 키를 설정하려면 다음 작업을 수행합니다.
+ API 메서드를 구성해 API 키를 요구합니다.
+ 리전의 API에 대해 API 키를 생성하거나 가져옵니다.
API 키를 설정하기 전에 API를 생성하여 단계에 배포해야 합니다. API 키 값을 생성한 후에는 변경할 수 없습니다.
API Gateway 콘솔을 사용하여 API를 생성하고 배포하는 방법에 대한 지침은 각각 [API Gateway에서 REST API 개발](rest-api-develop.md) 및 [API Gateway에서 REST API 배포](how-to-deploy-api.md) 단원을 참조하세요.
API 키를 만든 후에는 이를 사용량 계획에 연결해야 합니다. 자세한 내용은 [API Gateway의 REST API 사용량 계획 설정](api-gateway-create-usage-plans.md) 섹션을 참조하세요.
**참고**
고려해야 할 모범 사례는 [API 키 및 사용량 계획의 위한 모범 사례](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices) 섹션을 참조하세요.
**Topics**
+ [
## 메서드에서 API 키 한 개 요구
](#api-gateway-usage-plan-configure-apikey-on-method)
+ [
## API 키 생성
](#api-gateway-usage-plan-create-apikey)
+ [
## API 키 가져오기
](#api-gateway-usage-pan-import-apikey)
## 메서드에서 API 키 한 개 요구
다음 절차에서는 API 키를 요구하도록 API 메서드를 구성하는 방법에 대해 설명합니다.
------
#### [ AWS Management Console ]
**API 메서드를 구성해 API 키를 요구하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. API Gateway 기본 탐색 창에서 **리소스**를 선택합니다.
1. **리소스**에서 새 메서드를 생성하거나 기존 메서드를 선택합니다.
1. **메서드 요청** 탭의 **메서드 요청 설정**에서 **편집**을 선택합니다.
![\[메소드에 API 키 추가\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/api-gateway-new-console-add-key-to-method.png)
1. **API 키가 필요함**을 선택합니다.
1. **저장**을 선택합니다.
1. API를 배포하거나 다시 배포하여 요구 사항을 적용합니다.
**API 키가 필요함** 옵션이 `false`로 설정되어 있고 이전 단계를 실행하지 않는 경우, API 단계와 연결된 어떤 API 키도 해당 메서드에 사용되지 않습니다.
------
#### [ AWS CLI ]
다음 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 명령은 API 키가 필요한 `PUT` 메서드를 만듭니다.
```
aws apigateway put-method \
--rest-api-id 1234123412 \
--resource-id a1b2c3 \
--http-method PUT \
--authorization-type "NONE" \
--api-key-required
```
다음 [update-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-method.html) 명령은 API 키가 필요하도록 기존 메서드를 업데이트합니다.
```
aws apigateway update-method \
--rest-api-id 1234123412 \
--resource-id a1b2c3 \
--http-method PUT \
--patch-operations op="replace",path="/apiKeyRequired",value="true"
```
------
#### [ REST API ]
메서드에서 API 키를 요구하려면 다음 중 하나를 실시합니다.
+ [https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html)을 호출하여 메서드를 생성합니다. 요청 페이로드에서 `apiKeyRequired`를 `true`로 설정합니다.
+ [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html)를 호출하여 `apiKeyRequired`를 `true`로 설정합니다.
------
## API 키 생성
다음 절차는 API 키를 생성하는 방법을 보여줍니다. API 키를 가져오려면 이 단계를 건너뜁니다.
------
#### [ AWS Management Console ]
**API 키를 생성하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. API Gateway 기본 탐색 창에서 **API 키**를 선택합니다.
1. **API 키 생성**을 선택합니다.
![\[사용량 계획을 위한 API 키 생성\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-choose-create-api-key-from-actions-menu.png)
1. **이름**에 이름을 입력합니다.
1. (선택 사항) **설명**에 설명을 입력합니다.
1. **API 키**의 경우 **자동 생성**을 선택하여 API Gateway가 키 값을 생성하도록 하거나 **사용자 지정**을 선택하여 자체 키 값을 생성합니다.
1. **저장**을 선택합니다.
------
#### [ AWS CLI ]
다음 [create-api-key](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-api-key.html) 명령은 API 매핑을 생성합니다.
```
aws apigateway create-api-key \
--name 'Dev API key' \
--description 'API key for Devs' \
--enabled
```
------
#### [ REST API ]
[https://docs.aws.amazon.com/apigateway/latest/api/API_CreateApiKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateApiKey.html)를 호출하여 API 키를 생성합니다.
------
## API 키 가져오기
다음 절차에서는 API 키를 가져오는 방법을 설명합니다. API 키를 이미 생성한 경우 이 단계를 건너뜁니다.
------
#### [ AWS Management Console ]
**API 키를 가져오려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. 기본 탐색 창에서 **API 키**를 선택합니다.
1. **작업** 드롭다운 메뉴를 선택한 다음 **API 키 가져오기**를 선택합니다.
1. 쉼표로 구분된 키 파일을 로드하려면 **파일 선택**을 선택합니다. 텍스트 편집기에 키를 입력할 수도 있습니다. 파일 형식에 대한 자세한 내용은 [API Gateway API 키 파일 형식](api-key-file-format.md)을 참조하세요.
1. **경고 실패**를 선택해 오류 발생 시 가져오기를 중단하거나 **경고 무시**를 선택해 오류 발생 시에도 유효한 키 항목을 계속 가져옵니다.
1. API 키를 가져오려면 **가져오기**를 선택합니다.
------
#### [ AWS CLI ]
다음 [import-api-keys](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-api-keys.html) 명령은 API 키를 가져옵니다.
```
aws apigateway import-api-key \
a--body fileb://keys.csv \
--format csv
```
------
#### [ REST API ]
[https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html)를 호출하여 파일에서 API 키를 가져옵니다. 파일 형식은 [API Gateway API 키 파일 형식](api-key-file-format.md) 단원을 참조하세요.
------
새 API 키의 값은 변경할 수 없습니다. API를 생성한 후 사용량 계획을 구성합니다. 자세한 내용은 [API Gateway의 REST API 사용량 계획 설정](api-gateway-create-usage-plans.md) 섹션을 참조하세요.
# API Gateway의 REST API 사용량 계획 설정
사용량 계획을 만들기 전에 API 키를 설정했는지 확인합니다. 자세한 내용은 [API Gateway의 REST API를 사용하여 API 키 설정](api-gateway-setup-api-keys.md) 섹션을 참조하세요.
**Topics**
+ [
## API를 기본 사용량 계획으로 마이그레이션(필요한 경우)
](#api-gateway-usage-plan-migrate-to-default)
+ [
## 사용량 계획 생성
](#api-gateway-usage-plan-create)
+ [
## 사용량 계획에 스테이지 추가
](#api-gateway-usage-plan-add-stage)
+ [
## 사용량 계획에 API 키 추가
](#api-gateway-usage-plan-add-key)
## API를 기본 사용량 계획으로 마이그레이션(필요한 경우)
사용량 계획 기능이 출시된 2016년 8월 11일 *이후*에 API Gateway를 사용하기 시작한 경우, 지원되는 모든 리전에서 사용량 계획이 자동으로 활성화됩니다.
이 날짜 이전에 API Gateway를 사용하기 시작한 경우 기본 사용량 계획으로 마이그레이션해야 할 수 있습니다. 선택한 리전에서 처음으로 사용량 계획을 사용하기 전에 **Enable Usage Plans(사용량 계획 활성화)** 옵션이 메시지로 표시됩니다. 이 옵션을 활성화하면 기존 API 키에 연결된 모든 고유 API 단계에 대해 기본 사용량 계획이 생성됩니다. 조절 및 할당량 한도가 초기에 설정되어 있지 않은 기본 사용량 계획에서는 API 키와 API 단계 간의 연결이 사용량 계획에 복사됩니다. API는 전과 동일하게 동작합니다. 하지만 [ApiKey](https://docs.aws.amazon.com/apigateway/latest/api/API_ApiKey.html) `stageKeys` 속성을 사용하는 대신, [https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html) `apiStages` 속성을 사용하여 지정된 API 단계 값(`apiId` 및 `stage`)을 포함된 API 키([https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlanKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlanKey.html)를 통해)와 연결해야 합니다.
기본 사용량 계획으로 이미 마이그레이션했는지 여부를 점검하려면 [https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-account.html](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-account.html) CLI 명령을 사용하세요. 사용량 계획이 활성화되면 명령 출력에서 `features` 목록에 `"UsagePlans"` 항목이 포함됩니다.
다음과 같이 AWS CLI를 사용하여 기본 사용량 계획으로 API를 마이그레이션할 수도 있습니다.
**AWS CLI를 사용하여 기본 사용량 계획을 마이그레이션하려면**
1. CLI 명령 [https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html)를 호출합니다.
1. `cli-input-json` 파라미터에 대해 다음 JSON을 사용합니다.
```
[
{
"op": "add",
"path": "/features",
"value": "UsagePlans"
}
]
```
## 사용량 계획 생성
다음 절차에서는 사용량 계획을 생성하는 방법에 대해 설명합니다.
------
#### [ AWS Management Console ]
**사용량 계획을 생성하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. API Gateway 기본 탐색 창에서 **사용량 계획**을 선택한 다음 **사용량 계획 생성**을 선택합니다.
![\[API 사용량 계획 엔터티\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-setup.png)
1. **이름**에 이름을 입력합니다.
1. (선택 사항) **설명**에 설명을 입력합니다.
1. 기본적으로 사용량 계획에는 제한이 활성화됩니다. 사용량 계획의 **요율** 및 **버스트**를 입력합니다. 제한을 해제하려면 **조절**을 선택합니다.
1. 기본적으로 사용량 계획에서는 일정 기간 할당량이 활성화됩니다. **요청**에 사용량 계획 기간 동안 사용자가 할 수 있는 총 요청 수를 입력합니다. 할당량을 해제하려면 **할당량**을 선택합니다.
1. **사용량 계획 생성**을 선택합니다.
------
#### [ AWS CLI ]
다음 [create-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-usage-plan.html) 명령은 월초에 재설정되는 사용량 계획을 만듭니다.
```
aws apigateway create-usage-plan \
--name "New Usage Plan" \
--description "A new usage plan" \
--throttle burstLimit=10,rateLimit=5 \
--quota limit=500,offset=0,period=MONTH
```
------
#### [ REST API ]
[https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlan.html)를 호출하여 사용량 계획을 생성합니다.
------
## 사용량 계획에 스테이지 추가
다음 절차에서는 사용량 계획에 스테이지를 추가하는 방법에 대해 설명합니다.
------
#### [ AWS Management Console ]
**사용량 계획에 스테이지 추가**
1. 사용량 계획을 선택합니다.
1. **연결된 스테이지** 탭에서 **스테이지 추가**를 선택합니다.
![\[사용량 계획에 API 스테이지를 추가합니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-add-stage.png)
1. **API**에서 API를 선택합니다.
1. **스테이지**에서 스테이지를 선택합니다.
1. (선택 사항) 메서드 수준 제한을 설정하려면 다음을 수행합니다.
1. **메서드 수준 제한**을 선택한 다음 **메서즈 추가**를 선택합니다.
1. **리소스**에서 API의 리소스를 선택합니다.
1. **메서드**에서 API의 메서드를 선택합니다.
1. 사용량 계획의 **요율** 및 **버스트**를 입력합니다.
1. **사용량 계획 추가**를 선택합니다.
------
#### [ AWS CLI ]
다음 [update-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-usage-plan.html) 명령은 API의 `Prod` 스테이지를 사용량 계획에 추가합니다.
```
aws apigateway update-usage-plan \
--usage-plan-id abc123 \
--patch-operations op="add",path="/apiStages",value="a1b1c2:Prod"
```
------
#### [ REST API ]
[https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html)를 직접적으로 호출하여 사용량 계획을 업데이트합니다.
------
## 사용량 계획에 API 키 추가
다음 절차에서는 사용량 계획에 API 키를 추가하는 방법을 보여줍니다.
------
#### [ AWS Management Console ]
**사용량 계획에 키를 추가하려면**
1. **연결된 API 키** 탭에서 **API 키 추가**를 선택합니다.
![\[API 사용량 계획 엔터티\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-add-key.png)
1.
1. 기존 키를 사용량 계획에 연결하려면 **기존 키 추가**를 선택한 다음 드롭다운 메뉴에서 기존 키를 선택합니다.
1. 새 API 키를 생성하려면 **새 키 생성 및 추가**를 선택한 다음 새 키를 생성합니다. 새 키를 생성하는 방법에 대한 자세한 정보는 [API 키 생성](api-gateway-setup-api-keys.md#api-gateway-usage-plan-create-apikey) 섹션을 참조하세요.
1. **API 키 추가**를 선택합니다.
------
#### [ AWS CLI ]
다음 [create-usage-plan-key](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-usage-plan-key.html) 명령은 기존 API 키를 사용량 계획과 연결합니다.
```
aws apigateway create-usage-plan-key \
--usage-plan-id a1b2c3 \
--key-type "API_KEY" \
--key-id aaa111bbb
```
------
#### [ REST API ]
[https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlanKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlanKey.html)를 직접적으로 호출하여 기존 API 키를 사용량 계획과 연결합니다.
API 키를 가져올 때 API 키를 사용량 계획과 직접 연결할 수도 있습니다. [https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html)를 호출하여 하나 이상의 API 키를 지정된 사용량 계획에 직접 추가합니다. 요청 페이로드는 API 키 값, 연결된 사용량 계획 식별자, 그리고 사용량 계획에 대해 활성화된 키를 보여 주는 부울 플래그를 포함해야 하며, API 키 이름 및 설명도 포함할 수 있습니다.
다음 `apikey:import` 요청의 예는 3개의 API 키(`key`, `name`, `description`으로 식별됨)를 하나의 사용량 계획(`usageplanIds`로 식별됨)에 추가합니다.
```
POST /apikeys?mode=import&format=csv&failonwarnings=fase HTTP/1.1
Host: apigateway.us-east-1.amazonaws.com
Content-Type: text/csv
Authorization: ...
key,name, description, enabled, usageplanIds
abcdef1234ghijklmnop8901234567, importedKey_1, firstone, tRuE, n371pt
abcdef1234ghijklmnop0123456789, importedKey_2, secondone, TRUE, n371pt
abcdef1234ghijklmnop9012345678, importedKey_3, , true, n371pt
```
따라서 3개의 `UsagePlanKey` 리소스가 생성되고 `UsagePlan`에 추가됩니다.
이런 식으로 두 개 이상의 사용량 계획에 API 키를 추가할 수도 있습니다. 이를 위해 각 `usageplanIds` 열 값을 사용자가 선택한 사용량 계획 식별자를 포함하고 따옴표로 묶인, 쉼표로 구분된 문자열로 변경합니다(`"n371pt,m282qs"` 또는 `'n371pt,m282qs'`).
------
**참고**
API 키는 하나 이상의 사용량 계획과 연결할 수 있습니다. 사용량 계획은 하나 이상의 단계와 연결할 수 있습니다. 그러나 지정된 API 키는 API의 각 단계에 대하여 단 하나의 사용량 계획에만 연결할 수 있습니다.
# API Gateway에서 REST API에 대한 사용량 계획 유지 관리
사용량 계획을 유지 관리하려면 지정된 기간 동안 사용한 할당량과 남은 할당량을 모니터링하고, 필요하면 남은 할당량을 지정된 크기만큼 확장해야 합니다. 다음 절차에서는 할당량을 모니터링하는 방법을 설명합니다.
------
#### [ AWS Management Console ]
**사용한 할당량과 남은 할당량을 모니터링하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. API Gateway 기본 탐색 창에서 **사용량 계획**을 선택합니다.
1. 사용량 계획을 선택합니다.
1. **연결된 API 키** 탭을 선택하면 각 키에 대해 해당 기간 동안 남아 있는 요청 수를 확인할 수 있습니다.
1. (선택 사항) **사용량 데이터 내보내기**를 선택한 다음 **시작** 날짜 및 **종료** 날짜를 선택합니다. 그런 다음 내보내는 데이터 형식으로 **JSON** 또는 **CSV**를 선택하고 **내보내기**를 선택합니다.
다음은 내보낸 파일의 예입니다.
```
{
"px1KW6...qBazOJH": [
[
0,
5000
],
[
0,
5000
],
[
0,
10
]
]
}
```
이 예에서 사용량 데이터는 API 키(`px1KW6...qBazOJH`)로 식별되듯이 2016년 8월 1일부터 2016년 8월 3일 사이의 API 클라이언트의 일일 사용량 데이터를 보여 줍니다. 일일 사용량 데이터는 사용한 할당량과 남은 할당량을 보여줍니다. 이 예에서 구독자는 할당량을 아직 사용하지 않았고, API 소유자 또는 관리자가 셋째 날에 남은 할당량을 5000에서 10으로 줄였습니다.
다음 절차에서는 할당량을 수정하는 방법을 설명합니다.
**남은 할당량을 확장하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. API Gateway 기본 탐색 창에서 **사용량 계획**을 선택합니다.
1. 사용량 계획을 선택합니다.
1. **연결된 API 키** 탭을 선택하면 각 키에 대해 해당 기간 동안 남아 있는 요청 수를 확인할 수 있습니다.
1. API 키를 선택한 다음 **사용량 확장 부여**를 선택합니다.
1. **남은 요청** 할당량에 숫자를 입력합니다. 사용량 계획 기간 동안 남은 요청을 늘리거나 줄일 수 있습니다.
1. **업데이트 할당량**을 선택합니다.
------
#### [ AWS CLI ]
다음 [update-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-usage-plan.html) 예제에서는 사용량 계획에서 메서드 수준 스로틀링 설정을 추가, 제거 또는 수정합니다.
**참고**
`us-east-1`을 API에 해당하는 리전 값으로 변경해야 합니다.
개별 리소스와 메서드 조절의 속도 제한을 추가하거나 바꾸는 방법:
```
aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="replace",path="/apiStages/apiId:stage/throttle/resourcePath/httpMethod/rateLimit",value="0.1"
```
개별 리소스와 메서드 조절의 버스트 제한을 추가하거나 바꾸는 방법:
```
aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="replace",path="/apiStages/apiId:stage/throttle/resourcePath/httpMethod/burstLimit",value="1"
```
개별 리소스와 메서드에 대한 메서드 수준 조절 설정을 제거하는 방법:
```
aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="remove",path="/apiStages/apiId:stage/throttle/resourcePath/httpMethod",value=""
```
API에 대한 모든 메서드 수준 조절 설정을 제거하는 방법:
```
aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="remove",path="/apiStages/apiId:stage/throttle ",value=""
```
다음은 Pet Store 샘플 API를 사용하는 예입니다.
```
aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="replace",path="/apiStages/apiId:stage/throttle",value='"{\"/pets/GET\":{\"rateLimit\":1.0,\"burstLimit\":1},\"//GET\":{\"rateLimit\":1.0,\"burstLimit\":1}}"'
```
------
#### [ REST API ]
[https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html)를 직접적으로 호출하여 사용량 계획을 유지 관리합니다.
------
# CloudFormation를 사용하여 API 키와 사용량 계획을 생성하고 구성합니다.
CloudFormation를 사용하여 API 메서드에 API 키를 요구하고 API 사용 계획을 생성할 수 있습니다. 예제 CloudFormation 템플릿은 다음을 수행합니다.
+ `GET` 및 `POST` 메서드를 사용하여 API Gateway API를 생성합니다.
+ `GET` 및 `POST` 메서드에 대한 API 키가 필요합니다. 이 API는 들어오는 각 요청의 `X-API-KEY` 헤더에서 키를 받습니다.
+ API 키 생성
+ 매월 1,000개 요청의 월별 할당량, 초당 100개 요청의 스로틀링 속도 제한, 초당 200개 요청의 스로틀링 버스트 제한을 지정하는 사용 계획을 생성합니다.
+ `GET` 메서드에 대해 초당 50개 요청의 메서드 수준 스로틀링 속도 제한과 초당 100개 요청의 메서드 수준 스로틀링 버스트 제한을 지정합니다.
+ API 단계와 API 키를 사용량 계획에 연결합니다.
```
AWSTemplateFormatVersion: 2010-09-09
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
KeyName:
Type: String
Default: MyKeyName
Description: Name of an API key
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: keys-api
ApiKeySourceType: HEADER
PetsResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'pets'
PetsMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: GET
ApiKeyRequired: true
AuthorizationType: NONE
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
PetsMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: POST
ApiKeyRequired: true
AuthorizationType: NONE
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- PetsMethodGet
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
UsagePlan:
Type: AWS::ApiGateway::UsagePlan
DependsOn:
- ApiDeployment
Properties:
Description: Example usage plan with a monthly quota of 1000 calls and method-level throttling for /pets GET
ApiStages:
- ApiId: !Ref Api
Stage: !Sub '${StageName}'
Throttle:
"/pets/GET":
RateLimit: 50.0
BurstLimit: 100
Quota:
Limit: 1000
Period: MONTH
Throttle:
RateLimit: 100.0
BurstLimit: 200
UsagePlanName: "My Usage Plan"
ApiKey:
Type: AWS::ApiGateway::ApiKey
Properties:
Description: API Key
Name: !Sub '${KeyName}'
Enabled: True
UsagePlanKey:
Type: AWS::ApiGateway::UsagePlanKey
Properties:
KeyId: !Ref ApiKey
KeyType: API_KEY
UsagePlanId: !Ref UsagePlan
Outputs:
ApiRootUrl:
Description: Root Url of the API
Value: !Sub 'https://${Api}.execute-api.${AWS::Region}.amazonaws.com/${StageName}'
```
# OpenAPI 정의와 함께 API 키를 사용하도록 메서드를 구성합니다.
OpenAPI 정의를 사용하여 메서드에 API 키를 요구할 수 있습니다.
각 메서드에 대해 해당 메서드를 간접 호출할 때 API 키가 필요한 보안 요구 사항 객체를 생성합니다. 그런 다음 보안 정의에서 `api_key`를 정의합니다. 메서드에서 API 키를 사용량 계획에 추가하려면 관련 사용량 계획에 대한 API 키를 사용하여 UsagePlanKey를 생성합니다.
다음 예시에서는 API를 생성하고 `POST` 및 `GET` 메서드에 API 키가 필요합니다.
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"version" : "2024-03-14T20:20:12Z",
"title" : "keys-api"
},
"basePath" : "/v1",
"schemes" : [ "https" ],
"paths" : {
"/pets" : {
"get" : {
"responses" : { },
"security" : [ {
"api_key" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"type" : "http_proxy",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/",
"passthroughBehavior" : "when_no_match"
}
},
"post" : {
"responses" : { },
"security" : [ {
"api_key" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"type" : "http_proxy",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/",
"passthroughBehavior" : "when_no_match"
}
}
}
},
"securityDefinitions" : {
"api_key" : {
"type" : "apiKey",
"name" : "x-api-key",
"in" : "header"
}
}
}
```
------
#### [ OpenAPI 3.0 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "keys-api",
"version" : "2024-03-14T20:20:12Z"
},
"servers" : [ {
"url" : "{basePath}",
"variables" : {
"basePath" : {
"default" : "v1"
}
}
} ],
"paths" : {
"/pets" : {
"get" : {
"security" : [ {
"api_key" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/",
"passthroughBehavior" : "when_no_match",
"type" : "http_proxy"
}
},
"post" : {
"security" : [ {
"api_key" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/",
"passthroughBehavior" : "when_no_match",
"type" : "http_proxy"
}
}
}
},
"components" : {
"securitySchemes" : {
"api_key" : {
"type" : "apiKey",
"name" : "x-api-key",
"in" : "header"
}
}
}
}
```
------
# API Gateway의 REST API 사용량 계획 테스트
예를 들어 [자습서: 예제를 가져와 REST API 생성](api-gateway-create-api-from-example.md)에서 생성한 PetStore API를 사용해 보겠습니다. 이 API는 API 키 `Hiorr45VR...c4GJc`를 사용하도록 구성되었다고 가정합니다. 다음 단계에서는 사용량 단계를 테스트하는 방법에 대해 설명합니다.
**사용량 계획을 테스트하려면**
+ 사용량 계획에 API의 `GET` 쿼리 파라미터(예: `/pets`)가 포함된 Pets 리소스(`?type=...&page=...`)에서 `xbvxlpijch` 요청을 합니다.
```
GET /testStage/pets?type=dog&page=1 HTTP/1.1
x-api-key: Hiorr45VR...c4GJc
Content-Type: application/x-www-form-urlencoded
Host: xbvxlpijch.execute-api.ap-southeast-1.amazonaws.com
X-Amz-Date: 20160803T001845Z
Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160803/ap-southeast-1/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-api-key, Signature={sigv4_hash}
```
**참고**
API Gateway의 `execute-api` 구성 요소에 이 요청을 제출하고 필수 `Hiorr45VR...c4GJc` 헤더에 필수 API 키(예: `x-api-key`)를 제공해야 합니다.
응답이 성공하면 백엔드에서 `200 OK` 상태 코드와 요청한 결과가 포함된 페이로드가 반환됩니다. `x-api-key` 헤더 설정을 잊었거나 잘못된 키로 설정한 경우, `403 Forbidden` 응답을 받게 됩니다. 하지만 API 키를 요구하도록 메서드를 구성하지 않은 경우, `200 OK` 헤더를 올바르게 설정하든 그렇지 않든 `x-api-key` 응답을 받을 가능성이 높으며, 사용량 계획의 조절 및 할당량 제한은 우회됩니다.
경우에 따라 API Gateway가 요청에 대해 사용량 계획 조절 제한 또는 할당량을 적용할 수 없는 내부 오류가 발생할 경우, API Gateway는 조절 제한 또는 할당량을 사용량 계획에 지정된 대로 적용하지 않고 요청을 제공합니다. 하지만 CloudWatch에 `Usage Plan check failed due to an internal error` 오류 메시지를 기록합니다. 가끔 발생하는 이러한 오류는 무시해도 좋습니다.
# API 키를 사용하여 메서드를 직접적으로 호출
선택하는 API 키 원본 유형에 따라 다음 절차 중 하나를 사용하여 메서드 호출에서 헤더로 제공된 API 키 또는 권한 부여자가 반환한 API 키를 사용합니다.
**헤더로 제공된 API 키를 사용하려면**
1. 원하는 API 메서드를 사용하여 API를 생성한 다음, API를 스테이지에 배포합니다.
1. 새 사용량 계획을 만들거나 기존 사용량 계획을 선택합니다. 사용량 계획에 배포한 API 단계를 추가합니다. 사용량 계획에 API 키를 연결하거나 계획에서 기존 API 키를 선택합니다. 선택한 API 키 값을 적어 둡니다.
1. API 키를 요구하도록 API 메서드를 설정합니다.
1. 동일한 단계에 API를 다시 배포합니다. 새 단계에 API를 배포하는 경우 새 API 단계를 연결하도록 사용량 계획을 업데이트해야 합니다.
1. API 키를 사용하여 API를 직접적으로 호출합니다. 다음 예제 curl 명령은 API 키를 사용하여 API `prod` 스테이지의 `getUsers` 리소스에서 `GET` 메서드를 간접적으로 호출합니다.
```
curl -H "X-API-Key: abcd1234" 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers'
```
이제 클라이언트가 `x-api-key` 헤더에 선택한 API 키를 헤더 값으로 제공하여 API 메서드를 호출할 수 있습니다. 직접적인 호출은 다음과 같습니다.
**권한 부여자가 제공한 API 키를 사용하려면**
1. 원하는 API 메서드를 사용하여 API를 생성한 다음, API를 스테이지에 배포합니다.
1. 새 사용량 계획을 만들거나 기존 사용량 계획을 선택합니다. 사용량 계획에 배포한 API 단계를 추가합니다. 사용량 계획에 API 키를 연결하거나 계획에서 기존 API 키를 선택합니다. 선택한 API 키 값을 적어 둡니다.
1. 토큰 기반 Lambda 권한 부여자를 생성합니다. 권한 부여 응답의 루트 수준 속성으로 `usageIdentifierKey:{api-key}`를 포함시킵니다. 토큰 기반 권한 부여자를 만드는 방법에 대한 지침은 [`TOKEN` 권한 부여자 Lambda 함수 예제](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-token-lambda-function-create)을 참조합니다.
1. API 키를 요구하도록 API 메서드를 설정하고, 메서드에서 Lambda 권한 부여자를 활성화합니다.
1. 동일한 단계에 API를 다시 배포합니다. 새 단계에 API를 배포하는 경우 새 API 단계를 연결하도록 사용량 계획을 업데이트해야 합니다.
이제 클라이언트가 API 키를 명시적으로 제공하지 않고도 API 키 요구 메서드를 호출할 수 있습니다. 권한 부여자가 반환한 API 키가 자동으로 사용됩니다.