Política SpikeArrest

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

A política SpikeArrest protege contra picos de tráfego com o elemento <Rate>. Este elemento limita o número de pedidos processados por um proxy de API e enviados para um back-end, protegendo contra atrasos no desempenho e tempo de inatividade.

Esta política é uma política padrão e pode ser implementada em qualquer tipo de ambiente. Para obter informações sobre os tipos de políticas e a disponibilidade com cada tipo de ambiente, consulte Tipos de políticas.

A diferença entre o SpikeArrest e a quota

A política de quotas configura o número de mensagens de pedidos que uma app cliente pode enviar a uma API ao longo de uma hora, um dia, uma semana ou um mês. A política de quotas aplica limites de consumo às apps cliente através da manutenção de um contador distribuído que regista os pedidos recebidos.

Use a quota para aplicar contratos comerciais ou SLAs com programadores e parceiros, em vez de para a gestão operacional do tráfego. Use o SpikeArrest para se proteger contra picos súbitos no tráfego da API. Consulte também a comparação entre as políticas de quota e SpikeArrest.

Vídeos

Estes vídeos abordam exemplos de utilização desta política:

Por que motivo precisa desta funcionalidade

Compare a política de quotas

<SpikeArrest> elemento

Define a política SpikeArrest.

Valor predefinido	Consulte o separador Política predefinida abaixo
Obrigatório?	Opcional
Tipo	Objeto Complex
Elemento principal	N/A
Elementos subordinados	<Identifier> <MessageWeight> <Rate> (Obrigatório) <UseEffectiveCount>

Sintaxe

O elemento <SpikeArrest> usa a seguinte sintaxe:

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

Política predefinida

O exemplo seguinte mostra as predefinições quando adiciona uma política SpikeArrest ao seu fluxo na IU:

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

Este elemento tem os seguintes atributos comuns a todas as políticas:

Atributo	Padrão	Obrigatório?	Descrição
name	N/A	Valor	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.
continueOnError	falso	Opcional	Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado para a maioria das políticas. Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual
enabled	true	Opcional	Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo que permaneça vinculada a um fluxo.
async	falso	Obsoleto	Esse atributo está obsoleto.

Exemplos

Os exemplos seguintes mostram algumas das formas como pode usar a política SpikeArrest:

Exemplo 1

O exemplo seguinte define a taxa como cinco por segundo:

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

Esta política de exemplo permite um máximo de 5 pedidos por segundo. Através da suavização, é aplicada como um máximo de um pedido por cada intervalo de 200 milissegundos (1000/5).

Exemplo 2

O exemplo seguinte define a taxa como 12 por minuto:

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

Esta política de exemplo permite um máximo de 12 pedidos por minuto à taxa de um pedido por intervalo de 5 segundos (60/12). Se houver mais do que um pedido no intervalo de 5 segundos, esses pedidos são permitidos (sem suavização), desde que o número de pedidos seja inferior ao limite de taxa configurado de 12 por minuto.

Exemplo 3

O exemplo seguinte restringe os pedidos a 12 por minuto (um pedido permitido a cada cinco segundos ou 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>

Além disso, o elemento <MessageWeight> aceita um valor personalizado (o cabeçalho weight) que ajusta as ponderações das mensagens para apps ou clientes específicos. Isto oferece um controlo adicional sobre a limitação para entidades identificadas com o elemento <Identifier>.

Exemplo 4

O exemplo seguinte indica ao SpikeArrest que procure um valor de tempo de execução definido através do pedido que é transmitido como a variável de fluxo request.header.runtime_rate:

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

O valor da variável de fluxo tem de estar no formato intpm ou intps.

Para experimentar este exemplo, execute um pedido semelhante ao seguinte:

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

Sugestão: consulte o artigo Como posso usar produtos de API para definir limites de Spike Arrest? que explica como definir a taxa de SpikeArrest através de variáveis personalizadas definidas num produto de API.

Referência de elemento secundário

Esta secção descreve os elementos subordinados de <SpikeArrest>.

<DisplayName>

Use além do atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de som diferente e mais natural.

O elemento <DisplayName> é comum a todas as políticas.

Valor padrão	N/A
Obrigatório?	Opcional. Se você omitir <DisplayName>, o valor do atributo name da política será usado
Tipo	String
Elemento pai	<PolicyElement>
Elemento filho	Nenhum

O elemento <DisplayName> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

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

O elemento <DisplayName> não tem atributos ou elementos filhos.

<Identifier>

Permite-lhe escolher como agrupar os pedidos para que a política SpikeArrest possa ser aplicada com base no cliente. Por exemplo, pode agrupar pedidos por ID de programador, caso em que os pedidos de cada programador contam para a respetiva taxa de SpikeArrest e não para todos os pedidos ao proxy.

Use em conjunto com o elemento <MessageWeight> para um controlo mais detalhado da limitação de pedidos.

Se deixar o elemento <Identifier> vazio, é aplicado um limite de taxa a todos os pedidos para esse proxy de API.

Valor predefinido	N/A
Obrigatório?	Opcional
Tipo	String
Elemento principal	<SpikeArrest>
Elementos subordinados	Nenhum

Sintaxe

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

Exemplo 1

O exemplo seguinte aplica a política SpikeArrest por ID do programador:

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

A tabela seguinte descreve os atributos de <Identifier>:

Atributo	Descrição	Predefinição	Presença
ref	Identifica a variável pela qual o SpikeArrest agrupa os pedidos recebidos. Pode usar qualquer variável de fluxo para indicar um cliente único, como as disponíveis com a política VerifyAPIKey. Também pode definir variáveis personalizadas através da política de JavaScript ou da política AssignMessage.	N/A	Obrigatória

Este elemento também é abordado nesta publicação da comunidade do Apigee.

<MessageWeight>

Especifica a ponderação definida para cada mensagem. O peso da mensagem modifica o impacto de um único pedido no cálculo da taxa de SpikeArrest. O peso da mensagem pode ser qualquer variável de fluxo, como um cabeçalho HTTP, um parâmetro de consulta, um parâmetro de formulário ou o conteúdo do corpo da mensagem. Também pode usar variáveis personalizadas através da Política de JavaScript ou da Política AssignMessage.

Use em conjunto com <Identifier> para restringir ainda mais os pedidos por clientes ou apps específicos.

Por exemplo, se o SpikeArrest <Rate> for 10pm e uma app enviar pedidos com um peso de 2, só são permitidas cinco mensagens por minuto desse cliente, porque cada pedido conta como 2.

Valor predefinido	N/A
Obrigatório?	Opcional
Tipo	Número inteiro
Elemento principal	<SpikeArrest>
Elementos subordinados	Nenhum

Sintaxe

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

Exemplo 1

O exemplo seguinte restringe os pedidos a 12 por minuto (um pedido permitido a cada cinco segundos ou 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>

Neste exemplo, <MessageWeight> aceita um valor personalizado (o cabeçalho weight no pedido) que ajusta as ponderações das mensagens para clientes específicos. Isto oferece um controlo adicional sobre a limitação para entidades identificadas com o elemento <Identifier>.

A tabela seguinte descreve os atributos de <MessageWeight>:

Atributo	Descrição	Presença	Predefinição
ref	Identifica a variável de fluxo que contém o peso da mensagem para o cliente específico. Pode ser qualquer variável de fluxo, como um parâmetro de consulta HTTP, um cabeçalho ou o conteúdo do corpo de uma mensagem. Para mais informações, consulte a Referência de variáveis de fluxo. Também pode definir variáveis personalizadas através da política de JavaScript ou da política AssignMessage.	Obrigatória	N/A

<Rate>

Especifica a taxa à qual limitar os picos (ou as rajadas) de tráfego definindo o número de pedidos permitidos em intervalos de minutos ou segundos. Também pode usar este elemento em conjunto com <Identifier> e <MessageWeight> para limitar o tráfego de forma suave no tempo de execução aceitando valores do cliente. Use o elemento <UseEffectiveCount> para definir o algoritmo de limitação de taxa usado pela política.

Nota: a utilização de <UseEffectiveCount> com um valor ou false não é suportada para nenhuma organização do Apigee nem para organizações híbridas do Apigee que executem cargas de trabalho de produção. Para mais informações, consulte <UseEffectiveCount>.

Consulte a secção SpikeArrest da página Limites para ver os limites de taxa máximos que pode especificar.

Valor predefinido	N/A
Obrigatório?	Obrigatória
Tipo	Número inteiro
Elemento principal	<SpikeArrest>
Elementos subordinados	Nenhum

Sintaxe

Pode especificar tarifas de uma das seguintes formas:

• Uma taxa estática que especifica como o corpo do elemento <Rate>
• Um valor variável, que pode ser transmitido pelo cliente; identifique o nome da variável de fluxo através do atributo ref

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

Os valores de taxa válidos (definidos como um valor de variável ou no corpo do elemento) têm de estar em conformidade com o seguinte formato:

• intps (número de pedidos por segundo, suavizado em intervalos de milissegundos)
• intpm (número de pedidos por minuto, suavizado em intervalos de segundos)

O valor de int tem de ser um número inteiro positivo diferente de zero.

Exemplo 1

O exemplo seguinte define a taxa para cinco pedidos por segundo:

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

A política suaviza a taxa para um pedido permitido a cada 200 milissegundos (1000/5).

Exemplo 2

O exemplo seguinte define a taxa como 12 pedidos por minuto:

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

Esta política de exemplo suaviza a taxa para um pedido permitido a cada cinco segundos (60/12).

A tabela seguinte descreve os atributos de <Rate>:

Atributo	Descrição	Presença	Predefinição
ref	Identifica uma variável de fluxo que especifica a taxa. Pode ser qualquer variável de fluxo, como um parâmetro de consulta HTTP, um cabeçalho ou o conteúdo do corpo de uma mensagem, ou um valor, como um KVM. Para mais informações, consulte o artigo Referência de variáveis de fluxo. Também pode usar variáveis personalizadas através da Política de JavaScript ou da Política de AssignMessage. Se definir ref e o corpo deste elemento, o valor de ref é aplicado e tem prioridade quando a variável de fluxo é definida no pedido. (O inverso é verdadeiro quando a variável identificada em ref não está definida no pedido.) Por exemplo: <Rate ref="request.header.custom_rate">1pm</Rate> Neste exemplo, se o cliente não transmitir um cabeçalho custom_rate, a taxa do proxy da API é de 1 pedido por minuto para todos os clientes. Se o cliente transmitir um cabeçalho custom_rate, o limite de taxa passa a ser de 10 pedidos por segundo para todos os clientes no proxy, até ser enviado um pedido sem o cabeçalho custom_rate. Pode usar <Identifier> para agrupar pedidos de forma a aplicar tarifas personalizadas a diferentes tipos de clientes. Se especificar um valor para ref, mas não definir a taxa no corpo do elemento <Rate> e o cliente não transmitir um valor, a política SpikeArrest gera um erro.	Opcional	N/A

<UseEffectiveCount>

Este elemento permite-lhe escolher entre algoritmos de deteção de picos distintos definindo o valor como true ou false, conforme explicado abaixo:

verdadeiro

Se estiver definido como true, o SpikeArrest é distribuído numa região. Isto significa que as contagens de pedidos são sincronizadas entre os processadores de mensagens (MPs) numa região. Além disso, é usado um algoritmo de limitação de taxa de "janela deslizante". Este algoritmo fornece um comportamento de limite de taxa consistente e não "suaviza" o número de pedidos recebidos que podem ser enviados para o back-end. Se for enviado um pico de pedidos num curto intervalo de tempo, estes são permitidos, desde que não excedam o limite de taxa configurado, conforme definido no elemento <Rate>. Por exemplo:

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

false (predefinição)

Nota: embora o valor predefinido seja false, as organizações do Apigee devem definir este elemento como true.

A suavização de tarifas não é suportada para organizações do Apigee.

Se estiver definido como false (predefinição), a política SpikeArrest usa um algoritmo de "token bucket" que suaviza os picos de tráfego dividindo o limite de taxa especificado em intervalos mais pequenos. Uma desvantagem desta abordagem é que vários pedidos legítimos recebidos num curto intervalo de tempo podem ser potencialmente recusados.

Por exemplo, suponhamos que introduz uma taxa de 30 pm (30 pedidos por minuto). Nos testes, pode pensar que pode enviar 30 pedidos em 1 segundo, desde que sejam enviados no prazo de um minuto. No entanto, não é assim que a política aplica a definição. Se pensar bem, 30 pedidos num período de 1 segundo podem ser considerados um minipico em alguns ambientes.

• As taxas por minuto são suavizadas em pedidos completos permitidos em intervalos de segundos.
  

  Por exemplo, 30 pedidos por minuto são suavizados da seguinte forma:
  60 segundos (1 minuto) / 30 pedidos por minuto = intervalos de 2 segundos ou 1 pedido permitido a cada 2 segundos. Um segundo pedido no prazo de 2 segundos falha. Além disso, um 31.º pedido num minuto vai falhar.

• As taxas por segundo são suavizadas em pedidos completos permitidos em intervalos de milissegundos.

  Por exemplo, 10ps é suavizado da seguinte forma:
  1000 milissegundos (1 segundo) / 10ps = intervalos de 100 milissegundos ou 1 pedido permitido a cada 100 milissegundos. Um segundo pedido no prazo de 100 ms vai falhar. Além disso, um 11.º pedido num segundo vai falhar.

Nota: na suavização da taxa, o número de pedidos é sempre um número inteiro superior a zero. A suavização nunca envolve o cálculo de frações de pedidos.

Valor predefinido	Falso
Obrigatório?	Opcional
Tipo	Booleano
Elemento principal	<SpikeArrest>
Elementos subordinados	Nenhum

A tabela seguinte descreve os atributos do elemento <UseEffectiveCount>:

Atributo	Descrição	Predefinição	Presença
ref	Identifica a variável que contém o valor de <UseEffectiveCount>. Pode ser qualquer variável de fluxo, como um parâmetro de consulta HTTP, um cabeçalho ou o conteúdo do corpo de uma mensagem. Para mais informações, consulte a referência de variáveis de fluxo. Também pode definir variáveis personalizadas através da política de JavaScript ou da política AssignMessage.	N/A	Opcional

Variáveis de fluxo

Quando uma política SpikeArrest é executada, a seguinte variável de fluxo é preenchida:

Variável	Tipo	Autorização	Descrição
ratelimit.policy_name.failed	Booleano	Só de leitura	Indica se a política falhou ou não (true ou false).

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

Referência de erro

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>

O código de estado HTTP atual para exceder um limite de taxa definido por uma política de quota ou SpikeArrest é 429 (Demasiados pedidos).

Esquemas

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

Tópicos relacionados

• Política de quotas: política de quotas para limitar o tráfego em clientes individuais
• Limitação de velocidade para uma vista geral da limitação de velocidade
• Comparar as políticas Quota e SpikeArrest