API Gateway CLI 및 REST API를 사용하여 사용량 계획을 생성, 구성 및 테스트

사용량 계획을 구성하기 전에 선택한 API의 메서드가 API 키를 요구하도록 설정하고, 해당 API를 단계에 배포하거나 재배포하고, API 키를 하나 이상 생성하거나 가져와야 합니다. 자세한 내용은 API Gateway REST API를 사용하여 API 키 설정 단원을 참조하세요.

사용량 계획에 추가할 API를 이미 생성한 경우, API Gateway REST API를 사용하여 사용량 계획을 구성하려면 다음 지침을 따르십시오.

기본 사용량 계획으로 마이그레이션

사용량 계획을 처음 생성하는 경우 다음 본문과 함께 account:update를 호출하여 선택한 API 키와 연결된 기존 API 단계를 사용량 계획으로 마이그레이션할 수 있습니다.

{
  "patchOperations" : [ {
    "op" : "add",
    "path" : "/features",
    "value" : "UsagePlans"
  } ]
}

API 키와 연결된 API 단계를 마이그레이션하는 방법에 대한 자세한 내용은 API Gateway 콘솔에서 기본 사용량 계획으로 마이그레이션을 참조하세요.

사용량 계획 생성

다음 절차에서는 사용량 계획을 생성하는 방법에 대해 설명합니다.

REST API로 사용량 계획을 생성하려면

1. usageplan:create를 호출하여 사용량 계획을 생성합니다. 페이로드에서 계획의 이름과 설명, 연결된 API 단계, 속도 제한, 할당량을 지정합니다.

   결과적 사용량 계획 식별자를 기록해 둡니다. 이 정보는 다음 단계에서 필요합니다.

2. 다음 중 하나를 수행하세요.

   1. usageplankey:create를 호출하여 API 키를 사용량 계획에 추가합니다. 페이로드에서 keyId와 keyType을 지정합니다.

      사용량 계획에 API 키를 더 추가하려면 한 번에 한 API 키씩 앞의 호출을 반복합니다.

   2. apikey:import를 호출하여 하나 이상의 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의 각 단계에 대하여 단 하나의 사용량 계획에만 연결할 수 있습니다.

AWS CLI를 사용하여 사용량 계획 관리

다음 코드 예제에서는 update-usage-plan 명령을 호출하여 사용량 계획에서 메서드 수준 조절 설정을 추가, 삭제 또는 수정하는 방법을 보여 줍니다.

참고

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 생성 만든 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 오류 메시지가 기록됩니다. 가끔 발생하는 이러한 오류는 무시해도 좋습니다.