Política de Detenção de pico

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

Ícone de controle de pico na interface do Edge

A política de Detenção de pico 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.

Elemento <SpikeArrest>

Define a política de Detenção de pico.

Valor padrão Consulte a guia Política padrão a seguir
Obrigatório? Opcional
Tipo Objeto complexo
Elemento pai N/A
Elementos filhos <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 de controle de pico ao fluxo na IU do Edge:

<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>true</UseEffectiveCount>
</SpikeArrest>

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

Atributo Padrã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, 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 após a falha de uma política.
enabled verdadeiro Opcional Defina como "true" para aplicar a política. Defina como "false" para "turn off" a política. A política não será aplicada mesmo que permaneça vinculada a um fluxo.
async   falso Descontinuado Esse atributo está obsoleto.

Exemplos

Os exemplos a seguir mostram algumas maneiras de usar a política de retenção de pico:

Exemplo 1

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

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

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

Exemplo 2

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

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

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

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" />
</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 Detenção de pico 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" />
</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'

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 Nenhuma

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 Detenção de pico 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 Detenção de pico 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 de Detenção de pico por ID de desenvolvedor:

<SpikeArrest name="Spike-Arrest-1">
  <Identifier ref="developer.id"/>
  <Rate>42pm</Rate/>
</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 Detenção de pico 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 elemento também é discutido na seguinte postagem da comunidade Apigee: http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html.

<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 Detenção de pico. 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 Detenção de pico <Rate> for 10pm, e um aplicativo 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" />
</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.

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>
</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>
</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 de API será 1 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 cliente.

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 Detenção de pico gerará um erro.

Opcional N/A

<UseEffectiveCount>

Distribui suas contagens de controle de pico entre os processadores de mensagens (MPs, na sigla em inglês) ao usar grupos de escalonamento automático.

Sintaxe

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
</SpikeArrest>

Exemplo 1

O exemplo a seguir define <UseEffectiveCount> como verdadeiro:

<SpikeArrest name='Spike-Arrest-1'>
  <Rate>40ps</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

O elemento <UseEffectiveCount> é opcional. O valor padrão é false quando o elemento é omitido da política de controle de pico.

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

O efeito de <UseEffectiveCount> depende do valor:

  • true: o limite de taxa de pico de um MP é o <Rate> dividido pelo número atual de MPs no mesmo pod. O limite agregado é o valor de <Rate>. Quando os MPs são adicionados (ou removidos) dinamicamente, os limites individuais de taxa de pico aumentam (ou diminuem), mas o limite agregado permanece o mesmo.
  • false (esse será o valor padrão, se omitido): o limite de taxa de pico de cada MP é simplesmente o valor de <Rate>. O limite agregado é a soma das taxas de todos os MPs. Quando os MPs são adicionados (ou removidos), os limites de taxa de pico individuais deles permanecem os mesmos, mas o limite agregado aumenta (ou diminui).

A tabela a seguir mostra o efeito de <UseEffectiveCount> no limite de taxa efetiva de cada MP:

Valor de <UseEffectiveCount>
false false false true true true
No de MPs 8 4 2 8 4 2
Valor de <Rate> 10 10 10 40 40 40
Taxa efetiva por MP 10 10 10 5 10 20
Limite agregado 80 40 20 40* 40* 40*
* Igual a <Rate>.

Neste exemplo, observe que, quando o número de MPs é reduzido de 4 para 2 e <UseEffectiveCount> é false, a taxa efetiva por MP permanece a mesma (a 10). Mas quando <UseEffectiveCount> é true, a taxa efetiva por MP vai de 10 para 20 quando o número de MPs é reduzido de 4 para 2.

Variáveis de fluxo

Quando uma política de Detenção de pico é 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

Nesta seção, descrevemos os códigos de falha e as mensagens de erro retornados, além das variáveis de falha definidas pelo Edge quando esta 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.

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

Nome do erro Causa Corrigir
InvalidAllowedRate Se a taxa de detenção de pico especificada no elemento <Rate> da Política do Spike Arrest não é um número inteiro ou se a taxa não tem ps ou pm como um 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:

{  
   "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 limitação de cota ou pico é 429 (muitas solicitações). Para mudar o código de status HTTP para 500 (erro interno do servidor), defina a propriedade features.isHTTPStatusTooManyRequestEnabled como false usando a API Atualizar propriedades da organização.

Exemplo:

curl -u email:password -X POST -H "Content-type:application/xml" http://api.enterprise.apigee.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