SpikeArrest 정책

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

Edge UI의 Spike Arrest 아이콘

급증 저지 정책은 <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 필수

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

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

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 정책을 사용하여 커스텀 변수를 사용할 수도 있습니다.

ref 이 요소의 본문을 모두 정의하면 ref 값이 적용되고 요청에서 흐름 변수가 설정될 때 우선 적용됩니다. (ref에서 식별된 변수가 요청에 설정되지 않은 반대의 경우에도 마찬가지입니다.)

예:

<Rate ref="request.header.custom_rate">1pm</Rate>

이 예에서 클라이언트가 'custom_rate'를 전달하지 않는 경우 헤더 다음에 API 프록시의 비율은 모든 클라이언트에 대해 분당 요청 1회입니다. 클라이언트가 'custom_rate' 헤더에 있는 경우 비율 제한은 프록시 — 'custom_rate'가 없는 요청이 있을 때까지 헤더가 전송됩니다.

<Identifier>를 사용하여 요청을 그룹화하면 다양한 유형의 클라이언트에 맞춤 비율을 적용할 수 있습니다.

ref에 값을 지정하지만 <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 형식으로 급증 저지 속도를 지정하는 데 사용됩니다.
policies.ratelimit.InvalidMessageWeight 500 이 오류는 흐름 변수를 통해 <MessageWeight> 요소에 지정된 값이 잘못된 경우에(정수가 아닌 값) 발생합니다.
policies.ratelimit.SpikeArrestViolation 429

비율 제한을 초과했습니다.

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

배포 오류

이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.

오류 이름 원인 수정
InvalidAllowedRate 급증 저지 정책의 <Rate> 요소에 지정된 급증 저지 비율이 정수가 아니거나 속도에 ps 또는 pm이 서픽스로 없는 경우 API 프록시 배포가 실패합니다.

오류 변수

이러한 변수는 런타임 오류가 발생하면 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

변수 위치 예시
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

<ph type="x-smartling-placeholder">를 통해 개인정보처리방침을 정의할 수 있습니다.

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

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에서 정책 스키마를 사용할 수 있습니다.

관련 주제