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	Predefinição	Obrigatório?	Descrição
name	N/A	Obrigatório	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres. Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.
continueOnError	falso	Opcional	Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar falhas no fluxo atual
enabled	verdadeiro	Opcional	Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça anexada a um fluxo.
async	falso	Descontinuado	Este atributo foi descontinuado.

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 em conjunto com o atributo name para etiquetar a política no editor de proxy da IU de gestão com um nome diferente e mais natural.

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

Valor predefinido	N/A
Obrigatório?	Opcional. Se omitir <DisplayName>, é usado o valor do atributo name da política.
Tipo	String
Elemento principal	<PolicyElement>
Elementos subordinados	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 nem elementos subordinados.

<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 secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes para saber se está a desenvolver regras de falhas para tratar falhas. Para saber mais, consulte os artigos O que precisa de saber acerca dos erros de políticas e Como processar falhas.

Erros de tempo de execução

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

Sugestão: precisa de ajuda para resolver um erro? Clique em na coluna Corrigir para ver informações detalhadas de resolução de problemas.

Código de falha	Estado de HTTP	Causa	Corrigir
policies.ratelimit.FailedToResolveSpikeArrestRate	500	Este erro ocorre se a referência à variável que contém a definição da taxa no elemento <Rate> não puder ser resolvida para um valor na política SpikeArrest. Este elemento é obrigatório e usado para especificar a taxa de restrição de picos no formato intpm ou intps.
policies.ratelimit.InvalidMessageWeight	500	Este erro ocorre se o valor especificado para o elemento <MessageWeight> através 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 implementação

Estes erros podem ocorrer quando implementa um proxy que contém esta política.

Sugestão: precisa de ajuda para resolver um erro? Clique em na coluna Corrigir para ver informações detalhadas de resolução de problemas.

Nome do erro	Causa	Corrigir
InvalidAllowedRate	Se a taxa de detenção de picos especificada no elemento <Rate> da política não for um número inteiro ou se a taxa não tiver ps ou pm como sufixo, a implementação do proxy de API falha.SpikeArrest

Variáveis de falha

Estas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte o artigo O que precisa de saber acerca dos erros de políticas.

Variáveis	Onde	Exemplo
fault.name="fault_name"	fault_name é o nome da falha, conforme indicado na tabela Erros de tempo 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 especificado pelo utilizador da política que gerou a falha.	ratelimit.SA-SpikeArrestPolicy.failed = true

Exemplo de resposta de erro

Segue-se um exemplo de uma resposta de erro:

Nota: para o processamento de erros, a prática recomendada é capturar a parte errorcode da resposta de erro. Não confie no texto no elemento faultstring, porque pode mudar.

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

Exemplo de regra de falha

Segue-se um exemplo de uma regra de falha para processar 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