이 페이지는 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>
이 요소에는 다음과 같이 모든 정책에 공통된 속성이 있습니다.
속성 | 기본 | 필수 여부 | 설명 |
---|---|---|---|
name |
해당 없음 | 필수 |
정책의 내부 이름입니다. 원하는 경우 |
continueOnError |
false | 선택 | 정책이 실패할 경우 오류가 반환되도록 하려면 false 로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 true 로 설정합니다. 참조:
|
enabled |
true | 선택 | 정책을 시행하려면 true 로 설정합니다. 정책을 중지하려면 false 로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다. |
async |
false | 지원 중단됨 | 이 속성은 지원이 중단되었습니다. |
예시
다음 예시에서는 SpikeArrest 정책을 사용하는 몇 가지 방법을 보여줍니다.
예시 1
다음 예에서는 비율을 초당 5로 설정합니다.
<SpikeArrest name="Spike-Arrest-1"> <Rate>5ps</Rate> <UseEffectiveCount>false</UseEffectiveCount> </SpikeArrest>
이 샘플 정책은 초당 최대 5개의 요청을 허용합니다. 평활화를 통해 200밀리초(1000/5) 간격마다 최대 1개의 요청으로 적용됩니다.
예시 2
다음 예시에서는 비율을 분당 12로 설정합니다.
<SpikeArrest name="Spike-Arrest-1"> <Rate>12pm</Rate> <UseEffectiveCount>true</UseEffectiveCount> </SpikeArrest>
이 샘플 정책은 5초(60/12) 간격당 1개 요청의 비율로 분당 최대 12개 요청을 허용합니다. 요청이 5초 간격에서 1개를 초과할 때는 요청 수가 구성된 분당 12개 비율 제한보다 낮은 경우에 그러한 요청이 허용됩니다(평활화 없음).
예 3
다음 예는 요청을 분당 12로 제한합니다(5초마다 허용되는 요청 1개, 또는 60/12).
<SpikeArrest name="Spike-Arrest-1"> <Rate>12pm</Rate> <Identifier ref="client_id" /> <MessageWeight ref="request.header.weight" /> <UseEffectiveCount>true</UseEffectiveCount> </SpikeArrest>
또한 <MessageWeight>
요소는 특정 앱 또는 클라이언트의 메시지 가중치를 조정하는 맞춤 값(weight
헤더)을 허용합니다. 이렇게 하면 <Identifier>
요소로 식별되는 항목의 제한을 추가로 제어할 수 있습니다.
예 4
다음 예시에서는 SpikeArrest에 request.header.runtime_rate
흐름 변수로 전달된 요청을 통해 설정된 런타임 값을 찾도록 지시합니다.
<SpikeArrest name="Spike-Arrest-1"> <Rate ref="request.header.runtime_rate" /> <UseEffectiveCount>true</UseEffectiveCount> </SpikeArrest>
흐름 변수의 값은 intpm
또는 intps
형식이어야 합니다.
이 예시를 시도하려면 다음과 같은 요청을 실행합니다.
curl http://myorg-myenv.apigee.net/price -H 'runtime_rate:30ps'
하위 요소 참조
이 섹션에서는 <SpikeArrest>
의 하위 요소를 설명합니다.
<DisplayName>
name
속성 외에 이 요소를 사용하여 관리 UI 프록시 편집기에서 자연스러운 다른 이름으로 정책의 라벨을 지정합니다.
<DisplayName>
요소는 모든 정책에 공통으로 적용됩니다.
기본값 | 해당 사항 없음 |
필수 여부 | 선택사항. <DisplayName> 을 생략하면 정책의 name 속성 값이 사용됩니다. |
유형 | 문자열 |
상위 요소 | <PolicyElement> |
하위 요소 | 없음 |
<DisplayName>
요소는 다음 문법을 사용합니다.
구문
<PolicyElement> <DisplayName>POLICY_DISPLAY_NAME</DisplayName> ... </PolicyElement>
예
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
<DisplayName>
요소에 속성 또는 하위 요소가 없습니다.
<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="Spike-Arrest-1"> <Rate>12pm</Rate> <Identifier ref="client_id" /> <MessageWeight ref="request.header.weight" /> <UseEffectiveCount>true</UseEffectiveCount> </SpikeArrest>
이 예에서 <MessageWeight>
는 특정 클라이언트의 메시지 가중치를 조정하는 맞춤 값(요청의 weight
헤더)을 허용합니다. 이렇게 하면 <Identifier>
요소로 식별되는 항목의 제한을 추가로 제어할 수 있습니다.
다음 표는 <MessageWeight>
의 속성을 설명합니다.
속성 | 설명 | 접속 상태 | 기본값 |
---|---|---|---|
ref |
특정 클라이언트의 메시지 가중치를 포함하는 흐름 변수를 식별합니다. HTTP 쿼리 매개변수, 헤더, 메시지 본문 콘텐츠와 같은 흐름 변수가 될 수 있습니다. 자세한 내용은 흐름 변수 참조를 확인하세요. 자바스크립트 정책 또는 AssignMessage 정책을 사용하여 커스텀 변수를 설정할 수도 있습니다. | 필수 | 해당 사항 없음 |
<Rate>
분당 또는 초당 간격으로 허용되는 요청 수를 설정하여 트래픽 급증(또는 버스트)을 제한하는 비율을 지정합니다. 이 요소를 <Identifier>
및 <MessageWeight>
와 함께 사용하여 클라이언트의 값을 허용해 런타임에 트래픽을 원활하게 조절할 수도 있습니다. <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="Spike-Arrest-1"> <Rate>5ps</Rate> <UseEffectiveCount>false</UseEffectiveCount> </SpikeArrest>
이 정책은 200밀리초마다 허용되는 요청 1개(1000/5)로 비율을 평활화합니다.
예시 2
다음 예에서는 비율을 분당 요청 12개로 설정합니다.
<SpikeArrest name="Spike-Arrest-1"> <Rate>12pm</Rate> <UseEffectiveCount>true</UseEffectiveCount> </SpikeArrest>
이 정책 예시는 5초마다 허용되는 요청 1개(60/12)로 비율을 평활화합니다.
다음 표는 <Rate>
의 속성을 설명합니다.
속성 | 설명 | 접속 상태 | 기본값 |
---|---|---|---|
ref |
비율을 지정하는 흐름 변수를 식별합니다. HTTP 쿼리 매개변수, 헤더 또는 메시지 본문 콘텐츠와 같은 흐름 변수 또는 KVM과 같은 값이 될 수 있습니다. 자세한 내용은 흐름 변수 참조를 확인하세요.
자바스크립트 정책 또는 AssignMessage 정책을 사용하여 커스텀 변수를 사용할 수도 있습니다.
예를 들면 다음과 같습니다. <Rate ref="request.header.custom_rate">1pm</Rate> 이 예시에서 클라이언트가
|
선택사항 | 해당 사항 없음 |
<UseEffectiveCount>
이 요소를 사용하면 아래 설명된 대로 값을 true
또는 false
로 설정하여 개별 급증 저지 알고리즘 간에 선택할 수 있습니다.
true
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
(기본값)로 설정된 경우 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번째 요청도 실패합니다.
기본값 | 거짓 |
필수 여부 | 선택사항 |
유형 | 불리언 |
상위 요소 |
<SpikeArrest>
|
하위 요소 | 없음 |
다음 표에서는 <UseEffectiveCount>
요소의 속성을 설명합니다.
속성 | 설명 | 기본값 | 접속 상태 |
---|---|---|---|
ref |
<UseEffectiveCount> 값이 포함된 변수를 식별합니다. HTTP 쿼리 매개변수, 헤더, 메시지 본문 콘텐츠와 같은 흐름 변수가 될 수 있습니다. 자세한 내용은 흐름 변수 참조를 확인하세요. 자바스크립트 정책 또는 AssignMessage 정책을 사용하여 커스텀 변수를 설정할 수도 있습니다. |
해당 사항 없음 | 선택사항 |
흐름 변수
SpikeArrest 정책이 실행되면 다음과 같은 흐름 변수가 채워집니다.
변수 | 유형 | 권한 | 설명 |
---|---|---|---|
ratelimit.policy_name.failed |
불리언 | 읽기 전용 | 정책이 실패했는지 여부를 나타냅니다(true 또는 false ). |
자세한 내용은 흐름 변수 참조를 확인하세요.
오류 참조
이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.
런타임 오류
이러한 오류는 정책이 실행될 때 발생할 수 있습니다.
오류 코드 | HTTP 상태 | 원인 | 수정 |
---|---|---|---|
policies.ratelimit.FailedToResolveSpikeArrestRate |
500 |
이 오류는 <Rate> 요소 내에 속도 설정이 포함된 변수의 참조를 SpikeArrest 정책에서의 값으로 확인할 수 없는 경우에 발생합니다. 이 요소는 필수이며 intpm 또는 intps 형식으로 급증 저지 속도를 지정하는 데 사용됩니다. |
build |
policies.ratelimit.InvalidMessageWeight |
500 |
이 오류는 흐름 변수를 통해 <MessageWeight> 요소에 지정된 값이 잘못된 경우에(정수가 아닌 값) 발생합니다. |
build |
policies.ratelimit.SpikeArrestViolation |
429 |
비율 제한이 초과되었습니다. |
배포 오류
이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.
오류 이름 | 원인 | 수정 |
---|---|---|
InvalidAllowedRate |
SpikeArrest 정책의 <Rate> 요소에 지정된 급증 저지 비율이 정수가 아니거나 속도에 ps 또는 pm 서픽스가 없는 경우 API 프록시 배포가 실패합니다. |
build |
오류 변수
이러한 변수는 런타임 오류가 발생하면 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.
변수 | 장소 | 예 |
---|---|---|
fault.name="fault_name" |
fault_name은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다. | fault.name Matches "SpikeArrestViolation" |
ratelimit.policy_name.failed |
policy_name은 오류를 발생시킨 정책의 사용자 지정 이름입니다. | ratelimit.SA-SpikeArrestPolicy.failed = true |
오류 응답 예시
다음은 오류 응답의 예시입니다.
{ "fault":{ "detail":{ "errorcode":"policies.ratelimit.SpikeArrestViolation" }, "faultstring":"Spike arrest violation. Allowed rate : 10ps" } }
오류 규칙 예시
다음은 SpikeArrestViolation
오류를 처리하기 위한 오류 규칙의 예시입니다.
<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(너무 많은 요청)입니다.
HTTP 상태 코드를 500(내부 서버 오류)으로 변경하려면 조직 속성 업데이트 API를 사용하여 features.isHTTPStatusTooManyRequestEnabled
속성을 false
로 설정합니다.
예를 들면 다음과 같습니다.
curl -u email:password -X POST -H "Content-type:application/xml" http://apigee.googleapis.com/v1/organizations/myorg -d \ "<Organization type="trial" name="MyOrganization"> <Properties> <Property name="features.isHTTPStatusTooManyRequestEnabled">true</Property> . . . </Properties> </Organization>"
스키마
각 정책 유형은 XML 스키마(.xsd
)로 정의됩니다. 참고로 GitHub에서 정책 스키마를 사용할 수 있습니다.
관련 주제
- 할당량 정책: 개별 클라이언트의 트래픽을 제한하는 할당량 정책
- 비율 제한 개요의 비율 제한
- 할당량 및 SpokeArrest 정책 비교