Política de Detenção de pico

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

A política de SpikeArrest 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.

Esta é uma política padrão e pode ser implantada em qualquer tipo de ambiente. Nem todos os usuários têm necessidade de saber sobre os tipos de política e ambiente. Para informações sobre os tipos de políticas e a disponibilidade de cada tipo de ambiente, consulte Tipos de políticas.

A diferença entre SpikeArrest e a cota

A política de cotas configura o número de mensagens de solicitação que um aplicativo de cliente pode enviar para uma API ao longo de uma hora, dia, semana ou mês. A política de cotas impõe limites de consumo aos aplicativos de clientes mantendo um contador distribuído que combina as solicitações recebidas.

Use a cota para aplicar contratos comerciais ou SLAs a desenvolvedores e parceiros, em vez de aplicar ao gerenciamento de tráfego operacional. Use a SpikeArrest para se proteger contra picos repentinos no tráfego da API. Consulte também Como comparar as políticas de cota e detenção de pico.

Vídeos

Estes vídeos discutem casos de uso desta política:

Por que você precisa disso?

Comparar política de cotas

Elemento <SpikeArrest>

Define a política de SpikeArrest.

Valor padrão	Consulte a guia Política padrão a seguir
Obrigatório?	Opcional
Tipo	Objeto complexo
Elemento pai	n/a
Elemento filho	<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 padrão

O exemplo a seguir mostra as configurações padrão quando você adiciona uma política SpikeArrest ao 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 a seguir mostram algumas maneiras de usar a política SpikeArrest:

Exemplo 1

O exemplo a seguir define a taxa como cinco por segundo:

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

Esta política de amostra permite no máximo cinco solicitações por segundo. Por suavização, ela é aplicada no máximo uma solicitação a cada intervalo de 200 milissegundos (1.000/5).

Exemplo 2

O exemplo a seguir define a taxa para 12 por minuto:

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

Esta política de amostra permite no máximo 12 solicitações por minuto à taxa de uma solicitação por intervalo de 5 segundos (60/12). Se houver mais de uma solicitação nos cincosegundo intervalo, essas solicitações são permitidas (sem suavização), desde que o número de solicitações seja menor que o limite de taxa configurado de 12 por minuto.

Exemplo 3

O exemplo a seguir restringe solicitações a 12 por minuto (uma solicitação permitida a cada cinco segundos ou 60/12):

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

Além disso, o elemento <MessageWeight> aceita um valor personalizado (o cabeçalho weight) que ajusta os pesos das mensagens para apps ou clientes específicos. Isso proporciona controle adicional sobre a limitação de entidades identificadas com o elemento <Identifier>.

Exemplo 4

O exemplo a seguir instrui a SpikeArrest a procurar um valor de ambiente de execução definido por meio da solicitação que é transmitida como a variável de fluxo request.header.runtime_rate:

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

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

Para testar este exemplo, execute uma solicitação como esta:

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

Dica: confira Como usar produtos de API para definir limites de detenção de pico? que explique como definir a taxa SpikeArrest. usando variáveis personalizadas definidas em um produto de API.

Referência a elementos filhos

Esta seção descreve os elementos filhos 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 escolher como agrupar as solicitações, para que a política SpikeArrest 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 SpikeArrest 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.

Valor padrão	n/a
Obrigatório?	Opcional
Tipo	String
Elemento pai	<SpikeArrest>
Elemento filho	Nenhum

Sintaxe

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

Exemplo 1

O exemplo a seguir aplica a política SpikeArrest por ID de desenvolvedor:

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

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

Atributo	Descrição	Padrão	Presença
ref	Identifica a variável pela qual a SpikeArrest agrupa as solicitações recebidas. É possível usar qualquer variável de fluxo para indicar um cliente único, como aqueles disponíveis na política VerifyAPIKey. Também é possível definir variáveis personalizadas usando a política JavaScript ou a política AssignMessage.	n/a	Obrigatório

Esse problema também é discutido nesta postagem na Comunidade da Apigee.

<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 SpikeArrest. 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 SpikeArrest <Rate> for 10pm, e um app 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.

Valor padrão	n/a
Obrigatório?	Opcional
Tipo	Número inteiro
Elemento pai	<SpikeArrest>
Elemento filho	Nenhum

Sintaxe

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

Exemplo 1

O exemplo a seguir restringe solicitações a 12 por minuto (uma solicitação permitida a cada cinco segundos ou 60/12):

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

Neste exemplo, <MessageWeight> aceita um valor personalizado (o cabeçalho weight na solicitação) que ajusta os pesos das mensagens para clientes específicos. Isso proporciona controle adicional sobre a limitação de entidades identificadas com o elemento <Identifier>.

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

Atributo	Descrição	Presença	Padrã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, cabeçalho ou conteúdo do corpo da mensagem. Para mais informações, consulte a Referência de variáveis de fluxo. Também é possível definir variáveis personalizadas usando a política JavaScript ou a política AssignMessage.	Obrigatório	N/A

<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. Use o elemento <UseEffectiveCount> para definir o algoritmo de limitação de taxa usado pela política.

Observação: consulte a seção SpikeArrest da página "Limites" para ver os limites máximos de taxa que podem ser especificados.

Valor padrão	n/a
Obrigatório?	Obrigatório
Tipo	Número inteiro
Elemento pai	<SpikeArrest>
Elemento filho	Nenhum

Sintaxe

É possível especificar taxas de uma das seguintes maneiras:

• Uma taxa estática que você especifica como o corpo do elemento <Rate>
• Um valor variável, que pode ser transmitido pelo cliente; identifica o nome da variável de fluxo usando o 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 variável ou no corpo do elemento) precisam estar em conformidade com o seguinte formato:

• intps (número de solicitações por segundo, simplificadas em intervalos de milissegundos)
• intpm (número de solicitações por minuto, simplificadas em intervalos de segundos)

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

Exemplo 1

O exemplo a seguir define a taxa para cinco solicitações por segundo:

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

A política simplifica a taxa para uma solicitação permitida a cada 200 milissegundos (1000/5).

Exemplo 2

No exemplo a seguir, a taxa é definida para 12 solicitações por minuto:

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

Essa política de exemplo simplifica a taxa para uma solicitação permitida a cada cinco segundos (60/12).

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

Atributo	Descrição	Presença	Padrão
ref	Identifica uma variável de fluxo que especifica a taxa. Ele pode ser qualquer variável de fluxo, como um parâmetro de consulta HTTP, cabeçalho ou conteúdo do corpo da mensagem, ou um valor como um KVM. Para mais informações, consulte a Referência de variáveis de fluxo. Também é possível usar variáveis personalizadas usando a política JavaScript ou a política AssignMessage. Se você definir ref e o corpo desse elemento, o valor de ref será aplicado e terá precedência quando a variável de fluxo for definida na solicitação. O inverso é verdadeiro quando a variável identificada em ref não é definida na solicitação. 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 será de uma solicitação por minuto para todos os clientes. Se o cliente transmitir um cabeçalho custom_rate, o limite de taxa se tornará 10 solicitações por segundo para todos os clientes no proxy, até que uma solicitação sem o cabeçalho custom_rate seja enviada. Use <Identifier> para agrupar solicitações que impõem taxas personalizadas a diferentes tipos de clientes. Se você 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 de SpikeArrest gerará um erro.	Opcional	n/a

<UseEffectiveCount>

Esse elemento permite escolher entre algoritmos distintos de detenção de pico definindo o valor como true ou false, conforme explicado abaixo:

verdadeiro

Se definida como true, a SpikeArrest será distribuída em uma região. Isso significa que as contagens de solicitações são sincronizadas entre os processadores de mensagens (MPs) em uma região. Além disso, um algoritmo de limitação de taxa de "janela deslizante" é empregado. Esse algoritmo fornece um comportamento de limite de taxa consistente e não "nivela" o número de solicitações recebidas que podem ser enviadas para o back-end. Se uma explosão de solicitações for enviada em um curto intervalo de tempo, elas serão permitidas, desde que não excedam o limite de taxa configurado, conforme definido no elemento <Rate> , Exemplo:

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

false (padrão)

Se definida como false (padrão), a política SpikeArrest usará um algoritmo de intervalo de token que suaviza os picos de tráfego dividindo o limite de taxa especificado em intervalos menores. Uma desvantagem dessa abordagem é que várias solicitações legítimas recebidas em um curto período podem ser negadas.

Por exemplo, digamos que você insira uma taxa de 30h (30 solicitações por minuto). Durante os testes, talvez você ache que possa enviar 30 solicitações em um segundo, desde que tenham ocorrido em um minuto. Mas não é assim que a política aplica a configuração. Se você pensar nisso, 30 solicitações dentro de um período de um segundo podem ser consideradas um pequeno pico em alguns ambientes.

• As taxas por minuto são simplificadas em solicitações completas permitidas em intervalos de segundos.
  

  Por exemplo, 30pm fica mais tranquilo assim:
  60 segundos (1 minuto) / 30pm = intervalos de 2 segundos, ou 1 solicitação permitida a cada 2 segundos. Uma segunda solicitação dentro de 2 segundos falhará. Além disso, uma 31ª solicitação em um minuto falhará.

• As taxas por segundo são simplificadas nas solicitações completas permitidas em intervalos de milissegundos.

  Por exemplo, 10 ps são simplificados desta maneira:
  1.000 milissegundos (1 segundo) / 10 ps = 100 intervalos de milissegundos ou 1 solicitação permitida a cada 100 milissegundos. Uma segunda solicitação em 100 ms falhará. Além disso, uma 11ª solicitação em um segundo falhará.

Observação: na simplificação de taxa, o número de solicitações é sempre um número inteiro maior que zero. A simplificação nunca envolve o cálculo de frações de solicitações.

Valor padrão	Falso
Obrigatório?	Opcional
Tipo	Booleano
Elemento pai	<SpikeArrest>
Elemento filho	Nenhum

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

Atributo	Descrição	Padrã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, cabeçalho ou conteúdo do corpo da mensagem. Para mais informações, consulte a Referência de variáveis de fluxo. Também é possível definir variáveis personalizadas usando a política JavaScript ou a política AssignMessage.	n/a	Opcional

Variáveis de fluxo

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

Variável	Tipo	Permissão	Descrição
ratelimit.policy_name.failed	Booleano	Somente leitura	Indica se a política falhou (true ou false).

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

Referência de erros

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	Correção
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	Correção
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 status HTTP atual para exceder um limite de taxa definido por uma política de Cotas ou SpikeArrest é 429 (muitas solicitações). Para alterar o código de status HTTP para 500 (Erro interno do servidor), defina a propriedade features.isHTTPStatusTooManyRequestEnabled como false usando a API Atualizar as propriedades da organização API.

Cuidado: ao atualizar propriedades, você precisa transmitir todas as propriedades existentes à API, mesmo que elas não estejam sendo alteradas. Se você deixar as propriedades fora do payload para a chamada de API Update organization properties, elas serão removidas. Para ver a lista atual de propriedades do ambiente, use a API Get organization.

Se você tentar definir uma propriedade, mas o valor da propriedade atualizado não for retornado no payload da resposta, isso significa que a propriedade precisa ser definida por um usuário com o papel sysadmin. Entre em contato com o suporte da Apigee para alterar o valor da propriedade que requer o papel sysadmin.

Exemplo:

curl -u email:password -X POST -H "Content-type:application/xml" http://apigee.googleapis.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 de políticas de cota e detenção de pico