SpikeArrest 정책

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

Apigee Edge 문서 보기

SpikeArrest 정책은 <Rate> 요소를 사용하여 트래픽 급증으로부터 보호합니다. 이 요소는 API 프록시가 처리하고 백엔드로 전송되는 요청 수를 제한하여 성능 지연 및 다운타임으로부터 보호합니다.

이 정책은 표준 정책이며 모든 환경 유형에 배포할 수 있습니다. 정책 유형과 각 환경 유형에서의 가용성에 대한 자세한 내용은 정책 유형을 참조하세요.

SpikeArrest와 할당량 간의 차이점

할당량 정책은 클라이언트 앱이 시간, 일, 주 또는 월 동안 API에 제출할 수 있는 요청 메시지 수를 구성합니다. 할당량 정책은 들어오는 요청을 기록하는 분산 카운터를 유지하여 클라이언트 앱에 소비 한도를 적용합니다.

할당량을 사용하면 운영 트래픽 관리가 아닌 개발자 및 파트너와의 비즈니스 계약 또는 SLA를 적용할 수 있습니다. SpikeArrest를 사용하여 API 트래픽이 갑자기 급증하는 것을 방지합니다. 할당량 및 SpokeArrest 정책 비교도 참조하세요.

동영상

이 정책의 사용 사례에 대한 설명은 다음 동영상을 참조하세요.

필요성

할당량 정책 비교

<SpikeArrest> 요소

SpikeArrest 정책을 정의합니다.

기본값	아래의 기본 정책 탭을 참조하세요.
필수 여부	선택사항
유형	복합 객체
상위 요소	해당 사항 없음
하위 요소	<Identifier> <MessageWeight> <Rate> (필수) <UseEffectiveCount>

구문

<SpikeArrest> 요소는 다음 구문을 사용합니다.

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <DisplayName>display_name</DisplayName>
  <Properties/>
  <Identifier ref="flow_variable"/>
  <MessageWeight ref="flow_variable"/>
  <Rate ref="flow_variable">rate[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
</SpikeArrest>

기본 정책

다음 예시는 UI에서 흐름에 SpikeArrest 정책을 추가할 때의 기본 설정을 보여줍니다.

<SpikeArrest async="false" continueOnError="false" enabled="true" name="Spike-Arrest-1">
  <DisplayName>Spike Arrest-1</DisplayName>
  <Properties/>
  <Identifier ref="request.header.some-header-name"/>
  <MessageWeight ref="request.header.weight"/>
  <Rate>30ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

This element has the following attributes that are common to all policies:

Attribute	Default	Required?	Description
name	N/A	Required	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError	false	Optional	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow
enabled	true	Optional	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async	false	Deprecated	This attribute is deprecated.

예시

다음 예시에서는 SpikeArrest 정책을 사용하는 몇 가지 방법을 보여줍니다.

예시 1

다음 예에서는 비율을 초당 5로 설정합니다.

<SpikeArrest name="SA-Static-5ps">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

이 샘플 정책은 초당 최대 5개의 요청을 허용합니다. 평활화를 통해 200밀리초(1000/5) 간격마다 최대 1개의 요청으로 적용됩니다.

예시 2

다음 예시에서는 비율을 분당 12로 설정합니다.

<SpikeArrest name="SA-Static-12pm">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

이 샘플 정책은 5초(60/12) 간격당 1개 요청의 비율로 분당 최대 12개 요청을 허용합니다. 요청이 5초 간격에서 1개를 초과할 때는 요청 수가 구성된 분당 12개 비율 제한보다 낮은 경우에 그러한 요청이 허용됩니다(평활화 없음).

예 3

다음 예는 요청을 분당 12로 제한합니다(5초마다 허용되는 요청 1개, 또는 60/12).

<SpikeArrest name="SA-With-Dynamic-Weight-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request_specific_weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

또한 <MessageWeight> 요소는 특정 앱 또는 클라이언트의 메시지 가중치를 조정하는 맞춤 값(weight 헤더)을 허용합니다. 이렇게 하면 <Identifier> 요소로 식별되는 항목의 제한을 추가로 제어할 수 있습니다.

예 4

다음 예시에서는 SpikeArrest에 request.header.runtime_rate 흐름 변수로 전달된 요청을 통해 설정된 런타임 값을 찾도록 지시합니다.

<SpikeArrest name="SA-From-Inbound-Header-1">
  <Rate ref="request.header.runtime_rate" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

흐름 변수의 값은 intpm 또는 intps 형식이어야 합니다.

이 예시를 시도하려면 다음과 같은 요청을 실행합니다.

curl http://myorg-myenv.apigee.net/price -H 'runtime_rate:30ps'

팁: API 제품에 설정된 맞춤 변수를 사용하여 SpikeArrest 비율을 설정하는 방법을 설명하는 API 제품을 사용하여 급증 저지 한도를 설정하려면 어떻게 해야 하나요?를 확인하세요.

하위 요소 참조

이 섹션에서는 <SpikeArrest>의 하위 요소를 설명합니다.

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value	N/A
Required?	Optional. If you omit <DisplayName>, the value of the policy's name attribute is used.
Type	String
Parent Element	<PolicyElement>
Child Elements	None

The <DisplayName> element uses the following syntax:

Syntax

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Example

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

The <DisplayName> element has no attributes or child elements.

<Identifier>

클라이언트에 따라 SpikeArrest 정책을 적용할 수 있도록 요청을 그룹화하는 방법을 선택할 수 있습니다. 예를 들어 개발자 ID별로 요청을 그룹화할 수 있으며, 이 경우 각 개발자의 요청은 해당 프록시의 모든 요청이 아닌 자체 SpikeArrest 비율로 계산됩니다.

요청 제한을 보다 세밀하게 제어하려면 <MessageWeight> 요소와 함께 사용합니다.

<Identifier> 요소를 비워 두면 해당 API 프록시에 대한 모든 요청에 한 개의 비율 제한이 적용됩니다.

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

구문

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <Identifier ref="flow_variable"/>
</SpikeArrest>
        

예시 1

다음 예시에서는 개발자 ID별로 SpikeArrest 정책을 적용합니다.

<SpikeArrest name="Spike-Arrest-1">
  <Identifier ref="developer.id"/>
  <Rate>42pm</Rate/>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

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

속성	설명	기본값	접속 상태
ref	SpikeArrest 그룹이 요청을 수신하는 변수를 식별합니다. VerifyAPIKey 정책에 사용 가능한 고유한 클라이언트를 나타내는 모든 흐름 변수를 사용할 수 있습니다. 자바스크립트 정책 또는 AssignMessage 정책을 사용하여 커스텀 변수를 설정할 수도 있습니다.	해당 사항 없음	필수

이 요소는 이 Apigee 커뮤니티 게시물에서도 설명합니다.

<MessageWeight>

각 메시지에 정의된 가중치를 지정합니다. 메시지 가중치는 SpikeArrest 비율 계산에 대한 단일 요청의 영향을 수정합니다. 메시지 가중치는 HTTP 헤더, 쿼리 매개변수, 양식 매개변수, 메시지 본문 콘텐츠와 같은 모든 흐름 변수가 될 수 있습니다. 자바스크립트 정책 또는 AssignMessage 정책을 사용하여 커스텀 변수를 사용할 수도 있습니다.

<Identifier>와 함께 사용하여 특정 클라이언트 또는 앱별로 요청을 추가로 제한할 수 있습니다.

예를 들어 SpikeArrest <Rate>가 10pm이고 앱이 가중치가 2인 요청을 제출할 경우 각 요청이 2개로 계산되므로 해당 클라이언트에서 분당 5개의 메시지만 허용됩니다.

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

구문

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <MessageWeight ref="flow_variable"/>
</SpikeArrest>

예시 1

다음 예는 요청을 분당 12로 제한합니다(5초마다 허용되는 요청 1개, 또는 60/12).

<SpikeArrest name="SA-With-Dynamic-Weight-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request_specific_weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

이 예에서 <MessageWeight>는 특정 클라이언트의 메시지 가중치를 조정하는 맞춤 값(요청의 weight 헤더)을 허용합니다. 이렇게 하면 <Identifier> 요소로 식별되는 항목의 제한을 추가로 제어할 수 있습니다.

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

속성	설명	접속 상태	기본값
ref	특정 클라이언트의 메시지 가중치를 포함하는 흐름 변수를 식별합니다. HTTP 쿼리 매개변수, 헤더, 메시지 본문 콘텐츠와 같은 흐름 변수가 될 수 있습니다. 자세한 내용은 흐름 변수 참조를 확인하세요. 자바스크립트 정책 또는 AssignMessage 정책을 사용하여 커스텀 변수를 설정할 수도 있습니다.	필수	해당 사항 없음

<Rate>

분당 또는 초당 간격으로 허용되는 요청 수를 설정하여 트래픽 급증(또는 버스트)을 제한하는 비율을 지정합니다. 이 요소를 <Identifier> 및 <MessageWeight>와 함께 사용하여 클라이언트의 값을 허용해 런타임에 트래픽을 원활하게 조절할 수도 있습니다. <UseEffectiveCount> 요소를 사용하여 정책에 사용되는 비율 제한 알고리즘을 설정합니다.

참고: 값 또는 false와 함께 <UseEffectiveCount>를 사용하는 것은 모든 Apigee 조직 또는 프로덕션 워크로드를 실행하는 Apigee Hybrid 조직에서 지원되지 않습니다. 자세한 내용은 <UseEffectiveCount>를 참조하세요.

지정할 수 있는 최대 비율 제한은 한도 페이지의 SpikeArrest 섹션을 참조하세요.

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

구문

다음 방법 중 하나로 비율을 지정할 수 있습니다.

• <Rate> 요소의 본문으로 지정하는 정적 비율
• 클라이언트가 전달할 수 있는 변수 값입니다. ref 속성을 사용하여 흐름 변수의 이름을 식별합니다.

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <Rate ref="flow_variable">rate[pm|ps]</Rate>
</SpikeArrest>

유효한 비율 값(변수 값 또는 요소의 본문에 정의됨)은 다음 형식을 따라야 합니다.

• intps (초당 요청 수, 밀리초 간격으로 평활화)
• intpm (분당 요청 수, 초 간격으로 평활화)

int 값은 0이 아닌 양의 정수여야 합니다.

예시 1

다음 예시에서는 비율을 초당 요청 5개로 설정합니다.

<SpikeArrest name="SA-Static-5ps">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

이 정책은 200밀리초마다 허용되는 요청 1개(1000/5)로 비율을 평활화합니다.

예시 2

다음 예에서는 비율을 분당 요청 12개로 설정합니다.

<SpikeArrest name="SA-Static-12pm">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

이 정책 예시는 5초마다 허용되는 요청 1개(60/12)로 비율을 평활화합니다.

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

속성	설명	접속 상태	기본값
ref	비율을 지정하는 흐름 변수를 식별합니다. HTTP 쿼리 매개변수, 헤더 또는 메시지 본문 콘텐츠와 같은 흐름 변수 또는 KVM과 같은 값이 될 수 있습니다. 자세한 내용은 흐름 변수 참조를 확인하세요. 자바스크립트 정책 또는 AssignMessage 정책을 사용하여 커스텀 변수를 사용할 수도 있습니다. ref 및 이 요소의 본문을 모두 정의하면 ref 값이 적용되고 요청에서 흐름 변수가 설정될 때 우선 적용됩니다. (ref에서 식별된 변수가 요청에 설정되지 않은 반대의 경우에도 마찬가지입니다.) 예를 들면 다음과 같습니다. <Rate ref="request.header.custom_rate">1pm</Rate> 이 예시에서 클라이언트가 custom_rate 헤더를 전달하지 않는 경우 API 프록시 비율은 모든 클라이언트에 대해 분당 요청 1개입니다. 클라이언트가 custom_rate 헤더를 전달하면 custom_rate 헤더가 없는 요청이 전송될 때까지 비율 제한은 프록시의 모든 클라이언트에 대해 초당 요청 10개로 됩니다. <Identifier>를 사용하여 요청을 그룹화하면 다양한 유형의 클라이언트에 커스텀 비율을 적용할 수 있습니다. ref에 값을 지정하지만 <Rate> 요소의 본문에 비율을 설정하지 않고 클라이언트가 값을 전달하지 않는 경우 SpikeArrest 정책이 오류를 일으킵니다.	선택사항	해당 사항 없음

<UseEffectiveCount>

이 요소를 사용하면 아래 설명된 대로 값을 true 또는 false로 설정하여 개별 급증 저지 알고리즘 간에 선택할 수 있습니다.

참

true로 설정하면 SpikeArrest가 리전에 배포됩니다. 즉, 요청 수가 한 리전의 메시지 프로세서(MP) 간에 동기화됩니다. 또한 '슬라이딩 창' 비율 제한 알고리즘이 적용됩니다. 이 알고리즘은 일관적인 비율 제한 동작을 제공하며 백엔드로 전송될 수 있는 수신 요청 수를 '평활화'하지 않습니다. 요청 급증이 짧은 간격으로 전송되면 <Rate> 요소에 설정된 대로 구성된 비율 제한을 초과하지 않는 한 허용됩니다. 예를 들면 다음과 같습니다.

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request.header.weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

false(기본값)

참고: 기본값은 false이지만 Apigee 조직은 이 요소를 true로 설정해야 합니다.

Apigee 조직에서는 비율 평활화가 지원되지 않습니다.

false(기본값)로 설정된 경우 SpikeArrest 정책은 지정된 비율 제한을 더 작은 간격으로 나눠서 트래픽 급증을 평활화하는 '토큰 버킷' 알고리즘을 사용합니다. 이 접근 방식의 단점은 짧은 기간 동안 수신되는 여러 적법한 요청이 잠재적으로 거부될 수 있다는 것입니다.

예를 들어, 30pm(분당 요청 30개)의 비율을 입력한다고 가정하겠습니다. 테스트에서 요청이 1분 내에 들어오는 한 1초에 30개의 요청을 보낼 수 있다고 생각할 수 있습니다. 하지만 정책은 다른 방식으로 설정을 적용합니다. 생각해보면 1초 내 요청 30개는 일부 환경에서 작은 급증으로 간주될 수 있습니다.

• 분당 비율은 초 간격으로 허용되는 전체 요청으로 평활화됩니다.
  

  예를 들어 30pm은 다음과 같이 평활화됩니다.
  60초(1분)/30pm = 2초 간격, 또는 2초마다 허용되는 요청 1개. 2초 이내의 두 번째 요청은 실패합니다. 또한 1분 이내의 31번째 요청도 실패합니다.

• 초당 비율은 밀리초 간격으로 허용되는 전체 요청으로 평활화됩니다.

  예를 들어 10ps는 다음과 같이 평활화됩니다.
  1000밀리초(1초)/10ps = 100밀리초 간격, 100밀리초마다 허용되는 요청 1개. 100밀리초 이내의 두 번째 요청은 실패합니다. 또한 1초 이내의 11번째 요청도 실패합니다.

참고: 비율 평활화에서 요청 수는 항상 0보다 큰 정수입니다. 평활화는 요청을 분수로 계산하지 않습니다.

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

다음 표에서는 <UseEffectiveCount> 요소의 속성을 설명합니다.

속성	설명	기본값	접속 상태
ref	<UseEffectiveCount> 값이 포함된 변수를 식별합니다. HTTP 쿼리 매개변수, 헤더, 메시지 본문 콘텐츠와 같은 흐름 변수가 될 수 있습니다. 자세한 내용은 흐름 변수 참조를 확인하세요. 자바스크립트 정책 또는 AssignMessage 정책을 사용하여 커스텀 변수를 설정할 수도 있습니다.	해당 사항 없음	선택사항

흐름 변수

SpikeArrest 정책이 실행되면 다음과 같은 흐름 변수가 채워집니다.

변수	유형	권한	설명
ratelimit.policy_name.failed	불리언	읽기 전용	정책이 실패했는지 여부를 나타냅니다(true 또는 false).

자세한 내용은 흐름 변수 참조를 확인하세요.

오류 참조

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Fault code	HTTP status	Cause	Fix
policies.ratelimit.FailedToResolveSpikeArrestRate	500	This error occurs if the reference to the variable containing the rate setting within the <Rate> element cannot be resolved to a value within the SpikeArrest policy. This element is mandatory and used to specify the spike arrest rate in the form of intpm or intps.
policies.ratelimit.InvalidMessageWeight	500	This error occurs if the value specified for the <MessageWeight> element through a flow variable is invalid (a non-integer value).
policies.ratelimit.SpikeArrestViolation	429	The rate limit is exceeded.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Error name	Cause	Fix
InvalidAllowedRate	If the spike arrest rate specified in the <Rate> element of the SpikeArrest policy is not an integer or if the rate does not have ps or pm as a suffix, then the deployment of the API proxy fails.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "SpikeArrestViolation"
ratelimit.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	ratelimit.SA-SpikeArrestPolicy.failed = true

Example error response

Shown below is an example error response:

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.SpikeArrestViolation"
      },
      "faultstring":"Spike arrest violation. Allowed rate : 10ps"
   }
}

Example fault rule

Shown below is an example fault rule to handle a SpikeArrestViolation fault:

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

Quota 또는 SpikeArrest 정책이 설정한 비율 제한을 초과하는 현재 HTTP 상태 코드는 429(너무 많은 요청)입니다.

스키마

각 정책 유형은 XML 스키마(.xsd)로 정의됩니다. 참고로 GitHub에서 정책 스키마를 사용할 수 있습니다.

관련 주제

• 할당량 정책: 개별 클라이언트의 트래픽을 제한하는 할당량 정책
• 비율 제한 개요의 비율 제한
• 할당량 및 SpokeArrest 정책 비교