할당량 정책

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보

내용

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

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

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

동영상

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

샘플

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

<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>

<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>

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

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

<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>

<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>

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

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

<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>

할당량 정책에 대한 정보

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

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

SpikeArrest라는 할당량의 변화는 사용량 증가나 클라이언트 버그 또는 악의적인 공격의 급격한 증가로 인해 발생할 수 있는 트래픽 급증 (버스트)을 방지합니다. SpikeArrest에 관한 자세한 내용은 Spike Arrest 정책을 참고하세요.

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

할당량 정책 유형

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

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:00 및 24:00:00의 두 가지 표기법으로 한 날짜에 연결할 수 있는 두 시점의 자정을 구분할 수 있습니다. 따라서 2015-02-04 24:00:00은 2015-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">

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

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

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>

<Allow> 요소

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

다음은 <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의 값이 사용됩니다.

특성

<Allow>/<Class> 요소

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

<Class> 요소를 사용하려면 ref 속성을 사용하여 <Class> 태그에 흐름 변수를 지정합니다. 그런 다음 Edge는 흐름 변수의 값을 사용하여 <Allow> 하위 태그 중 하나를 선택하여 허용되는 정책 수를 결정합니다. Edge는 아래와 같이 흐름 변수의 값을 <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일 수 있습니다. 쿼리 매개변수에 잘못된 값이 있으면 정책은 할당량 위반 오류를 반환합니다.

특성

<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_time 및 off_peak_time이라는 두 가지 할당량 카운터를 유지합니다.

특성

<Interval> 요소

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

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

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

특성

<TimeUnit> 요소

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

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

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

특성

<StartTime> 요소

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

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

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

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

<Distributed> 요소

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

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

<Distributed>true</Distributed>

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

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

<Synchronous> 요소

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

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

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

<Synchronous>false</Synchronous>

<AsynchronousConfiguration> 요소

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

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

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

또는

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

<AsynchronousConfiguration>/<SyncIntervalInSeconds> 요소

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

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

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

<AasyncConfiguration>/<SyncMessageCount> 요소

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

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

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

<Identifier> 요소

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

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

이 요소는 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"/>

특성

<MessageWeight> 요소

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

예를 들어 POST 메시지를 GET 메시지에 비해 '무거움' 또는 비싼 것으로 간주하려고 합니다. 따라서 POST의 경우 MessageWeight을 2로, GET의 경우 1로 설정합니다. 요청이 카운터에 영향을 미치지 않도록 MessageWeight를 0으로 설정할 수도 있습니다. 이 예시에서 할당량이 분당 메시지 10개이고 POST 요청의 MessageWeight가 2이면 할당량이 10분 간격으로 POST 요청 5개를 허용합니다. 카운터 재설정이 거부되기 전의 모든 추가 요청(POST 또는 GET)입니다.

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

<MessageWeight ref="message_weight"/>

흐름 변수

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

오류 참조

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

런타임 오류

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

배포 오류

오류 변수

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

오류 응답 예시

{  
   "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>

스키마

관련 주제

ResetQuota 정책

SpikeArrest 정책

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