할당량 정책

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

개요

할당량은 API 프록시가 시간 범위(예: 분, 시간, 일, 주, 월) 동안 처리할 수 있는 요청 메시지의 할당량입니다. 할당량 정책은 API 프록시에서 수신하는 요청 수를 집계하는 카운터를 관장합니다. 이 기능을 통해 API 공급업체는 일정 시간 간격으로 앱에서 발생하는 API 호출 수를 제한할 수 있습니다. 예를 들어 할당량 정책을 사용하면 앱을 분당 1개 또는 월별 10,000개 요청으로 제한할 수 있습니다.

이 정책은 확장 가능한 정책이며, 이 정책을 사용하면 Apigee 라이선스에 따라 비용 또는 사용률이 영향을 받을 수 있습니다. 정책 유형 및 사용 영향에 대한 자세한 내용은 정책 유형을 참조하세요.

참고: API 프록시가 할당량 한도에 도달하면 후속 API 호출이 거부됩니다. Apigee는 할당량을 초과하는 모든 요청에 대해 오류 메시지를 반환합니다. 할당량 정책은 앱이 한도를 초과한 후 즉시 할당량을 초기화하는 기능을 제공합니다.

예를 들어 할당량이 월 10,000개 메시지로 정의되면 비율 제한이 10,000번째 메시지 후에 시작됩니다. 10,000개의 메시지가 기간의 첫째 날 또는 마지막 날에 집계되었는지는 중요하지 않습니다. 지정된 시간 간격의 마지막 시점에 할당량 카운터가 자동으로 초기화될 때까지 또는 ResetQuota 정책을 사용하여 할당량이 명시적으로 초기화될 때까지 추가적인 요청이 허용되지 않습니다.

SpikeArrest 정책이라는 할당량 정책은 사용량의 갑작스러운 증가, 버그가 있는 클라이언트, 악의적인 공격으로 인한 트래픽 급증(또는 폭발)을 방지합니다.

할당량 정책을 사용하여 1분, 1시간, 1일, 1주, 1개월 등의 기간 동안 API 프록시에서 허용하는 요청 메시지 수를 구성할 수 있습니다. API 프록시에 액세스하는 모든 앱에서 할당량을 동일하게 설정하거나 다음을 기준으로 할당량을 설정할 수 있습니다.

• API 프록시가 포함된 제품
• API를 요청하는 앱
• 앱 개발자
• 기타 여러 기준

전체 트래픽 급증에 대처하기 위해 할당량 정책을 사용하지 마세요. 이를 위해 SpikeArrest 정책을 사용합니다.

팁: 사용할 비율 제한 정책을 결정하는 데 도움이 필요하신가요? 할당량 및 SpikeArrest 정책 비교를 참조하세요.

동영상

참고: 다음 동영상에서는 Apigee UI의 기본 프록시 편집기를 보여줍니다. Apigee는 동영상에 표시된 기본 버전과 다르게 설계된 새 버전의 프록시 편집기를 도입합니다.

다음 동영상에서 할당량 정책을 통한 할당량 관리를 소개합니다.

소개

동적 할당량

분산형 및 동기식

메시지 가중치

캘린더

순환 기간

Flexi

조건부 할당량

흐름 변수

오류 처리

할당량 정책 유형

할당량 정책은 할당량 카운터를 시작되고 재설정하는 여러 가지 방식을 지원합니다. 다음 예시와 같이 <Quota> 요소의 type 속성과 함께 사용할 속성을 정의할 수 있습니다.

<Quota name="QuotaPolicy" type="calendar">
  ...
</Quota>

유효한 type 값은 다음과 같습니다.

• calendar: 명시적 시작 시간을 기반으로 할당량을 구성합니다. 각 앱의 할당량 카운터는 사용자가 설정한 <StartTime>, <Interval>, <TimeUnit> 값에 따라 새로고침됩니다.
• rollingwindow: '순환 기간'을 사용하는 할당량을 구성하여 할당량 사용량을 결정합니다. rollingwindow를 사용하면 <Interval> 및 <TimeUnit> 요소로 기간을 결정합니다(예: 1일). 요청이 수신되면 Apigee는 정확한 요청 시간(예: 오후 5시 1분)을 확인한 다음 현재 시점과 전날(1일) 오후 5시 1분 사이에 수신된 요청 수를 집계하고 해당 기간 동안 할당량이 초과되었는지 여부를 확인합니다.
• flexi: 앱에서 첫 번째 요청 메시지가 수신되면 카운터가 시작되고 <Interval> 및 <TimeUnit> 값에 따라 재설정하는 할당량을 구성합니다.

다음 표에서는 각 유형의 할당량 재설정을 설명합니다.

시간 단위	유형
	default(또는 null)	calendar	flexi
분	다음 분 시작	<StartTime> 후 1분	첫 요청 후 1분
시간	다음 정시	<StartTime> 후 1시간	첫 요청 후 1시간
일	당일 자정(GMT 기준)	<StartTime> 후 24시간	첫 요청 후 24시간
주	주말 일요일 자정(GMT 기준)	<StartTime> 후 1주	첫 요청 후 1주
월	매월 마지막 날 자정(GMT 기준)	<StartTime> 이후 1개월(28일)	첫 요청 후 1개월(28일)

참고: 할당량 정책은 시간 단위로 second도 지원합니다. 그러나 second는 Distributed=false의 정의에 따라 분산되지 않은 카운터에서만 지원됩니다. Google에서는 second를 사용하는 대신 SpikeArrest 정책을 사용하여 2단계에서 요청 트래픽 급증을 제한하는 것이 좋습니다.

type="calendar"의 경우 <StartTime>값을 지정해야 합니다.

이 테이블에는 rollingwindow 유형 값이 표시되지 않습니다. 순환 기간 할당량은 1시간 또는 1일 기간처럼 할당량 기간의 크기를 설정하여 작동합니다. 새 요청이 수신되면 정책은 지난 기간에 할당량이 초과되었는지 확인합니다.

예를 들어 1,000개의 요청을 허용하는 2시간 기간을 정의합니다. 오후 4시 45분에 새로운 요청이 수신됩니다. 정책은 지난 2시간의 할당량 수, 즉 오후 2시 45분 이후의 요청 수를 계산합니다. 2시간 동안 할당량 한도가 초과되지 않았다면 요청이 허용됩니다.

1분 후 오후 4시 46분에 또 다른 요청이 수신됩니다. 이제 정책은 오후 2시 46분 이후의 할당량 수를 계산하여 한도가 초과되었는지 확인합니다.

rollingwindow 유형의 경우 카운터가 초기화되지 않지만 요청마다 다시 계산됩니다.

할당량 카운터 이해

API 프록시 흐름에서 할당량 정책이 실행되면 할당량 카운터가 줄어듭니다. 카운터가 한도에 도달하면 이 카운터와 연결된 추가 API 호출이 허용되지 않습니다. 구성에 따라 할당량 정책에 하나 이상의 카운터가 사용될 수 있습니다. 여러 카운터가 사용되는 시기와 카운터의 동작을 이해하는 것이 중요합니다.

API 제품의 할당량 계산 방법

API 프록시가 API 제품에 포함된 경우 해당 제품에 정의된 할당량 규칙을 사용하도록 할당량 정책을 구성할 수 있습니다. API 제품은 제품 수준 또는 개별 작업 수준에서 할당량 규칙을 지정할 수 있습니다.

API 제품에 정의된 작업마다 별도의 할당량 카운터가 유지되므로 다음과 같은 규칙이 적용됩니다.

• 작업에 대한 할당량이 정의되어 있으면 작업의 할당량 규칙이 제품 수준에서 정의된 할당량 규칙보다 우선 적용됩니다. 작업마다 별도의 할당량 카운터가 생성됩니다. 작업 경로에 API 호출이 있으면 카운터가 증가합니다.
• 작업에 대한 할당량이 정의되어 있지 않으면 제품 수준 할당량 규칙이 적용됩니다. 단, 작업마다 별도의 할당량 카운터는 계속 유지됩니다. 이 경우 할당량 규칙을 제품 수준 정의에서 가져오더라도 작업이 여전히 자체 카운터를 유지한다는 점을 이해하는 것이 중요합니다.
• API 제품에 할당량 정의가 포함되지 않은 경우(제품 또는 작업 수준에서) 정책에 지정된 할당량 규칙이 적용됩니다. 단, 이 경우 API 제품의 작업마다 별도의 할당량 카운터는 유지됩니다.

다음 섹션에서는 카운터 옵션 및 동작을 자세히 설명합니다.

API 프록시 수준 카운터 구성

API 프록시 범위에서 할당량 수를 유지하도록 API 제품을 구성할 수 있습니다. 이 경우 API 제품 수준에서 지정된 할당량 구성은 자체 할당량이 지정되지 않은 모든 작업에서 공유됩니다. 이 구성을 사용하면 이 API 제품의 API 프록시 수준에서 전역 카운터를 만들 수 있습니다.

이 구성을 수행하려면 /apiproducts Apigee API를 사용하여 제품을 만들거나 업데이트하고 요청 생성 또는 업데이트에서 quotaCountScope 속성을 PROXY로 설정합니다. PROXY 구성을 사용하면 동일한 프록시와 연결되고 자체 카운터가 없는 API 제품에 정의된 모든 작업이 API 제품 수준에서 설정된 동일한 할당량 카운터를 공유합니다.

그림 1에서 작업 1과 2는 프록시 1과 연결되어 있고 작업 4와 5는 프록시 3과 연결되어 있습니다. API 제품에서 quotaCounterScope=PROXY가 설정되므로 이러한 각 작업은 API 제품 수준 할당량 설정을 공유합니다. 이러한 작업은 동일한 할당량 구성을 공유하지만 프록시 연결에 따라 별도의 카운터를 사용합니다. 반면 작업 3에는 자체 할당량 구성이 설정되어 있으므로 quotaCounterScope 플래그의 영향을 받지 않습니다.

그림 1: quotaCounterScope 플래그 사용

quotaCounterScope=PROXY인 경우 일부 프록시 리소스에는 할당량 구성이 설정되어 있고 다른 리소스에는 설정되어 있지 않은 작업을 구성하지 않는 것이 좋습니다. 예를 들어 그림 1에서 작업 4에 자체 할당량 구성이 있지만 작업 5에 없는 경우 이 구성은 피해야 할 패턴으로 간주됩니다.

기본적으로 작업에 대한 할당량이 정의되어 있지 않으면 제품 수준 할당량 규칙이 적용됩니다. 단, 작업마다 별도의 할당량 카운터는 계속 유지됩니다.

사용 중인 API 제품이 없는 경우 할당량 계산 방법

API 프록시와 연결된 API 제품이 없으면 할당량 정책은 API 프록시에서 참조되는 횟수와 관계없이 단일 카운터를 유지합니다. 할당량 카운터의 이름은 정책의 name 속성을 기반으로 합니다.

예를 들어 요청 한도가 5개인 MyQuotaPolicy라는 할당량 정책을 만들고 API 프록시의 여러 흐름(흐름 A, B, C)에 배치합니다. 이 정책은 여러 흐름에서 사용되지만 모든 정책 인스턴스에서 업데이트하는 단일 카운터를 유지합니다.

• 흐름 A 실행 -> MyQuotaPolicy가 실행되고 카운터 = 1
• 흐름 B 실행 -> MyQuotaPolicy가 실행되고 카운터 = 2
• 흐름 A 실행 -> MyQuotaPolicy가 실행되고 카운터 = 3
• 흐름 C 실행 -> MyQuotaPolicy가 실행되고 카운터 = 4
• 흐름 A 실행 -> MyQuotaPolicy가 실행되고 카운터 -= 5

할당량 카운터가 한도에 도달하여 3개 흐름에 대한 다음 요청이 거부됩니다.

API 프록시 흐름에서 둘 이상의 위치에서 동일한 할당량 정책을 사용하면 의도치 않게 할당량이 빠르게 실행될 수 있으며 이러한 사용은 안티패턴 소개에 설명된 안티패턴입니다.

또는 API 프록시에서 여러 할당량 정책을 정의하고 각 흐름마다 다른 정책을 사용할 수 있습니다. 각 할당량 정책은 정책의 name 속성에 따라 자체 카운터를 유지합니다.

정책 구성을 통해 여러 카운터 만들기

할당량 정책의 <Class> 또는 <Identifier> 요소를 사용하여 단일 정책에 여러 개의 고유한 카운터를 정의할 수 있습니다. 이러한 요소를 사용하여 단일 정책은 요청을 실행하는 앱, 요청을 실행하는 앱 개발자, 클라이언트 ID 또는 기타 클라이언트 식별자 등에 따라 다양한 카운터를 유지할 수 있습니다. <Class> 또는 <Identifier> 요소 사용에 대한 자세한 내용은 위의 예시를 참조하세요.

참고: 할당량 카운터는 할당량 정책이 포함된 API 프록시로 범위가 지정됩니다. 여러 API 프록시에 이름이 같은 할당량 정책이 포함된 경우 여러 카운터가 별도로 유지됩니다.

시간 표기법

모든 할당량 시간은 협정 세계시(UTC) 시간대로 설정됩니다.

할당량 시간 표기법은 국제 표준 ISO 8601에 정의된 국제 표준 날짜 표기법을 따릅니다.

날짜는 YYYY-MM-DD 형식으로 년, 월, 일로 정의됩니다. 예를 들어 2021-02-04는 2021년 2월 4일을 나타냅니다.

시간대는 hours:minutes:seconds 형식으로 시간, 분, 초로 정의됩니다. 예를 들어 23:59:59는 자정 1초 전을 나타냅니다.

00:00:00 및 24:00:00의 두 가지 표기법으로 한 날짜에 연결할 수 있는 두 시점의 자정을 구분할 수 있습니다. 따라서 2021-02-04 24:00:00은 2021-02-05 00:00:00과 동일한 날짜와 시간을 나타냅니다. 후자가 일반적으로 선호되는 표기법입니다.

API 제품 구성에서 할당량 설정 가져오기

API 제품 구성에서 할당량 한도를 설정할 수 있습니다. 이러한 한도는 할당량을 자동으로 적용하지 않습니다. 대신 할당량 정책에서 제품 할당량 설정을 참조할 수 있습니다. 다음은 할당량 정책이 참조하는 제품에 할당량을 설정할 때의 몇 가지 장점입니다.

• 할당량 정책은 API 제품의 모든 API 프록시에서 동일한 설정을 사용할 수 있습니다.
• API 제품의 할당량 설정에 대한 런타임을 변경할 수 있으며, 해당 값을 참조하는 할당량 정책에 자동으로 업데이트된 할당량 값이 포함됩니다.

API 제품의 할당량 설정 사용에 대한 자세한 내용은 위의 '동적 할당량' 예시를 참조하세요.

할당량 한도로 API 제품을 구성하는 방법에 대한 자세한 내용은 API 제품 만들기를 참조하세요.

공유 할당량 카운터 구성

일반적으로 할당량 정책은 API 프록시로 전송되는 모든 요청을 계산합니다. 일부 사용 사례에서는 수신 요청 할당량 계산을 적용해야 할 수 있지만 지정된 조건을 충족하는 대상 응답에 대해 할당량 수를 늘려야 할 수 있습니다. <SharedName>, <CountOnly>, <EnforceOnly>의 3개 할당량 정책 요소를 함께 사용하면 수신 요청 할당량을 적용하고 지정한 조건에 따라 대상 응답을 계산하도록 할당량 정책을 맞춤설정할 수 있습니다.

예를 들어 백엔드 대상의 응답에 200 HTTP 상태 코드가 포함된 API 프록시에 대해 할당량 카운터를 증분한다고 가정해보세요. 이러한 특수화된 계산을 수행하기 위해서는 다음을 수행합니다.

• 이름 값으로 설정된 <SharedName> 요소 및 true로 설정된 <EnforceOnly> 요소를 사용하여 ProxyEndpoint 요청 흐름에 할당량 정책을 추가합니다.
• <SharedName> 요소가 첫 번째 정책과 동일한 이름 값으로 설정되고 <CountOnly> 요소가 true로 설정된 ProxyEndpoint 응답 흐름에 다른 할당량 정책을 추가합니다.
• 할당량 카운터를 증가시킬 조건을 설정하는 조건부 단계에 두 번째 할당량 정책(<CountOnly>가 포함된 정책)을 배치합니다.

공유 카운터 사용 방법을 보여주는 예시는 샘플 섹션의 공유 카운터를 참조하세요.

샘플

이러한 정책 코드 샘플은 다음과 같은 방법으로 할당량 기간을 시작하고 종료하는 방법을 보여줍니다.

동적 할당량 추가

<Quota name="CheckQuota">
  <Interval ref="verifyapikey.verify-api-key.apiproduct.developer.quota.interval">1</Interval>
  <TimeUnit ref="verifyapikey.verify-api-key.apiproduct.developer.quota.timeunit">hour</TimeUnit>
  <Allow count="200" countRef="verifyapikey.verify-api-key.apiproduct.developer.quota.limit"/>
</Quota>

동적 할당량을 사용 설정하면 할당량 정책에 전달된 정보를 기반으로 여러 할당량 설정을 시행하는 단일 할당량 정책을 구성할 수 있습니다. 이 컨텍스트에서 할당량 설정의 또 다른 용어는 서비스 요금제입니다. 동적 할당량은 앱의 서비스 요금제를 확인한 후 이러한 설정을 적용합니다.

참고: 요소의 값과 참조를 모두 지정하면 참조가 우선순위를 가져옵니다. 런타임 시 참조가 결정되지 않으면 값이 사용됩니다.

예를 들어 API 제품을 만들 때 허용되는 할당량 한도, 시간 단위, 간격을 선택적으로 설정할 수 있습니다. 단, API 제품에 이러한 값을 설정해도 API 프록시에 적용되지는 않습니다. 또한 이러한 값을 읽는 API 프록시에 할당량 정책을 추가해야 합니다. 자세한 내용은 API 제품 만들기를 참조하세요.

위의 예시에서 할당량 정책이 포함된 API 프록시는 verify-api-key라는 VerifyAPIKey 정책을 사용하여 요청에서 전달된 API 키의 유효성을 검사합니다. 그런 다음 할당량 정책은 VerifyAPIKey 정책의 흐름 변수에 액세스하여 API 제품에 설정된 할당량 값을 읽습니다.

또 다른 옵션은 개별 개발자 또는 앱에 커스텀 속성을 설정한 다음 할당량 정책에서 해당 값을 읽는 것입니다. 예를 들어 개발자별로 다른 할당량 값을 설정하려면 한도, 시간 단위, 간격을 포함하는 커스텀 속성을 설정합니다. 그런 다음 아래와 같이 할당량 정책에서 이 값을 참조합니다.

<Quota name="DeveloperQuota">
  <Identifier ref="verifyapikey.verify-api-key.client_id"/>
  <Interval ref="verifyapikey.verify-api-key.developer.timeInterval"/>
  <TimeUnit ref="verifyapikey.verify-api-key.developer.timeUnit"/>
  <Allow countRef="verifyapikey.verify-api-key.developer.limit"/>
</Quota>

또한 이 예시에서는 VerifyAPIKey 흐름 변수를 사용하여 개발자에 설정한 커스텀 속성을 참조합니다.

모든 변수를 사용하여 할당량 정책의 매개변수를 설정할 수 있습니다. 이러한 변수의 출처는 다음과 같습니다.

• 흐름 변수
• API 제품, 앱 또는 개발자의 속성
• 키 값 맵(KVM)
• 헤더, 쿼리 매개변수, 양식 매개변수 등

각 API 프록시에 대해 다른 모든 프록시의 다른 할당량 정책과 동일한 변수를 참조하는 할당량 정책을 추가하거나, 할당량 정책이 해당 정책 및 프록시에 고유한 변수를 참조할 수 있습니다.

시작 시간

<Quota name="QuotaPolicy" type="calendar">
  <StartTime>2021-02-18 10:30:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

type이 calendar로 설정된 할당량에는 명시적인 <StartTime> 값을 정의해야 합니다. 시간 값은 현지 시간이 아니라 GMT 시간입니다. calendar 유형의 정책에 <StartTime> 값을 제공하지 않으면 Apigee에서 오류가 발생합니다.

각 앱의 할당량 카운터는 <StartTime>, <Interval>, <TimeUnit> 값에 따라 새로고침됩니다. 이 예시에서 할당량은 2021년 2월 18일 오전 10시 30분(GMT)에 집계되며 5시간마다 새로고침됩니다. 따라서 다음 새로고침은 2021년 2월 18일 오후 3시 30분(GMT)입니다.

액세스 카운터

<Quota name="QuotaPolicy">
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

API 프록시는 할당량 정책에서 설정한 흐름 변수에 액세스할 수 있습니다. API 프록시에서 이러한 흐름 변수에 액세스하여 조건부 처리를 수행하거나, 할당량 한도에 가까워질 때 정책을 모니터링하고, 현재 할당량 카운터를 앱에 반환하거나 그 밖에 다른 이유로 활용할 수 있습니다.

정책의 흐름 변수는 정책 name 속성을 기반으로 하므로 위에 있는 <Quota>라는 정책에는 다음 형식의 흐름 변수에 액세스합니다.

• ratelimit.QuotaPolicy.allowed.count: 허용된 개수입니다.
• ratelimit.QuotaPolicy.used.count: 현재 카운터 값입니다.
• ratelimit.QuotaPolicy.expiry.time: 카운터가 초기화되는 UTC 시간입니다.

아래 설명된 여러 다른 흐름 변수에 액세스할 수 있습니다.

예를 들어 다음 AssignMessage 정책을 사용하여 할당량 흐름 변수의 값을 응답 헤더로 반환할 수 있습니다.

<AssignMessage continueOnError="false" enabled="true" name="ReturnQuotaVars">
  <AssignTo createNew="false" type="response"/>
  <Set>
    <Headers>
      <Header name="QuotaLimit">{ratelimit.QuotaPolicy.allowed.count}</Header>
      <Header name="QuotaUsed">{ratelimit.QuotaPolicy.used.count}</Header>
      <Header name="QuotaResetUTC">{ratelimit.QuotaPolicy.expiry.time}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

공유 카운터

다음 예시에서는 대상 응답이 HTTP 상태 200일 때에도 할당량 카운터가 증분되도록 API 프록시 공유 카운터를 구성하는 방법을 보여줍니다. 두 할당량 정책 모두 동일한 <SharedName> 값이 사용되기 때문에 두 할당량 정책 모두 동일한 할당량 카운터를 공유합니다. 자세한 내용은 공유 할당량 카운터 구성을 참조하세요.

ProxyEndpoint 구성 예시:

<ProxyEndpoint name="default">
    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Name>Enforce-Only</Name>  <!--First quota policy enforces quota count -->
            </Step>
        </Request>
        <Response>
            <Step>
                <Name>Count-Only</Name>   <!-- Second quota policy counts quota if call is successful -->
                <Condition>response.status.code = 200</Condition>
            </Step>
        </Response>
        <Response/>
    </PreFlow>
    <Flows/>
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <HTTPProxyConnection>
        <BasePath>/quota-shared-name</BasePath>
    </HTTPProxyConnection>
    <RouteRule name="noroute"/>
</ProxyEndpoint>

첫 번째 할당량 정책 예시:

<Quota continueOnError="false" enabled="true" name="Enforce-Only" type="rollingwindow">
    <DisplayName>Enforce-Only</DisplayName>
    <Properties/>
    <Allow count="5"/>
    <Interval>2</Interval>
    <TimeUnit>minute</TimeUnit>
    <Distributed>true</Distributed>
    <Synchronous>true</Synchronous>
    <EnforceOnly>true</EnforceOnly>
    <SharedName>common-proxy</SharedName>  <!-- Notice that SharedName value is the same for both Quota policies -->
</Quota>

두 번째 할당량 정책 예시:

<Quota continueOnError="false" enabled="true" name="Count-Only" type="rollingwindow">
    <DisplayName>Count-Only</DisplayName>
    <Properties/>
    <Allow count="5"/>
    <Interval>2</Interval>
    <TimeUnit>minute</TimeUnit>
    <Distributed>true</Distributed>
    <Synchronous>true</Synchronous>
    <CountOnly>true</CountOnly>
    <SharedName>common-proxy</SharedName>  <!-- Same name as the first policy -->
</Quota>

참고: 동일한 할당량 정책에서 <Class> 요소와 <Identifier> 요소를 모두 사용할 수는 없습니다.

첫 번째 요청

<Quota name="MyQuota">
  <Interval>1</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="10000"/>
</Quota>

이 샘플 코드를 사용하여 시간당 호출 할당량 10,000개를 적용합니다. 이 정책은 매 시간 할당량 카운터를 재설정합니다. 한 시간이 끝나기 전에 카운터가 호출 할당량 10,000개에 도달하면 10,000개를 초과하는 호출이 거부됩니다.

예를 들어 카운터가 2021-07-08 07:00:00에서 시작되면 2021-07-08 08:00:00의 0으로 재설정됩니다(시작 시간에서 1시간). 첫 번째 메시지가 2021-07-08 07:35:28에 수신되고 2021-07-08 08:00:00 이전에 메시지 수가 10,000개에 도달하면 이 수를 초과하는 호출은 매 시간 집계가 재설정될 때까지 거부됩니다.

카운터 초기화 시간은 <Interval>과 <TimeUnit>의 조합을 기반으로 합니다. 예를 들어 <Interval>을 12로, <TimeUnit>을 시간으로 설정하면 카운터는 12시간마다 초기화됩니다. <TimeUnit>을 분, 시간, 일, 주 또는 월로 설정할 수 있습니다.

이 정책은 API 프록시의 여러 위치에서 참조할 수 있습니다. 예를 들어 프록시 PreFlow에 배치하여 모든 요청에 실행되도록 할 수 있습니다. 또는 API 프록시의 여러 흐름에 배치할 수 있습니다. 프록시의 여러 위치에서 이 정책을 사용하는 경우 정책의 모든 인스턴스가 업데이트하는 단일 카운터가 유지됩니다.

또는 API 프록시에서 여러 할당량 정책을 정의할 수 있습니다. 각 할당량 정책은 정책의 name 속성에 따라 자체 카운터를 유지합니다.

식별자 설정

<Quota name="QuotaPolicy" type="calendar">
  <Identifier ref="request.header.clientId"/>
  <StartTime>2021-02-18 10:00:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

기본적으로 할당량 정책은 요청의 출처에 관계없이 API 프록시에 대한 단일 카운터를 정의합니다. 또는 <Identifier> 속성의 값에 따라 별개의 카운터를 유지하기 위해 할당량 정책과 함께 <Identifier> 속성을 사용할 수 있습니다.

예를 들어 <Identifier> 태그를 사용하여 모든 클라이언트 ID에 별도의 카운터를 정의할 수 있습니다. 그런 다음 프록시 요청에서 위 예시와 같이 클라이언트 앱이 clientID가 포함된 헤더를 전달합니다.

<Identifier> 속성에 흐름 변수를 지정할 수 있습니다. 예를 들어 이름이 id인 쿼리 매개변수에 고유 식별자가 포함되도록 지정할 수 있습니다.

<Identifier ref="request.queryparam.id"/>

VerifyAPIKey 정책을 사용하여 API 키를 검증하는 경우 또는 OAuth 토큰이 있는 OAuthV2 정책을 사용하는 경우 API 키 또는 토큰의 정보를 사용하여 동일한 할당량 정책에 대한 개별 카운터를 정의할 수 있습니다. 예를 들어 다음 <Identifier> 태그는 verify-api-key라는 VerifyAPIKey 정책의 client_id 흐름 변수를 사용합니다.

<Identifier ref="verifyapikey.verify-api-key.client_id"></Identifier>

이제 고유한 client_id 값이 할당량 정책에 자체 카운터를 정의합니다.

클래스

<Quota name="QuotaPolicy">
  <Interval>1</Interval>
  <TimeUnit>day</TimeUnit>
  <Allow>
    <Class ref="request.header.developer_segment">
      <Allow class="platinum" count="10000"/>
      <Allow class="silver" count="1000" />
    </Class>
  </Allow>
</Quota>

클래스 기반 할당량 수를 사용하여 할당량 한도를 동적으로 설정할 수 있습니다. 이 예시에서 할당량 한도는 각 요청으로 전달된 developer_segment 헤더 값에 따라 결정됩니다. 변수의 값은 platinum 또는 silver일 수 있습니다. 헤더에 잘못된 값이 있으면 정책은 할당량 위반 오류를 반환합니다.

참고: 동일한 할당량 정책에서 <Class> 요소와 <Identifier> 요소를 모두 사용할 수는 없습니다.

---

<Quota> 요소

다음은 <Quota>의 속성과 하위 요소입니다. 일부 요소 조합은 서로 배타적이거나 필수 요소가 아닙니다. 구체적인 사용은 샘플을 참조하세요.

my-verify-key-policy라고 하는 VerifyAPIKey 정책이 요청에서 앱의 API 키를 확인하는 데 사용되는 경우 아래의 verifyapikey.my-verify-key-policy.apiproduct.* 변수가 기본적으로 제공됩니다. 변수 값은 API 제품 구성에서 할당량 설정 가져오기에 설명된 대로 키가 연결된 API 제품의 할당량 설정에서 가져옵니다.

<Quota continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="UPPER_REQUEST_LIMIT" countRef="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.limit"/>
   <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="UPPER_LIMIT_DURING_PEAK"/>
        <Allow class="off_peak_time" count="UPPER_LIMIT_DURING_OFFPEAK"/>
      </Class>
   </Allow>
   <Interval ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.interval">1</Interval>
   <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2021-7-16 12:00:00</StartTime>
   <Distributed>false</Distributed>
   <Synchronous>false</Synchronous>
   <AsynchronousConfiguration>
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
      <SyncMessageCount>5</SyncMessageCount>
   </AsynchronousConfiguration>
   <Identifier/>
   <MessageWeight/>
   <UseQuotaConfigInAPIProduct>
     <DefaultConfig>
       <Allow>
          <Class ref="request.queryparam.time_variable">
            <Allow class="peak_time" count="5000"/>
            <Allow class="off_peak_time" count="1000"/>
          </Class>
       </Allow>
       <Interval ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.interval">1</Interval>
       <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.timeunit">month</TimeUnit>
     </DefaultConfig>
   </UseQuotaConfigInAPIProduct>
   </SharedName>
   </CountOnly>
   </EnforceOnly>
</Quota>

다음 속성은 이 정책에만 해당합니다.

속성	설명	기본값	Presence
유형	할당량 정책 유형을 설정하여 할당량 카운터가 할당량 사용량을 확인하는 시기와 방법뿐만 아니라 할당량 카운터를 재설정하는 방법을 결정합니다. type을 설정하지 않으면 카운터가 분/시/일/주/월 초에 시작됩니다. 유효한 값으로 다음이 포함되어 있습니다. calendar rollingwindow flexi 각 유형에 대한 자세한 설명은 할당량 정책 유형을 참조하세요.	해당 사항 없음	선택사항

다음 표는 모든 정책 상위 요소의 공통 속성에 대해 설명합니다.

속성	설명	기본값	Presence
name	정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다. 원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.	해당 사항 없음	필수
continueOnError	정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다. 참조: 오류 규칙은 오류 상태(continueOnError)에서만 트리거됨 현재 흐름 내에서 오류 처리	false	선택사항
enabled	정책을 시행하려면 true로 설정합니다. 정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.	true	선택사항
async	이 속성은 지원이 중단되었습니다.	false	지원 중단됨

<DisplayName> 요소

name 속성 외에도 이 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름으로 라벨을 지정합니다.

<DisplayName>Policy Display Name</DisplayName>

기본값	해당 사항 없음 이 요소를 생략하면 정책 name 속성 값이 사용됩니다.
Presence	선택사항
유형	문자열

<Allow>

할당량 수 한도를 지정합니다. 정책의 카운터가 이 한도 값에 도달하면 카운터가 초기화될 때까지 후속 호출이 거부됩니다.

흐름 변수를 기반으로 <Allow> 요소를 조건부화하는 <Class> 요소도 포함할 수 있습니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	정수 또는 복합 유형
상위 요소	<Quota>
하위 요소	<Class>

다음은 <Allow> 요소를 설정하는 세 가지 방법입니다.

<Allow count="2000"/>

<Allow countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>

<Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> 

count와 countRef를 모두 지정하면 countRef가 우선순위를 갖습니다. countRef가 런타임에 확인되지 않으면 count의 값이 사용됩니다.

<Class> 요소를 <Allow> 하위 요소로 지정하여 흐름 변수를 기반으로 정책의 허용 수를 결정할 수도 있습니다. Apigee는 흐름 변수 값을 다음과 같이 <Allow> 요소의 class 속성과 일치시킵니다.

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

다음 표에는 <Allow> 속성이 나와 있습니다.

속성	설명	기본값	Presence
count	할당량의 메시지 수를 지정하는 데 사용합니다. 예를 들어 count 속성 값 100, Interval 1, TimeUnit 월은 월별 메시지 100개 할당량을 지정합니다.	2000	선택사항
countRef	할당량에 대한 메시지 수가 포함된 흐름 변수를 지정하는 데 사용합니다. countRef는 count 속성보다 우선합니다.	없음	선택사항

<Class>

흐름 변수 값을 기반으로 <Allow> 요소 값을 조건부화할 수 있습니다. 정책은 <Class>의 서로 다른 <Allow> 하위 태그마다 다른 카운터를 유지합니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	복합 유형
상위 요소	<Allow>
하위 요소	<Allow>(<Class>의 하위 요소)

<Class> 요소를 사용하려면 ref 속성을 사용하여 흐름 변수를 <Class> 요소로 지정합니다. 그런 다음 흐름 변수 값으로 <Allow> 하위 요소 중 하나를 선택하여 허용되는 정책 수를 결정합니다. Apigee는 흐름 변수 값을 다음과 같이 <Allow> 요소의 class 속성과 일치시킵니다.

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

이 예시에서 현재 할당량 카운터는 각 요청과 함께 전달된 time_variable 쿼리 매개변수의 값에 따라 결정됩니다. 변수의 값은 peak_time 또는 off_peak_time일 수 있습니다. 쿼리 매개변수에 잘못된 값이 있으면 정책은 할당량 위반 오류를 반환합니다.

참고: 동일한 할당량 정책에서 <Class> 요소와 <Identifier> 요소를 모두 사용할 수는 없습니다.

다음 표에는 <Class> 속성이 나와 있습니다.

속성	설명	기본값	Presence
ref	할당량에 대한 할당량 클래스가 포함된 흐름 변수를 지정하는 데 사용합니다.	없음	필수

<Allow>(<Class>의 하위 요소)

<Class> 요소에서 정의한 할당량 카운터 한도를 지정합니다. 정책은 <Class>의 서로 다른 <Allow> 하위 태그마다 다른 카운터를 유지합니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	복합 유형
상위 요소	<Class>
하위 요소	없음

예를 들면 다음과 같습니다.

    <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow count="5000"/>
        <Allow count="1000"/>
      </Class>
    </Allow>

이 예시에서 할당량 정책은 peak_time 및 off_peak_time이라는 두 가지 할당량 카운터를 유지합니다. <Class> 예시와 같이 전달된 쿼리 매개변수에 따라 사용되는 항목이 다릅니다.

다음 표에는 <Allow> 속성이 나와 있습니다.

속성	설명	기본값	Presence
class	할당량 카운터의 이름을 정의합니다.	없음	필수
count	카운터의 할당량 한도를 지정합니다.	없음	필수

<Interval>

할당량이 계산되는 기간을 지정합니다.

기본값	해당 사항 없음
필수 여부	필수
유형	정수
상위 요소	<Quota>
하위 요소	없음

Apigee에서 할당량 사용을 계산하는 기간을 결정하기 위해 지정하는 <TimeUnit>(분, 시, 일, 주, 월)과 페어링할 정수(예: 1, 2, 5, 60 등)를 지정하는 데 사용합니다.

예를 들어, hour의 <TimeUnit>와 함께 간격이 24이면 할당량이 24시간 동안 계산된다는 의미입니다.

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>

다음 표에는 <Interval> 속성이 나와 있습니다.

속성	설명	기본값	Presence
ref	할당량의 간격을 포함하는 흐름 변수를 지정하는 데 사용합니다. ref는 명시적 간격 값보다 우선합니다. 참조 및 값이 모두 지정된 경우 참조가 우선순위를 갖습니다. ref가 런타임에 확인되지 않으면 값이 사용됩니다.	없음	선택사항

<TimeUnit>

할당량에 적용되는 시간 단위를 지정합니다.

기본값	해당 사항 없음
필수 여부	필수
유형	문자열
상위 요소	<Quota>
하위 요소	없음

minute, hour, day, week, month, year에서 선택합니다.

참고: 할당량 정책은 시간 단위로 second도 지원합니다. 하지만 second는 분산되지 않은 카운터에서만 지원됩니다(<Distributed>이 false로 설정된 경우). Google에서는 여기에 second 값을 사용하는 대신 SpikeArrest 정책을 사용하여 2차 수준에서 요청 트래픽 급증을 제한하는 것이 좋습니다.

예를 들어, TimeUnit이 hour이고 Interval이 24이면 할당량이 24시간 동안 계산된다는 의미입니다.

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>

기본값:	없음
Presence:	필수
유형:	문자열

다음 표에는 <TimeUnit> 속성이 나와 있습니다.

속성	설명	기본값	Presence
ref	할당량의 시간 단위가 포함된 흐름 변수를 지정합니다. ref는 명시적 간격 값보다 우선합니다. ref가 런타임에서 확인되지 않으면 내부 값이 사용됩니다.	없음	선택사항

<StartTime>

type을 calendar로 설정하면 요청을 수신한 앱과 관계없이 할당량 카운터가 시작되는 날짜와 시간을 지정합니다.

기본값	해당 사항 없음
필수 여부	선택사항(type이 calendar로 설정된 경우에는 필수)
유형	ISO 8601 날짜 및 시간 형식의 문자열입니다.
상위 요소	<Quota>
하위 요소	없음

type이 calendar으로 설정되면 명시적인 <StartTime>을 제공해야 하며 흐름 변수에 대한 참조를 사용할 수 없습니다. type 값이 설정되어 있지 않은 상태에서 <StartTime> 값을 지정하면 Apigee에서 오류가 발생합니다.

예를 들면 다음과 같습니다.

<StartTime>2021-7-16 12:00:00</StartTime>

<Distributed>

Apigee에서 요청을 처리하는 데 노드를 하나 이상 사용할지를 결정합니다.

기본값	false
필수 여부	선택사항
유형	불리언
상위 요소	<Quota>
하위 요소	없음

true로 설정하면 정책이 중앙 카운터를 유지하고 모든 노드에 지속적으로 동기화하도록 지정할 수 있습니다. 노드는 가용성 영역 및/또는 리전에 적용될 수 있습니다.

참고: 유료 Apigee 계정이 있는 경우 일반적으로 설치에 여러 메시지 프로세서가 있으며 그 수는 트래픽 부하에 따라 달라질 수 있습니다. 평가 계정에는 일반적으로 2개의 메시지 프로세서가 있습니다.

기본값 false를 사용하면 각 노드의 수가 공유되지 않으므로 할당량을 초과할 수 있습니다.

<Distributed>false</Distributed>

카운터가 동기화되고 모든 요청에서 업데이트되도록 하려면 <Distributed>와 <Synchronous>를 true로 설정합니다.

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>

<Synchronous>

분산 할당량 카운터를 동기식으로 업데이트할지를 결정합니다.

기본값	false
필수 여부	선택사항
유형	불리언
상위 요소	<Quota>
하위 요소	없음

분산 할당량 카운터를 동기식으로 업데이트하려면 true로 설정합니다. 즉, 카운터에 대한 업데이트는 API에 대한 요청에서 할당량을 확인하는 것과 동시에 이루어져야 합니다. 할당량을 초과하는 API 호출을 허용하지 않아야 하는 경우에는 true로 설정합니다.

참고: 카운터에 동기식 업데이트를 구현하면 성능에 영향을 미치고 처리량을 줄일 수 있습니다. 일부 경우에 <Synchronous>true</Synchronous>를 사용하면 할당량 정책이 일부 트랜잭션을 처리하지 못할 수 있습니다.

할당량 카운터를 비동기식으로 업데이트하려면 false로 설정합니다. 즉, 중앙 저장소의 할당량 카운터가 비동기식으로 업데이트되는 시점에 따라 할당량을 초과하는 일부 API 호출이 발생할 수 있습니다. 그러나 동기식 업데이트와 관련된 잠재적인 성능 영향은 발생하지 않습니다.

비동기식 비동기 업데이트의 기본 간격은 10초입니다. <AsynchronousConfiguration> 요소를 사용하여 이러한 비동기식 동작을 구성합니다.

<Synchronous>false</Synchronous>

<AsynchronousConfiguration>

정책 구성 요소 <Synchronous>가 존재하지 않거나 존재하여 false로 설정하면 분산 할당량 카운터 간의 동기화 간격을 구성합니다. <Synchronous>가 true로 설정된 경우 Apigee에서 이 요소를 무시합니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	복합 유형
상위 요소	<Quota>
하위 요소	<SyncIntervalInSeconds> <SyncMessageCount>

<SyncIntervalInSeconds> 또는 <SyncMessageCount> 하위 요소를 사용하여 동기화 동작을 지정할 수 있습니다. 두 요소 중 하나 또는 둘 다 사용합니다. 예를 들면 다음과 같습니다.

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

또는

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

• <SyncIntervalInSeconds>만 있는 경우 할당량은 N초마다 동기화됩니다. 여기서 N은 처리된 메시지 수와 관계없이 요소에 지정된 값입니다.
• <SyncMessageCount>만 있는 경우 할당량은 메시지 M개마다 동기화됩니다. 여기서 M은 요소에 지정된 값 또는 10초마다 중 더 이른 시점입니다.
• 두 요소가 모두 존재하는 경우 할당량은 메시지 M개마다 또는 N초마다(둘 중 더 이른 시점) 동기화됩니다.
• <AsynchronousConfiguration>가 없거나 하위 요소가 모두 존재하지 않는 경우 처리된 메시지 수와 관계없이 할당량이 10초마다 동기화됩니다.

<SyncIntervalInSeconds>

10초 후에 비동기 업데이트가 수행되는 기본 동작을 재정의합니다.

기본값	10초
필수 여부	선택사항
유형	정수
상위 요소	<AsynchronousConfiguration>
하위 요소	없음

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

동기화 간격은 한도의 설명대로 10초 이상이어야 합니다.

<SyncMessageCount>

할당량 카운터를 동기화하기 전에 처리할 요청 수를 지정합니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	정수
상위 요소	<AsynchronousConfiguration>
하위 요소	없음

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

이 예시의 구성을 사용하여 각 노드에서 할당량 수는 5번의 요청마다 또는 10초마다(둘 중 더 이른 시점) 동기화됩니다.

<Identifier>

흐름 변수를 기반으로 고유한 카운터를 만들도록 정책을 구성합니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	문자열
상위 요소	<Quota>
하위 요소	없음

식별자 요소를 통해 흐름 변수의 값으로 정의된 고유 버킷에 호출 수를 할당할 수 있습니다. 예를 들어 VerifyAPIKey 정책 뒤에 채워지는 developer.id 변수를 사용하여 각 개발자가 만든 모든 앱의 모든 인스턴스에 할당량 제한 하나를 적용하거나 client_id를 사용하여 각 앱별로 할당량 제한을 적용할 수 있습니다. 후자 구성은 다음과 같습니다.

<Identifier ref="client_id"/>

AssignMessage 정책 또는자바스크립트 정책으로 설정할 수 있는 커스텀 변수 또는 VerifyAPIKey 정책이나 VerifyJWT 정책에서 설정한 변수와 같이 암시적으로 설정된 변수를 참조할 수 있습니다. 변수에 대한 자세한 내용은 흐름 변수 사용을 참조하고 Apigee에서 정의한 잘 알려진 변수 목록은 흐름 변수 참조를 확인하세요.

이 요소를 사용하지 않으면 정책은 모든 호출 수를 특정 할당량 정책의 단일 카운터로 할당합니다.

<Identifier> 할당량에 대해 developer.id 또는 developer.app.id를 참조하거나 이러한 변수를 <Identifier>로 사용되는 커스텀 변수에서 한 요소로 사용하는 경우 이러한 변수의 값은 향후 유지보수 기간 중에 변경될 수 있습니다. 이러한 상황은 드물며 정기적으로 발생하지는 않습니다. 하지만 발생했거나 이러한 변수 중 하나를 <Identifier>로 사용하는 할당량 정책이 있는 경우 변경사항이 발생한 기간 동안에는 할당량이 엄격하게 적용되지 않습니다.

식별자가 지정되지 않은 경우 할당량 정책은 어떻게 작동하나요?에서도 이 요소를 설명합니다.

참고: 동일한 할당량 정책에서 <Class> 요소와 <Identifier> 요소를 모두 사용할 수는 없습니다.

다음 표는 <Identifier>의 속성을 설명합니다.

속성	설명	기본값	Presence
ref	요청에 사용할 카운터를 식별하는 흐름 변수를 지정합니다. 이 변수는 HTTP 헤더, 쿼리 매개변수, 양식 매개변수 또는 메시지 콘텐츠 요소를 참조하거나 호출 수를 할당하는 방법을 식별하는 다른 값을 참조할 수 있습니다. client_id는 일반적으로 변수로 사용됩니다. client_id는 API 키 또는 고객 키라고도 하며 Apigee에서 조직에 등록된 경우 앱에 생성됩니다. API에 API 키 또는 OAuth 승인 정책을 사용 설정한 경우 이 식별자를 사용할 수 있습니다.	해당 사항 없음	선택사항

<MessageWeight>

할당량을 위해 메시지마다 할당되는 비용을 지정합니다. 이 요소를 사용하여 요청 메시지의 영향을 높일 수 있습니다. 예를 들어 다른 요청보다 컴퓨팅 리소스를 더 많이 사용합니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	정수
상위 요소	<Quota>
하위 요소	없음

예를 들어 POST 메시지를 GET 메시지보다 두 배 더 많이 계산하려고 합니다. 따라서 POST의 경우 <MessageWeight>를 2로, GET에는 1로 설정합니다. <MessageWeight>를 0으로 설정하여 요청이 카운터에 영향을 미치지 않도록 할 수도 있습니다.

이 예시에서 할당량이 분당 메시지 10개이고 POST 요청의 <MessageWeight>가 2이면 할당량은 10분 간격으로 5개의 POST 요청을 허용합니다. 카운터 초기화가 거부되기 전의 추가 요청, POST 또는 GET입니다.

<MessageWeight>를 나타내는 값은 흐름 변수로 지정해야 하며, HTTP 헤더, 쿼리 매개변수, XML 또는 JSON 요청 페이로드 또는 기타 흐름 변수에서 추출할 수 있습니다. 예를 들어 이름이 weight인 헤더에 설정합니다.

<MessageWeight ref="message_weight"/>

<UseQuotaConfigInAPIProduct>

시간 단위, 간격, 허용 최대치 등 API 제품의 할당량 설정을 정의합니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	복합 유형
상위 요소	<Quota>
하위 요소	<DefaultConfig>

할당량 정책에 <UseQuotaConfigInAPIProduct> 요소를 추가하면 Apigee에서 <Quota>의 <Allow>, <Interval>, <TimeUnit> 하위 요소를 무시합니다.

<UseQuotaConfigInAPIProduct> 요소는 단순히 다음 예시와 같이 <DefaultConfig> 요소를 사용하여 정의하는 기본 설정의 컨테이너입니다.

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>...</DefaultConfig>
</UseQuotaConfigInAPIProduct>

stepName 속성을 사용하면 VerifyAPIKey 정책 또는 흐름에서 OAuthv2 정책의 ValidateToken 정책 작업을 참조할 수 있습니다.

다음 표는 <UseQuotaConfigInAPIProduct>의 속성을 설명합니다.

속성	설명	기본값	Presence
stepName	흐름에서 인증 정책 이름을 식별합니다. 대상은 VerifyAPIKey 정책 또는 OAuthv2 정책 중 하나일 수 있습니다.	해당 사항 없음	필수

자세한 내용은 다음을 참조하세요.

• <DefaultConfig>
• API 제품이란 무엇인가요?
• API 제품 관리

<DefaultConfig>

API 제품 할당량의 기본값을 포함합니다. <DefaultConfig>를 정의하는 경우 하위 요소 세 개가 모두 필요합니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	복합 유형
상위 요소	<UseQuotaConfigInAPIProduct>
하위 요소	<Allow> <Interval> <TimeUnit>

API 제품의 작업(UI 또는 API 제품 API 사용)과 할당량 정책 모두에서 이 값을 정의할 수 있습니다. 하지만 그렇게 하면 API 제품의 설정이 우선 적용되고 할당량 정책의 설정은 무시됩니다.

이 요소의 구문은 다음과 같습니다.

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>
    <Allow>allow_count</Allow>
    <Interval>interval</Interval>
    <TimeUnit>[minute|hour|day|week|month]</TimeUnit>
  </DefaultConfig>
</UseQuotaConfigInAPIProduct>

다음 예시는 할당량을 매주 10,000으로 지정합니다.

<DefaultConfig>
  <Allow>10000</Allow>
  <Interval>1</Interval>
  <TimeUnit>week</TimeUnit>
</DefaultConfig>

자세한 내용은 다음을 참조하세요.

• API 제품이란 무엇인가요?
• API 제품 관리

<SharedName>

이 할당량 정책을 공유됨으로 식별합니다. API 프록시에서 <SharedName> 값이 동일한 모든 할당량 정책은 동일한 기본 할당량 카운터를 공유합니다. 이 요소가 있으면 <EnforceOnly> 또는 <CountOnly> 요소도 있어야 합니다.

자세한 내용과 예시는 공유 할당량 카운터 구성을 참조하세요.

기본값	해당 사항 없음
필수 여부	선택사항
유형	문자열
상위 요소	<Quota>
하위 요소	없음

<CountOnly>

ProxyEndpoint 응답 흐름의 조건부 단계에서 이 요소가 true로 설정된 할당량 정책을 배치하여 조건부로 기본 할당량 카운터를 늘립니다. 이 요소가 있으면 <SharedName> 및 <EnforceOnly> 요소도 있어야 합니다.

자세한 내용과 예시는 공유 할당량 카운터 구성을 참조하세요.

기본값	false
필수 여부	선택사항
유형	불리언
상위 요소	<Quota>
하위 요소	없음

<EnforceOnly>

API 프록시의 요청 흐름에서 이 요소를 true로 설정하여 할당량 정책을 배치합니다. 이 구성을 사용하면 API 프록시에서 <SharedName> 값이 동일한 할당량 정책에 대해 할당량 수를 공유할 수 있습니다. 이 요소가 있으면 <SharedName> 및 <CountOnly> 요소도 있어야 합니다.

자세한 내용과 예시는 공유 할당량 카운터 구성을 참조하세요.

기본값	false
필수 여부	선택사항
유형	불리언
상위 요소	<Quota>
하위 요소	없음

흐름 변수

할당량 정책이 실행되면 다음과 같은 사전 정의된 흐름 변수가 자동으로 채워집니다. 자세한 내용은 흐름 변수 참조를 확인하세요.

변수	유형	권한	설명
ratelimit.{policy_name}.allowed.count	긴 형식	읽기 전용	허용되는 할당량 수를 반환합니다.
ratelimit.{policy_name}.used.count	긴 형식	읽기 전용	할당량 간격 내에서 사용되는 현재 할당량을 반환합니다.
ratelimit.{policy_name}.available.count	긴 형식	읽기 전용	할당량 간격에서 사용 가능한 할당량 수를 반환합니다.
ratelimit.{policy_name}.exceed.count	긴 형식	읽기 전용	할당량을 초과하면 1을 반환합니다.
ratelimit.{policy_name}.total.exceed.count	긴 형식	읽기 전용	할당량을 초과하면 1을 반환합니다.
ratelimit.{policy_name}.expiry.time	긴 형식	읽기 전용	할당량이 만료되는 시점과 새 할당량 간격이 시작되는 시기를 결정하는 UTC 시간(밀리초)을 반환합니다. 할당량 정책 유형이 rollingwindow이면 할당량 간격이 만료되지 않으므로 이 값은 유효하지 않습니다.
ratelimit.{policy_name}.identifier	문자열	읽기 전용	정책에 연결된 (클라이언트) 식별자 참조를 반환합니다.
ratelimit.{policy_name}.class	문자열	읽기 전용	클라이언트 식별자와 연결된 클래스를 반환합니다.
ratelimit.{policy_name}.class.allowed.count	긴 형식	읽기 전용	클래스에 정의된 허용 할당량 수를 반환합니다.
ratelimit.{policy_name}.class.used.count	긴 형식	읽기 전용	클래스 내에서 사용된 할당량을 반환합니다.
ratelimit.{policy_name}.class.available.count	긴 형식	읽기 전용	클래스에서 사용 가능한 할당량 수를 반환합니다.
ratelimit.{policy_name}.class.exceed.count	긴 형식	읽기 전용	현재 할당량 간격의 클래스 한도를 초과하는 요청 수를 반환합니다.
ratelimit.{policy_name}.class.total.exceed.count	긴 형식	읽기 전용	모든 할당량 간격에서 클래스의 한도를 초과하는 요청의 총 개수를 반환하므로 모든 할당량 간격에 대한 class.exceed.count 합계입니다.
ratelimit.{policy_name}.failed	부울	읽기 전용	정책 실패 여부를 나타냅니다(true 또는 false).

오류 참조

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다.

도움말: 오류를 해결하는 데 도움이 필요하신가요? 해결 열의 를 클릭하여 자세한 문제 해결 정보를 확인합니다.

오류 코드	HTTP 상태	원인	수정
policies.ratelimit.FailedToResolveQuotaIntervalReference	500	<Interval> 요소가 Quota 정책 내에 정의되지 않은 경우 발생합니다. 이 요소는 필수이며 할당량에 적용되는 시간 간격을 지정하는 데 사용됩니다. 시간 간격은 <TimeUnit> 요소에 정의된 대로 분, 시간, 일, 주 또는 월 단위일 수 있습니다.
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference	500	<TimeUnit> 요소가 Quota 정책 내에 정의되지 않은 경우 발생합니다. 이 요소는 필수이며 할당량에 적용되는 시간 단위를 지정하는 데 사용됩니다. 시간 간격은 분, 시간, 일, 주 또는 월 단위일 수 있습니다.
policies.ratelimit.InvalidMessageWeight	500	흐름 변수를 통해 지정된 <MessageWeight> 요소의 값이 잘못된 경우에(정수가 아닌 값) 발생합니다.
policies.ratelimit.QuotaViolation	500	할당량 한도를 초과했습니다.	해당 사항 없음

배포 오류

팁: 오류를 해결하는 데 도움이 필요하신가요? 해결 열의 를 클릭하여 자세한 문제해결 정보를 확인하세요.

오류 이름	원인	수정
InvalidQuotaInterval	<Interval> 요소에 지정된 할당량 간격이 정수가 아닌 경우 API 프록시 배포가 실패합니다. 예를 들어 지정된 할당량 간격이 <Interval> 요소에서 0.1이면 API 프록시 배포가 실패합니다.
InvalidQuotaTimeUnit	<TimeUnit> 요소에 지정된 시간 단위가 지원되지 않는 경우 API 프록시 배포가 실패합니다. 지원되는 시간 단위는 minute, hour, day, week, month입니다.
InvalidQuotaType	<Quota> 요소의 type 속성에 의해 지정된 할당량 유형이 잘못된 경우 API 프록시 배포가 실패합니다. 지원되는 할당량 유형은 default, calendar, flexi, rollingwindow입니다.
InvalidStartTime	<StartTime> 요소에 지정된 시간 형식이 잘못된 경우 API 프록시 배포가 실패합니다. 유효한 형식은 yyyy-MM-dd HH:mm:ss이며 ISO 8601 날짜 및 시간 형식입니다. 예를 들어 <StartTime> 요소에 지정된 시간이 7-16-2017 12:00:00인 경우 API 프록시 배포가 실패합니다.
StartTimeNotSupported	할당량 유형이 calendar 유형이 아닌 <StartTime> 요소가 지정된 경우 API 프록시 배포가 실패합니다. <StartTime> 요소는 calendar 할당량 유형에만 지원됩니다. 예를 들어 <Quota> 요소에서 type 속성이 flexi 또는 rolling window로 설정된 경우 API 프록시 배포가 실패합니다.
InvalidTimeUnitForDistributedQuota	<Distributed> 요소가 true로 설정되고 <TimeUnit> 요소가 second로 설정된 경우 API 프록시 배포가 실패합니다. timeunit second는 분산 할당량에 유효하지 않습니다.
InvalidSynchronizeIntervalForAsyncConfiguration	Quota 정책의 <AsynchronousConfiguration> 요소 내에 있는 <SyncIntervalInSeconds> 요소에 지정된 값이 0 미만이면 API 프록시 배포가 실패합니다.
InvalidAsynchronizeConfigurationForSynchronousQuota	<AsynchronousConfiguration> 요소의 값이 Quota 정책의 true로 설정되고 또한 이 값이 <AsynchronousConfiguration>를 사용해 정의된 비동기 구성를 보유하고 있다면 API 프록시 배포가 실패합니다.

오류 변수

이러한 변수는 이 정책으로 오류가 트리거될 때 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

변수	장소	예
fault.name="fault_name"	fault_name은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다.	fault.name Matches "QuotaViolation"
ratelimit.policy_name.failed	policy_name은 오류를 발생시킨 정책의 사용자 지정 이름입니다.	ratelimit.QT-QuotaPolicy.failed = true

오류 응답 예시

참고: 오류 처리에서 권장사항은 오류 응답의 errorcode 부분을 트래핑하는 것입니다. 변경될 수 있으므로 faultstring의 텍스트에 의존하지 마세요.

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.QuotaViolation"
      },
      "faultstring":"Rate limit quota violation. Quota limit  exceeded. Identifier : _default"
   }
}

오류 규칙 예시

<FaultRules>
    <FaultRule name="Quota Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "QuotaViolation") </Condition>
        </Step>
        <Condition>ratelimit.Quota-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

참고: 현재 할당량 정책은 비율 제한을 적용하면 500의 상태 코드를 반환합니다. Apigee 관리형 서비스를 사용하고 할당량 정책이 429를 반환하게 하려면 Google Cloud Customer Care에 문의하세요. features.isHTTPStatusTooManyRequestEnabled 속성을 사용 설정합니다. 자세한 내용은 할당량 정책 위반의 Http 429 기본 상태 코드를 참조하세요.

참고: 속성을 업데이트할 때 변경되지 않더라도 모든 기존 속성을 API에 전달해야 합니다. 페이로드에서 속성을 생략하면 속성이 삭제됩니다.

curl -u email:password -X POST -H "Content-type:application/xml" \
  http://LOAD_BALANCER_IP:8080/v1/o/myorg \
  -d '<Organization type="trial" name="MyOrganization">
    <DisplayName>MyOrganization</DisplayName>
    <Environments/>
    <Properties>
        <Property name="features.isHTTPStatusTooManyRequestEnabled">true</Property>
    </Properties>
  </Organization>'

스키마

샘플: 최신 스키마는 GitHub 저장소 샘플을 참조하세요.

관련 주제

ResetQuota 정책

SpikeArrest 정책

할당량 및 Spoke Arrest 정책 비교