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 Opcionalmente, use o elemento |
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:
|
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'
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.
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 Por exemplo: <Rate ref="request.header.custom_rate">1pm</Rate> Neste exemplo, se o cliente não transmitir um cabeçalho Pode usar Se especificar um valor para |
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)
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.
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.
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 . |
build |
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). |
build |
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.
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 |
build |
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:
{ "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