<ph type="x-smartling-placeholder"></ph>
현재 Apigee Edge 문서를 보고 있습니다.
Apigee X 문서. 정보
급증 저지 정책은 <Rate>
요소를 사용하여 트래픽 급증으로부터 보호합니다. 이 요소는 API 프록시가 처리하고 백엔드로 전송되는 요청 수를 제한하여 성능 지연 및 다운타임으로부터 보호합니다.
<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>
기본 정책
다음 예는 다음 안내를 따르세요.
<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>true</UseEffectiveCount> </SpikeArrest>
이 요소에는 다음과 같이 모든 정책에 공통된 속성이 있습니다.
속성 | 기본 | 필수 여부 | 설명 |
---|---|---|---|
name |
N/A | 필수 |
정책의 내부 이름입니다. 원하는 경우 |
continueOnError |
false | 선택사항 | 정책이 실패할 때 오류를 반환하려면 'false'로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패한 후에도 흐름 실행이 계속되게 하려면 'true'로 설정합니다. |
enabled |
true | 선택 | 정책을 시행하려면 'true'로 설정합니다. 정책을 '사용 중지'하려면 'false'로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다. |
async |
false | 지원 중단됨 | 이 속성은 지원이 중단되었습니다. |
예
다음 예시에서는 급증 저지 정책을 사용하는 몇 가지 방법을 보여줍니다.
예시 1
다음 예에서는 비율을 초당 5로 설정합니다.
<SpikeArrest name="Spike-Arrest-1"> <Rate>5ps</Rate> </SpikeArrest>
이 정책은 200밀리초마다 허용되는 요청 1개(1000/5)로 비율을 평활화합니다.
예시 2
다음 예에서는 비율을 분당 12로 설정합니다.
<SpikeArrest name="Spike-Arrest-1"> <Rate>12pm</Rate> </SpikeArrest>
이 정책 예시는 5초마다 허용되는 요청 1개(60/12)로 비율을 평활화합니다.
예시 3
다음 예는 요청을 분당 12로 제한합니다(5초마다 허용되는 요청 1개, 또는 60/12).
<SpikeArrest name="Spike-Arrest-1"> <Rate>12pm</Rate> <Identifier ref="client_id" /> <MessageWeight ref="request.header.weight" /> </SpikeArrest>
또한 <MessageWeight>
요소는 특정 앱 또는 클라이언트의 메시지 가중치를 조정하는 맞춤 값(weight
헤더)을 허용합니다. 이렇게 하면 <Identifier>
요소로 식별되는 항목의 제한을 추가로 제어할 수 있습니다.
예 4
다음 예시에서는 급증 저지에 request.header.runtime_rate
흐름 변수로 전달된 요청을 통해 설정된 런타임 값을 찾도록 지시합니다.
<SpikeArrest name="Spike-Arrest-1"> <Rate ref="request.header.runtime_rate" /> </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>
클라이언트에 따라 급증 저지 정책을 적용할 수 있도록 요청을 그룹화하는 방법을 선택할 수 있습니다. 예를 들어 개발자 ID별로 요청을 그룹화할 수 있으며, 이 경우 각 개발자의 요청은 해당 프록시의 모든 요청이 아닌 자체 급증 저지 비율로 계산됩니다.
요청 제한을 보다 세밀하게 제어하려면 <MessageWeight>
요소와 함께 사용합니다.
<Identifier>
요소를 비워 두면 해당 API 프록시에 대한 모든 요청에 한 개의 비율 제한이 적용됩니다.
기본값 | 해당 사항 없음 |
필수 여부 | 선택사항 |
유형 | 문자열 |
상위 요소 |
<SpikeArrest>
|
하위 요소 | 없음 |
구문
<SpikeArrest continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Identifier ref="flow_variable"/> </SpikeArrest>
예시 1
다음 예에서는 개발자 ID별로 급증 저지 정책을 적용합니다.
<SpikeArrest name="Spike-Arrest-1"> <Identifier ref="developer.id"/> <Rate>42pm</Rate/> </SpikeArrest>
다음 표는 <Identifier>
의 속성을 설명합니다.
속성 | 설명 | 기본값 | 상태 |
---|---|---|---|
ref |
Spike Arrest가 수신 요청을 그룹화하는 데 사용하는 변수를 식별합니다. VerifyAPIKey 정책에 사용 가능한 고유한 클라이언트를 나타내는 모든 흐름 변수를 사용할 수 있습니다. 자바스크립트 정책 또는 AssignMessage 정책을 사용하여 커스텀 변수를 설정할 수도 있습니다. | 해당 사항 없음 | 필수 |
이 요소는 Apigee 커뮤니티 게시물(http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html)에서도 설명합니다.
<MessageWeight>
각 메시지에 정의된 가중치를 지정합니다. 메일 가중치는 영향을 수정함 요청 1건이라고 할 수 있습니다. 메시지 가중치는 HTTP 헤더, 쿼리 매개변수, 양식 매개변수, 메시지 본문 콘텐츠와 같은 모든 흐름 변수가 될 수 있습니다. 자바스크립트 정책 또는 AssignMessage 정책을 사용하여 커스텀 변수를 사용할 수도 있습니다.
<Identifier>
와 함께 사용하여 특정 클라이언트 또는 앱별로 요청을 추가로 제한할 수 있습니다.
예를 들어 급증 저지 <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" /> </SpikeArrest>
이 예에서 <MessageWeight>
는 특정 클라이언트의 메시지 가중치를 조정하는 맞춤 값(요청의 weight
헤더)을 허용합니다. 이렇게 하면 <Identifier>
요소로 식별되는 항목의 제한을 추가로 제어할 수 있습니다.
다음 표는 <MessageWeight>
의 속성을 설명합니다.
속성 | 설명 | 접속 상태 | 기본값 |
---|---|---|---|
ref |
특정 클라이언트의 메시지 가중치를 포함하는 흐름 변수를 식별합니다. HTTP 쿼리 매개변수, 헤더, 메시지 본문 콘텐츠와 같은 흐름 변수가 될 수 있습니다. 자세한 내용은 흐름 변수 참조를 확인하세요. 자바스크립트 정책 또는 AssignMessage 정책을 사용하여 커스텀 변수를 설정할 수도 있습니다. | 필수 | 해당 사항 없음 |
<Rate>
분당 또는 초당 간격으로 허용되는 요청 수를 설정하여 트래픽 급증(또는 버스트)을 제한하는 비율을 지정합니다. 이 요소를 <Identifier>
및 <MessageWeight>
와 함께 사용하여 클라이언트의 값을 허용해 런타임에 트래픽을 원활하게 조절할 수도 있습니다.
기본값 | 해당 사항 없음 |
필수 여부 | 필수 |
유형 | 정수 |
상위 요소 |
<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> </SpikeArrest>
이 정책은 200밀리초마다 허용되는 요청 1개(1000/5)로 비율을 평활화합니다.
예시 2
다음 예에서는 비율을 분당 요청 12개로 설정합니다.
<SpikeArrest name="Spike-Arrest-1"> <Rate>12pm</Rate> </SpikeArrest>
이 정책 예는 5초마다 허용되는 요청 1개(60/12)로 비율을 평활화합니다.
다음 표는 <Rate>
의 속성을 설명합니다.
속성 | 설명 | 접속 상태 | 기본값 |
---|---|---|---|
ref |
비율을 지정하는 흐름 변수를 식별합니다. HTTP 쿼리 매개변수, 헤더 또는 메시지 본문 콘텐츠와 같은 흐름 변수 또는 KVM과 같은 값이 될 수 있습니다. 자세한 내용은 흐름 변수 참조를 확인하세요.
자바스크립트 정책 또는 AssignMessage 정책을 사용하여 커스텀 변수를 사용할 수도 있습니다.
예: <Rate ref="request.header.custom_rate">1pm</Rate> 이 예에서 클라이언트가 'custom_rate'를 전달하지 않는 경우 헤더 다음에 API 프록시의 비율은 모든 클라이언트에 대해 분당 요청 1회입니다. 클라이언트가 'custom_rate' 헤더에 있는 경우 비율 제한은 프록시 — 'custom_rate'가 없는 요청이 있을 때까지 헤더가 전송됩니다.
|
선택 | 해당 사항 없음 |
<UseEffectiveCount>
자동 확장을 사용할 때 Spike Arrest 수를 메시지 프로세서 (MP)에 분산합니다. 액세스할 수 있습니다
구문
<SpikeArrest continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <UseEffectiveCount>[false|true]</UseEffectiveCount> </SpikeArrest>
예시 1
다음 예는 <UseEffectiveCount>
를 true로 설정합니다.
<SpikeArrest name='Spike-Arrest-1'> <Rate>40ps</Rate> <UseEffectiveCount>true</UseEffectiveCount> </SpikeArrest>
<UseEffectiveCount>
요소는 선택사항입니다. 기본값은 false
입니다.
'Spake Arrest 정책'에서 요소가 생략된 경우
기본값 | 거짓 |
필수 여부 | 선택사항 |
유형 | 불리언 |
상위 요소 |
<SpikeArrest>
|
하위 요소 | 없음 |
다음 표에서는 <UseEffectiveCount>
요소의 속성을 설명합니다.
속성 | 설명 | 기본값 | 접속 상태 |
---|---|---|---|
ref |
<UseEffectiveCount> 값이 포함된 변수를 식별합니다. HTTP 쿼리 매개변수, 헤더, 메시지 본문 콘텐츠와 같은 흐름 변수가 될 수 있습니다. 자세한 내용은 흐름 변수 참조를 확인하세요. 자바스크립트 정책 또는 AssignMessage 정책을 사용하여 커스텀 변수를 설정할 수도 있습니다. |
해당 사항 없음 | 선택사항 |
<UseEffectiveCount>
의 효과는 값에 따라 다릅니다.
true
: MP의 급증 비율 한도는<Rate>
를 동일한 포드의 현재 MP 수로 나눈 값입니다. 집계 한도는 (총<Rate>
개) 하원의원이 동적으로 추가 (또는 삭제)될 때 개별적으로 급증 비율 제한은 증가 (또는 감소)하지만 집계 제한은 동일하게 유지됩니다.false
(생략된 경우 기본값): 각 MP의 급증 비율 한도는 단순히<Rate>
의 값입니다. 집계 한도는 모든 MP의 비율 합계입니다. 의원이 추가 (또는 제거)되면 개별 급증 비율 제한은 동일하게 유지되지만 총 제한은 증가 (또는 감소).
다음 표에서는 <UseEffectiveCount>
가
각 MP:
<UseEffectiveCount> 의 값 |
||||||
---|---|---|---|---|---|---|
false |
false |
false |
true |
true |
true |
|
MP 수 | 8 | 4 | 2 | 8 | 4 | 2 |
<Rate> 의 값 |
10 | 10 | 10 | 40 | 40 | 40 |
MP당 유효 비율 | 10 | 10 | 10 | 5 | 10개 | 20 |
집계 한도 | 80 | 40 | 20 | 40* | 40* | 40* |
* <Rate> 와 동일합니다. |
이 예에서는 MP 수가 4에서 2로 감소하고
<UseEffectiveCount>
이 (가) false
인 경우 MP당 유효 요율은 동일하게 유지됩니다.
10페이지). 하지만 <UseEffectiveCount>
가 true
이면 MP당 유효 비율은
MP 수가 4에서 2로 감소하면 10에서 20으로 감소합니다.
흐름 변수
급증 저지 정책이 실행되면 다음과 같은 흐름 변수가 채워집니다.
변수 | 유형 | 권한 | 설명 |
---|---|---|---|
ratelimit.policy_name.failed |
부울 | 읽기 전용 | 정책이 실패했는지 여부를 나타냅니다(true 또는 false ). |
자세한 내용은 흐름 변수 참조를 확인하세요.
오류 참조
이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 오류 변수를 설명합니다. 이 정책이 오류를 트리거할 때 Edge에서 설정되는 값 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.
런타임 오류
이러한 오류는 정책이 실행될 때 발생할 수 있습니다.
오류 코드 | HTTP 상태 | 원인 | 수정 |
---|---|---|---|
policies.ratelimit.FailedToResolveSpikeArrestRate |
500 |
이 오류는 <Rate> 요소 내에 속도 설정이 포함된 변수의 참조를 급증 저지 정책에서의 값으로 확인할 수 없는 경우에 발생합니다. 이 요소는 필수이며 intpm 또는 intps 형식으로 급증 저지 속도를 지정하는 데 사용됩니다. |
build |
policies.ratelimit.InvalidMessageWeight |
500 |
이 오류는 흐름 변수를 통해 <MessageWeight> 요소에 지정된 값이 잘못된 경우에(정수가 아닌 값) 발생합니다. |
build |
policies.ratelimit.SpikeArrestViolation |
429 |
비율 제한을 초과했습니다. <ph type="x-smartling-placeholder"> |
배포 오류
이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.
오류 이름 | 원인 | 수정 |
---|---|---|
InvalidAllowedRate |
급증 저지 정책의 <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>
할당량 또는 급증 저지 정책에서 설정한 비율 제한을 초과하는 경우에 관한 현재 HTTP 상태 코드
429
(너무 많은 요청)입니다. HTTP 상태 코드를 500
로 변경하려면
내부 서버 오류가 발생함)에 대해
features.isHTTPStatusTooManyRequestEnabled
속성을 false
로
조직 속성 업데이트 API
예를 들면 다음과 같습니다.
curl -u email:password -X POST -H "Content-type:application/xml" http://api.enterprise.apigee.com/v1/organizations/myorg -d \ "<Organization type="trial" name="MyOrganization"> <Properties> <Property name="features.isHTTPStatusTooManyRequestEnabled">true</Property> . . . </Properties> </Organization>"
스키마
각 정책 유형은 XML 스키마(.xsd
)로 정의됩니다. 참고로 GitHub에서 정책 스키마를 사용할 수 있습니다.
관련 주제
- 할당량 정책: 개별 클라이언트의 트래픽을 제한하는 할당량 정책
- 비율 제한 개요의 비율 제한
- 할당량 및 SpikeArrest 정책
- API 프록시 작업 샘플