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>

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

Attribute	Default	Required?	Description
name	N/A	Required	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError	false	Optional	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow
enabled	true	Optional	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async	false	Deprecated	This attribute is deprecated.

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

Default Value	N/A
Required?	Optional. If you omit <DisplayName>, the value of the policy's name attribute is used.
Type	String
Parent Element	<PolicyElement>
Child Elements	None

The <DisplayName> element uses the following syntax:

Syntax

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

Example

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

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

<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

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Esses erros podem ocorrer quando a política é executada.

Dica: precisa de ajuda para resolver um erro? Clique em na coluna "Correção" para ver informações detalhadas sobre solução de problemas.

Código de falha	Status HTTP	Causa	Corrigir
policies.ratelimit.FailedToResolveSpikeArrestRate	500	Esse erro ocorrerá se a referência à variável que contém a configuração de taxa no elemento <Rate> não puder ser resolvida como um valor na política SpikeArrest. Esse elemento é obrigatório e usado para especificar a taxa de parada de pico na forma de intpm ou intps.
policies.ratelimit.InvalidMessageWeight	500	Esse erro ocorrerá se o valor especificado para o elemento <MessageWeight> por meio de uma variável de fluxo for inválido (um valor não inteiro).
policies.ratelimit.SpikeArrestViolation	429	O limite de taxa foi excedido.

Erros de implantação

Esses erros podem ocorrer quando você implanta um proxy que contém esta política.

Dica: precisa de ajuda para resolver um erro? Clique em na coluna "Correção" para ver informações detalhadas sobre solução de problemas.

Nome do erro	Causa	Corrigir
InvalidAllowedRate	Se a taxa de detenção de pico especificada no elemento <Rate> da política SpikeArrest não é um número inteiro ou se a taxa não tem ps ou pm como sufixo, a implantação do proxy da API falhará.

Variáveis de falha

Essas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.

Variáveis	Onde	Exemplo
fault.name="fault_name"	fault_name é o nome da falha, conforme listado na tabela Erros de ambiente de execução acima. O nome da falha é a última parte do código de falha.	fault.name Matches "SpikeArrestViolation"
ratelimit.policy_name.failed	policy_name é o nome da política especificada pelo usuário que gerou a falha.	ratelimit.SA-SpikeArrestPolicy.failed = true

Exemplo de resposta de erro

Veja abaixo um exemplo de resposta de erro:

Observação: para tratamento de erros, a prática recomendada é interceptar a parte errorcode da resposta de erro. Não confie no texto do faultstring, porque ele pode mudar.

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.SpikeArrestViolation"
      },
      "faultstring":"Spike arrest violation. Allowed rate : 10ps"
   }
}

Exemplo de regra de falha

Veja abaixo um exemplo de regra de falha para lidar com uma falha 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>

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