할당량 정책

<ph type="x-smartling-placeholder"></ph> 현재 Apigee Edge 문서를 보고 있습니다.
Apigee X 문서.
정보

대상

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

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

전체적인 트래픽 급증을 방지하기 위해 할당량을 사용하지 않습니다. 이를 위해 급증 저지 정책을 사용합니다. 급증 저지 정책을 참조하세요.

동영상

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

소개(새 Edge)

소개(기본 Edge)

동적 할당량

분산형 및 동기식

메시지 가중치

캘린더

순환 기간

Flexi

조건부 할당량

흐름 변수

오류 처리

샘플

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

동적 할당량 추가

<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 제품에 설정된 할당량 값을 읽습니다. 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>2017-02-18 10:30:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

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

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

액세스 카운터

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

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

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

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

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

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

<AssignMessage async="false" 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>

첫 번째 요청

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

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

예를 들어 카운터가 2017-07-08 07:00:00에서 시작되면 2017-07-08 08:00:00의 0으로 재설정됩니다(시작 시간에서 1시간). 첫 번째 메시지가 2017-07-08 07:35:28에 수신되고 2017-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>2017-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일 수 있습니다. 헤더에 잘못된 값이 있으면 정책은 할당량 위반 오류를 반환합니다.


할당량 정책에 대한 정보

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

예를 들어 할당량이 월 10,000개 메시지로 정의되면 비율 제한이 10,000번째 메시지 후에 시작됩니다. 첫 번째 해당 기간의 마지막 날 할당량 카운터까지 추가 요청 영역이 허용되지 않습니다. 지정된 시간 간격이 끝날 때 또는 할당량이 명시적으로 적용될 때까지 자동으로 재설정됩니다. 할당량 재설정 정책을 참조하세요.

SpikeArrest라는 할당량 변형을 사용하면 트래픽 급증 (또는 버스트)을 갑작스러운 사용량 증가, 클라이언트 버그 또는 악의적인 공격으로 인해 발생할 수 있습니다. 자세한 내용은 SpikeArrest에 대한 자세한 내용은 Spike Arrest 정책을 참고하세요.

할당량은 개별 API 프록시에 적용되며 여러 API 프록시로 분산되지 않습니다. 예를 들어 API 제품 1개에 3개의 API 프록시가 있는 경우 3개의 API 프록시 모두 동일한 할당량 정책 구성을 사용하는 경우에도 단일 할당량이 3개 간에 공유되지 않습니다.

할당량 정책 유형

할당량 정책은 여러 가지 유형의 정책(기본값, calendar, flexi, rollingwindow)을 지원합니다. 각 유형은 다음 표와 같이 할당량 카운터가 시작되는 시기와 초기화 시점을 정의합니다.

시간 단위 기본값(또는 null) 재설정 캘린더 초기화 flexi 재설정
다음 분 시작 <StartTime> 후 1분 첫 요청 후 1분
시간 다음 정시 <StartTime> 후 1시간 첫 요청 후 1시간
당일 자정(GMT 기준) <StartTime> 후 24시간 첫 요청 후 24시간
주말 일요일 자정(GMT 기준) <StartTime> 후 1주 첫 요청 후 1주
매월 마지막 날 자정(GMT 기준) <StartTime> 이후 1개월(28일) 첫 요청 후 1개월(28일)

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

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

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

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

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

할당량 카운터 이해

기본적으로 할당량 정책은 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 프록시 흐름의 두 곳 이상에서 동일한 할당량 정책을 사용하는 경우 할당량이 예상보다 빨리 소진되게 하는 방법은 다음 페이지에서 피해야 할 패턴입니다. Apigee Edge 피해야 할 패턴 도서.

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

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

시간 표기법

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

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

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

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

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

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

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

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

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

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

요소 참조

이 정책에 구성할 수 있는 요소와 속성은 다음과 같습니다. 일부 요소 조합은 서로 배타적이거나 필수 요소가 아닙니다. 구체적인 사용은 샘플을 참조하세요. 아래 verifyapikey.VerifyAPIKey.apiproduct.* 변수는 'VerifyAPIKey'라는API 키 정책을 사용하여 요청에서 앱의 API 키를 확인할 때 기본적으로 사용할 수 있습니다. 변수 값은 API 제품 구성에서 할당량 설정 가져오기에 설명된 대로 키가 연결된 API 제품의 할당량 설정에서 가져옵니다.

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>
   <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.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval> 
   <TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2017-7-16 12:00:00</StartTime> 
   <Distributed>false</Distributed> 
   <Synchronous>false</Synchronous> 
   <AsynchronousConfiguration> 
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds> 
      <SyncMessageCount>5</SyncMessageCount> 
   </AsynchronousConfiguration> 
   <Identifier/> 
   <MessageWeight/> 
</Quota>

<Quota> 속성

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">

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

속성 설명 기본값 접속 상태
유형

할당량 카운터가 할당량 사용량을 확인하는 시점과 방식을 파악할 때 사용합니다. 자세한 내용은 할당량 정책 유형을 참조하세요.

type 값을 생략하면 카운터가 처음부터 시작됩니다. 분/시간/일/주/월의 숫자입니다.

유효한 값으로 다음이 포함되어 있습니다.

  • calendar: 명시적 시작 시간을 기반으로 할당량을 구성합니다. 각 앱의 할당량 카운터는 사용자가 설정한 <StartTime>, <Interval>, <TimeUnit> 값에 따라 새로고침됩니다.
  • rollingwindow: '순환 기간'을 사용하는 할당량을 구성하여 할당량 사용량을 결정합니다. rollingwindow를 사용하면 <Interval><TimeUnit> 요소로 기간을 결정합니다(예: 1일). 요청이 수신되면 Edge는 요청이 발생한 정확한 시간 (예: 오후 5시 1분)부터 오후 5시 1분 사이에 들어온 요청 수를 집계합니다. 이전 1일 (1일) 동안 할당량 초과 여부를 닫아야 합니다.
  • flexi: 앱에서 첫 번째 요청 메시지가 수신되면 카운터가 시작되고 <Interval>, <TimeUnit> 값에 따라 재설정하는 할당량을 구성합니다.
캘린더 선택사항

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

속성 설명 기본값 현재 상태
name

정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다.

원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.

해당 없음 필수
continueOnError

정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다.

정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다.

거짓 선택사항
enabled

정책을 시행하려면 true로 설정합니다.

정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.

선택사항
async

이 속성은 지원이 중단되었습니다.

거짓 지원 중단됨

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>
기본값

해당 없음

이 요소를 생략하면 정책 name 속성 값이 사용됩니다.

현재 상태 선택사항
유형 문자열

<Allow> 요소

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

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

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

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

기본값: 해당 사항 없음
Presence: 선택사항
유형: 정수

속성

속성 설명 기본값 접속 상태
개수

할당량의 메시지 수를 지정하는 데 사용합니다.

예를 들어 count 속성 값 100, Interval 1, TimeUnit 월은 월별 메시지 100개 할당량을 지정합니다.

2000 선택사항
countRef

할당량에 대한 메시지 수가 포함된 흐름 변수를 지정하는 데 사용합니다. countRefcount 속성보다 우선합니다.

없음 선택사항

<Allow>/<Class> 요소

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

<Class> 요소를 사용하려면 ref 속성을 사용하여 <Class> 태그에 흐름 변수를 지정합니다. 그러면 Edge는 흐름 변수를 사용하여 <Allow> 하위 태그 중 하나를 선택하여 허용되는 태그를 결정합니다. 정책 수입니다. Edge는 흐름 변수의 값을 class에 일치시킵니다. 속성을 지정해야 합니다.<Allow>

<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일 수 있습니다. 쿼리 매개변수에 잘못된 값이 있으면 정책은 할당량 위반 오류를 반환합니다.

기본값: 해당 사항 없음
Presence: 선택사항
유형: 해당 사항 없음

속성

속성 설명 기본값 접속 상태
ref

할당량에 대한 할당량 클래스가 포함된 흐름 변수를 지정하는 데 사용합니다.

없음 필수

<Allow>/<Class>/<Allow> 요소

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

예:

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

이 예시에서 할당량 정책은 peak_timeoff_peak_time이라는 두 가지 할당량 카운터를 유지합니다.

기본값: 해당 사항 없음
Presence: 선택사항
유형: 해당 사항 없음

속성

속성 설명 기본값 접속 상태
클래스

할당량 카운터의 이름을 정의합니다.

없음 필수
개수 카운터의 할당량 한도를 지정합니다. 없음 필수

<Interval> 요소

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

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

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>
기본값: 없음
Presence: 필수
유형: 정수

속성

속성 설명 기본값 접속 상태
ref

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

없음 선택사항

<TimeUnit> 요소

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

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

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
기본값: 없음
Presence: 필수
유형:

문자열. minute, hour, day, week, month 중에서 선택합니다.

속성

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

<StartTime> 요소

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

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

예:

<StartTime>2017-7-16 12:00:00</StartTime>
기본값: 없음
Presence: typecalendar로 설정된 경우에 필요합니다.
유형:

ISO 8601 날짜 및 시간 형식의 문자열입니다.

<Distributed> 요소

Edge를 설치하면 하나 이상의 메시지 프로세서를 사용하여 요청을 처리할 수 있습니다. 이 요소를 true로 설정하면 정책이 중앙 카운터를 유지하고 모든 메시지 프로세서에 지속적으로 동기화되도록 지정할 수 있습니다. 메시지 프로세서는 여러 가용성 영역 또는 리전에 적용될 수 있습니다.

<ph type="x-smartling-placeholder">

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

<Distributed>true</Distributed>

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

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>
기본값: 거짓
Presence: 선택사항
유형: 부울

<Synchronous> 요소

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

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

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

<Synchronous>false</Synchronous>
기본값: 거짓
Presence: 선택사항
유형: 부울

<AsynchronousConfiguration> 요소

정책 구성 요소 <Synchronous>가 없거나 존재하지 않고 false로 설정하면 분산 할당량 카운터 간의 동기화 간격을 구성합니다.

SyncIntervalInSeconds 또는 SyncMessageCount 하위 요소를 사용하여 일정 기간 또는 메시지 수 이후 동기화할 수 있으며 상호 배타적입니다. 예를 들면 다음과 같습니다.

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

또는

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
기본값: SyncIntervalInSeconds = 10초
Presence: 선택사항. <Synchronous>true로 설정되면 무시됩니다.
유형:

복합

<AsynchronousConfiguration>/<SyncIntervalInSeconds> 요소

10초 간격 후 비동기 업데이트가 수행되는 기본 동작을 재정의하려면 이 요소를 사용합니다.

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

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

기본값: 10
Presence: 선택사항
유형:

정수

<AsynchronousConfiguration>/<SyncMessageCount> 요소

할당량 사이에 모든 Apigee 메시지 프로세서의 요청 수를 지정합니다. 업데이트.

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

이 예시에서는 각 Apigee에서 요청 5회마다 할당량 수가 업데이트되도록 지정합니다. 에지 메시지 프로세서

기본값: 해당 없음
Presence: 선택사항
유형:

정수

<Identifier> 요소

<Identifier> 요소를 사용하여 흐름 변수를 기반으로 고유한 카운터를 만드는 정책을 구성할 수 있습니다.

흐름 변수로 정의된 특성에 고유한 카운터를 만들 수 있습니다. 예를 들어 개발자 이메일 주소를 사용하여 할당량을 특정 개발자에게 연결할 수 있습니다. 커스텀 변수부터 API 키 확인 정책에 사용할 수 있는 변수와 같은 사전 정의된 변수까지, 다양한 변수를 사용하여 할당량을 식별할 수 있습니다. 변수 참조도 참조하세요.

이 요소를 사용하지 않으면 정책은 할당량에 적용되는 단일 카운터를 사용합니다.

이 요소는 Apigee 커뮤니티 게시물(http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html)에서도 설명합니다.

<Identifier ref="verifyapikey.verify-api-key.client_id"/>
기본값: 해당 사항 없음
Presence: 선택사항
유형:

문자열

속성

속성 설명 기본값 접속 상태
ref

요청에 사용할 카운터를 식별하는 흐름 변수를 지정합니다. 식별자는 HTTP 헤더, 쿼리 매개변수, 양식 매개변수 또는 각 앱, 앱 사용자, 앱 개발자, API 제품 또는 기타 특성에 고유한 메시지 콘텐츠일 수 있습니다.

앱을 고유하게 식별하는 데 가장 일반적으로 사용되는 <Identifier>client_id입니다. client_id는 API 키의 또 다른 이름입니다. 또는 고객 키를 만들 수 있습니다. Apigee Edge입니다. API에 API 키 또는 OAuth 승인 정책을 사용 설정한 경우 이 식별자를 사용할 수 있습니다.

보안 정책이 없는 경우와 같이 client_id가 없는 경우에는 할당량 설정을 가져와야 할 수 있습니다. 포함 이러한 상황에서는 Access Entity 정책을 사용하여 적절한 API를 검색할 수 있습니다. ExtractVariables를 사용하여 값을 추출한 다음, 추출된 값을 컨텍스트 변수의 값을 지정합니다. 자세한 내용은 항목 액세스 정책을 참조하세요.

해당 없음 선택사항

<MessageWeight> 요소

각 메시지에 할당된 가중치를 지정할 때 사용합니다. 메시지 가중치를 사용하여 요청 메시지의 영향을 높일 수 있습니다. 예를 들어 다른 요청보다 컴퓨팅 리소스를 더 많이 사용합니다.

예를 들어, POST 메시지가 두 배의 "무거움"으로 계산되도록 할 수 있습니다. GET이 있거나 메시지를 보낼 수 있습니다 따라서 POST의 경우 MessageWeight을 2로, POST의 경우 1로 설정합니다. 받기 MessageWeight를 0으로 설정하여 요청이 카운터에 영향을 주지 않습니다. 이 예시에서 할당량이 분당 메시지 10개이고 POST 요청의 MessageWeight2이면 할당량이 10분 간격으로 5개의 POST 요청을 허용합니다. 모든 추가 요청, POST 또는 GET 다시 시도해야 합니다.

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

<MessageWeight ref="message_weight"/>
기본값: 해당 사항 없음
Presence: 선택사항
유형:

정수

흐름 변수

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

변수 유형 권한 설명
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).

오류 참조

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

런타임 오류

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

오류 코드 HTTP 상태 원인 해결
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 <Interval> 요소가 할당량 정책 내에 정의되지 않은 경우 발생합니다. 이 요소는 필수이며 할당량에 적용되는 시간 간격을 지정하는 데 사용됩니다. 시간 간격 <TimeUnit> 요소로 정의된 대로 분, 시간, 일, 주, 월이 될 수 있습니다.
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference 500 <TimeUnit> 요소가 할당량 정책 내에 정의되지 않은 경우 발생합니다. 이 요소는 필수이며 할당량에 적용되는 시간 단위를 지정하는 데 사용됩니다. 시간 간격은 분, 시간, 일, 주 또는 월 단위일 수 있습니다.
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 정책에서 <AsynchronousConfiguration> 요소의 값이 true로 설정된 경우 API 프록시의 배포가 실패합니다.

오류 변수

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

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

오류 응답 예시

{  
   "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>
<ph type="x-smartling-placeholder">

스키마

관련 주제

ResetQuota 정책

SpikeArrest 정책

할당량, 급증 저지, 동시 비율 한도 정책 비교