Política de Detenção de pico

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. informações

A política de Detenção de pico protege contra o aumento do tráfego com o elemento <Rate>. Esse elemento limita o número de solicitações processadas por um proxy de API e enviadas para um back-end, protegendo contra atrasos de desempenho e inatividade.

Elemento <SpikeArrest>

Define a política de Detenção de pico.

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

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

Exemplos

Os exemplos a seguir mostram algumas maneiras de usar a política de retenção de pico:

<SpikeArrest name="Spike-Arrest-1">
  <Rate>5ps</Rate>
</SpikeArrest>

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
</SpikeArrest>

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

<SpikeArrest name="Spike-Arrest-1">
  <Rate ref="request.header.runtime_rate" />
</SpikeArrest>

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

Referência a elementos filhos

Esta seção descreve os elementos filhos de <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.

The <DisplayName> element uses the following syntax:

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

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

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

<Identifier>

Permite escolher como agrupar as solicitações, para que a política Detenção de pico possa ser aplicada com base no cliente. Por exemplo, é possível agrupar solicitações por ID de desenvolvedor. Nesse caso, as solicitações de cada desenvolvedor serão consideradas na própria taxa de Detenção de pico e não todas as solicitações para o proxy.

Use em conjunto com o elemento <MessageWeight> para um controle mais refinado sobre a limitação de solicitações.

Se você deixar o elemento <Identifier> vazio, um limite de taxa será aplicado a todas as solicitações nesse proxy de API.

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

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

A tabela a seguir descreve os atributos de <Identifier>:

Esse elemento também é discutido na seguinte postagem da comunidade Apigee: http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html.

<MessageWeight>

Especifica a ponderação definida para cada mensagem. O peso da mensagem modifica o impacto de uma única solicitação no cálculo da taxa de Detenção de pico. O peso da mensagem pode ser qualquer variável de fluxo, como cabeçalho HTTP, parâmetro de consulta, parâmetro do formulário ou conteúdo do corpo da mensagem. Também é possível usar variáveis personalizadas com a política JavaScript ou a política AssignMessage.

Use com <Identifier> para acelerar ainda mais as solicitações de clientes ou aplicativos específicos.

Por exemplo, se a Detenção de pico <Rate> for 10pm, e um aplicativo enviar solicitações com um peso de 2, somente cinco mensagens por minuto serão permitidas desse cliente, porque cada solicitação conta como 2.

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

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

A tabela a seguir descreve os atributos de <MessageWeight>:

<Rate>

Especifica a taxa para limitar os picos de tráfego (ou bursts) definindo o número de solicitações permitidas em intervalos de minutos ou segundos. Também é possível usar esse elemento com <Identifier> e <MessageWeight> para limitar facilmente o tráfego no ambiente de execução aceitando valores do cliente.

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

<SpikeArrest name="Spike-Arrest-1">
  <Rate>5ps</Rate>
</SpikeArrest>

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
</SpikeArrest>

A tabela a seguir descreve os atributos de <Rate>:

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

<UseEffectiveCount>

Distribui suas contagens de controle de pico entre os processadores de mensagens (MPs, na sigla em inglês) ao usar grupos de escalonamento automático.

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
</SpikeArrest>

<SpikeArrest name='Spike-Arrest-1'>
  <Rate>40ps</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

O elemento <UseEffectiveCount> é opcional. O valor padrão é false quando o elemento é omitido da política de controle de pico.

A tabela a seguir descreve os atributos do elemento <UseEffectiveCount>:

O efeito de <UseEffectiveCount> depende do valor:

• true: o limite de taxa de pico de um MP é o <Rate> dividido pelo número atual de MPs no mesmo pod. O limite agregado é o valor de <Rate>. Quando os MPs são adicionados (ou removidos) dinamicamente, os limites individuais de taxa de pico aumentam (ou diminuem), mas o limite agregado permanece o mesmo.
• false (esse será o valor padrão, se omitido): o limite de taxa de pico de cada MP é simplesmente o valor de <Rate>. O limite agregado é a soma das taxas de todos os MPs. Quando os MPs são adicionados (ou removidos), os limites de taxa de pico individuais deles permanecem os mesmos, mas o limite agregado aumenta (ou diminui).

A tabela a seguir mostra o efeito de <UseEffectiveCount> no limite de taxa efetiva de cada MP:

Neste exemplo, observe que, quando o número de MPs é reduzido de 4 para 2 e <UseEffectiveCount> é false, a taxa efetiva por MP permanece a mesma (a 10). Mas quando <UseEffectiveCount> é true, a taxa efetiva por MP vai de 10 para 20 quando o número de MPs é reduzido de 4 para 2.

Variáveis de fluxo

Quando uma política de Detenção de pico é executada, a variável de fluxo a seguir é preenchida:

Para mais informações, consulte a Referência de variáveis de fluxo.

Referência de erros

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.

Deployment errors

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

Fault variables

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

Example error response

Shown below is an example error response:

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

O código de status HTTP atual para exceder um limite de taxa definido por uma política de limitação de cota ou pico é 429 (muitas solicitações). Para mudar o código de status HTTP para 500 (erro interno do servidor), defina a propriedade features.isHTTPStatusTooManyRequestEnabled como false usando a API Atualizar propriedades da organização.

Exemplo:

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

Esquemas

Cada tipo de política é definido por um esquema XML (.xsd). Para referência, os esquemas de política estão disponíveis no GitHub.

Temas relacionados

• Política de cotas: política de cotas para limitar o tráfego em clientes individuais
• Visão geral da limitação de taxa
• Comparação das políticas de cotas e SpikeArrest
• Como trabalhar com amostras de proxies de API