Política de cotas

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X.
informações

O que

Use a política de cota para configurar o número de mensagens de solicitação que um proxy de API permite durante um período, como um minuto, uma hora, um dia, uma semana ou um mês. É possível definir a cota como a mesma para todos os apps que acessam o proxy da API ou definir a cota com base em:

  • O produto que contém o proxy da API
  • O app que solicita a API
  • O desenvolvedor do app
  • Vários outros critérios

Não use a cota para se proteger contra picos de tráfego gerais. Para isso, use a política Spike Arrest. Consulte a política Spike Arrest.

Vídeos

Estes vídeos introduzem o gerenciamento de cotas com a política de cotas:

Introdução (novo Edge)

Introdução (Edge classico)

Cota dinâmica

Distribuído e síncrono

Peso da mensagem

Agenda

Janela contínua

Flexível

Cota condicional

Variáveis de fluxo

Como lidar com erros

Amostras

Estes exemplos de códigos de política ilustram como iniciar e encerrar períodos de cota:

Mais cota dinâmica

<Quota name="CheckQuota"> 
  <Interval ref="verifyapikey.verify-api-key.apiproduct.developer.quota.interval">1</Interval>
  <TimeUnit ref="verifyapikey.verify-api-key.apiproduct.developer.quota.timeunit">hour</TimeUnit>
  <Allow count="200" countRef="verifyapikey.verify-api-key.apiproduct.developer.quota.limit"/>
</Quota>

As cotas dinâmicas permitem que você configure uma única política de cota que impõe diferentes configurações de cota com base nas informações transmitidas para essa política. Outro termo para as configurações de cota neste contexto é "Plano de serviço". A cota dinâmica verifica o "Plano de serviço" dos apps e aplica essas configurações.

Observação: se você especificar um valor e uma referência para um elemento, a referência terá a prioridade. Se a referência não for resolvida no momento da execução, o valor será usado.

Por exemplo, ao criar um produto de API, você tem a opção de definir o limite de cota, a unidade de tempo e o intervalo permitidos. No entanto, definir esses valores no produto de API não impõe o uso em um proxy de API. Você também precisa adicionar uma política de cotas ao proxy da API que lê esses valores. Consulte Criar produtos de API para saber mais.

No exemplo acima, o proxy de API que contém a política de cota usa uma política VerifyAPIKey chamada verify-api-key para validar a chave de API transmitida em uma solicitação. A política de cotas acessa as variáveis de fluxo da política VerifyAPIKey para ler os valores de cota definidos no produto da API. Para mais informações sobre as variáveis de fluxo do VerifyAPIKey, consulte Verificar a política de chaves de API.

Outra opção é definir atributos personalizados em desenvolvedores ou apps individuais e ler esses valores na política de cotas. Por exemplo, você quer definir valores de cota diferentes por desenvolvedor. Nesse caso, defina atributos personalizados no desenvolvedor contendo o limite, a unidade de tempo e o intervalo. Em seguida, faça referência a esses valores na política de cotas, conforme mostrado abaixo:

<Quota name="DeveloperQuota"> 
  <Identifier ref="verifyapikey.verify-api-key.client_id"/> 
  <Interval ref="verifyapikey.verify-api-key.developer.timeInterval"/> 
  <TimeUnit ref="verifyapikey.verify-api-key.developer.timeUnit"/> 
  <Allow countRef="verifyapikey.verify-api-key.developer.limit"/> 
</Quota>

Este exemplo também usa as variáveis de fluxo VerifyAPIKey para fazer referência aos atributos personalizados definidos no desenvolvedor.

Use qualquer variável para definir os parâmetros da política de cotas. Essas variáveis podem ser provenientes de:

  • Variáveis de fluxo
  • Propriedades sobre o produto, aplicativo ou desenvolvedor de API
  • Um mapa de chave-valor (KVM)
  • Um cabeçalho, parâmetro de consulta, parâmetro de formulário etc.

Para cada proxy de API, é possível adicionar uma política de cota que referencie a mesma variável de todas as outras políticas de cota em todos os outros proxies ou a política de cotas pode referenciar variáveis exclusivas para essa política e proxy.

Horário de início

<Quota name="QuotaPolicy" type="calendar">
  <StartTime>2017-02-18 10:30:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

Para uma cota com type definido como calendar, defina um valor <StartTime> explícito. O valor de hora é o horário GMT, não horário local. Se você não fornecer um valor <StartTime> para uma política do tipo calendar, o Edge emitirá um erro.

O contador de cotas de cada aplicativo é atualizado com base nos valores de <StartTime>, <Interval> e <TimeUnit>. Para este exemplo, a cota começa a contar às 10h30 GMT em 18 de fevereiro de 2017 e é atualizada a cada cinco horas. Portanto, a próxima atualização é às 15h30 GMT, em 18 de fevereiro de 2017.

Contador de acessos

<Quota name="QuotaPolicy">
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

Um proxy de API tem acesso às variáveis de fluxo definidas pela política de cotas. Acesse essas variáveis de fluxo no proxy da API para executar o processamento condicional, monitorar a política conforme ela se aproxima do limite da cota, retornar o contador de cotas atual para um app ou por outras razões.

Como o acesso das variáveis de fluxo para a política é baseado no atributo name das políticas, para a política acima chamada QuotaPolicy, você acessa as variáveis do fluxo no formulário:

  • ratelimit.QuotaPolicy.allowed.count: contagem permitida.
  • ratelimit.QuotaPolicy.used.count: valor do contador atual.
  • ratelimit.QuotaPolicy.expiry.time: horário UTC quando o contador é redefinido.

Há muitas outras variáveis de fluxo que você pode acessar, conforme descrito abaixo.

Por exemplo, use a seguinte política AssignMessage para retornar os valores das variáveis do fluxo de cota como cabeçalhos de resposta:

<AssignMessage async="false" continueOnError="false" enabled="true" name="ReturnQuotaVars">
    <AssignTo createNew="false" type="response"/>
    <Set>
        <Headers>
            <Header name="QuotaLimit">{ratelimit.QuotaPolicy.allowed.count}</Header>
            <Header name="QuotaUsed">{ratelimit.QuotaPolicy.used.count}</Header>
            <Header name="QuotaResetUTC">{ratelimit.QuotaPolicy.expiry.time}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

Primeira solicitação

<Quota name="MyQuota">
  <Interval>1</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="10000"/>
</Quota>

Use este código de amostra para aplicar uma cota de 10.000 chamadas por hora. A política redefine o contador de cotas na parte superior de cada hora. Se o contador atingir a cota de 10.000 chamadas antes do fim da hora, as chamadas além de 10.000 serão rejeitadas.

Por exemplo, se o contador começar em 2017-07-08 07:00:00, ele será redefinido para 0 às 2017-07-08 08:00:00 (1 hora a partir do horário de início). Se a primeira mensagem for recebida em 2017-07-08 07:35:28 e a contagem de mensagens alcançar 10.000 antes de 2017-07-08 08:00:00, as chamadas além dessa contagem serão rejeitadas até que a contagem seja redefinida no topo da hora.

O tempo de redefinição de contador é baseado na combinação de <Interval> e <TimeUnit>. Por exemplo, se você definir <Interval> como 12 para uma <TimeUnit> de hora, o contador será redefinido a cada 12 horas. Você pode definir <TimeUnit> como minuto, hora, dia, semana ou mês.

Você pode referenciar essa política em vários lugares no proxy da API. Por exemplo, você pode colocá-lo no pré-fluxo de proxy para que ele seja executado em todas as solicitações. Também é possível colocá-lo em vários fluxos no proxy da API. Se você usar essa política em vários lugares no proxy, ela manterá um único contador atualizado por todas as instâncias da política.

Se preferir, defina várias políticas de cota no seu proxy de API. Cada política de cota mantém o próprio contador, com base no atributo name da política.

Definir identificador

<Quota name="QuotaPolicy" type="calendar">
  <Identifier ref="request.header.clientId"/> 
  <StartTime>2017-02-18 10:00:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

Por padrão, uma política de cotas define um único contador para o proxy da API, independentemente da origem de uma solicitação. Como alternativa, é possível usar o atributo <Identifier> com uma política de cota para manter contadores separados com base no valor do atributo <Identifier>.

Por exemplo, use a tag <Identifier> para definir contadores separados para cada ID do cliente. Em uma solicitação ao seu proxy, o app cliente transmite um cabeçalho contendo clientID, conforme mostrado no exemplo acima.

É possível especificar qualquer variável de fluxo para o atributo <Identifier>. Por exemplo, é possível especificar que um parâmetro de consulta chamado id contenha o identificador exclusivo:

<Identifier ref="request.queryparam.id"/>

Se você usar a política VerifyAPIKey para validar a chave de API ou as políticas OAuthV2 com tokens OAuth, poderá usar informações na chave da API ou no token para definir contadores individuais para a mesma política de cotas. Por exemplo, a tag <Identifier> a seguir usa a variável de fluxo client_id de uma política VerifyAPIKey chamada verify-api-key:

<Identifier ref="verifyapikey.verify-api-key.client_id"></Identifier>

Cada valor client_id exclusivo agora define seu próprio contador na política de cotas.

Classe

<Quota name="QuotaPolicy">
  <Interval>1</Interval>
  <TimeUnit>day</TimeUnit>
  <Allow>
    <Class ref="request.header.developer_segment">
      <Allow class="platinum" count="10000"/>
      <Allow class="silver" count="1000" />
    </Class>
  </Allow>
</Quota>

Você pode definir limites de cota dinamicamente usando uma contagem de cotas baseada em classe. Neste exemplo, o limite de cota é determinado pelo valor do cabeçalho developer_segment transmitido com cada solicitação. Essa variável pode ter um valor de platinum ou silver. Se o cabeçalho tiver um valor inválido, a política retornará um erro de violação de cota.


Sobre a política de cotas

Uma cota é uma cota de mensagens de solicitação que um proxy de API pode manipular durante um período, como minuto, hora, dia, semana ou mês. A política mantém contadores que processam o número de solicitações recebidas pelo proxy da API. Esse recurso permite que os provedores de APIs apliquem limites ao número de chamadas de API feitas por apps em um intervalo de tempo. Com as políticas de cota, é possível, por exemplo, limitar aplicativos a uma solicitação por minuto ou a 10.000 solicitações por mês.

Por exemplo, se uma cota for definida como 10.000 mensagens por mês, o limite de taxa começará após 10.000 mensagens. Não importa se 10 mensagens foram contadas no primeiro dia ou no último dia desse período. nenhuma área de solicitações adicionais é permitida até que o contador de cotas seja automaticamente redefinido ao final do intervalo de tempo especificado ou até que a cota seja redefinida explicitamente usando a política de redefinição de cota.

Uma variação da Quota chamada SpikeArrest impede picos de tráfego (ou bursts) que podem ser causados por um aumento repentino no uso, clientes com bugs ou ataques mal-intencionados. Para mais informações sobre o SpikeArrest, consulte a política de Spider Arrest.

As cotas se aplicam a proxies de API individuais e não são distribuídas entre proxies de API. Por exemplo, se você tiver três proxies de API em um produto, uma única cota não será compartilhada entre os três, mesmo se os três usarem a mesma configuração de política de cota.

Tipos de políticas de cotas

A política de cotas é compatível com vários tipos diferentes de políticas: padrão, calendar, flexi e rollingwindow. Cada tipo define quando o contador de cotas começa e quando é redefinido, conforme mostrado na tabela a seguir:

Unidade de tempo Redefinição padrão (ou nula) redefinição de agenda redefinição flexível
minuto Início do próximo minuto Um minuto depois de <StartTime> Um minuto após a primeira solicitação
hora Começo da próxima hora Uma hora depois de <StartTime> Uma hora após a primeira solicitação
dia Meia-noite GMT do dia atual 24 horas depois de <StartTime> 24 horas após a primeira solicitação
semana Meia-noite (GMT) no final da semana Uma semana depois de <StartTime> Uma semana depois da primeira solicitação
mês Meia-noite (GMT) do último dia do mês Um mês (28 dias) depois de <StartTime> Um mês (28 dias) após a primeira solicitação

Para type="calendar", é preciso especificar o valor de <StartTime>.

A tabela não lista o valor para o tipo rollingwindow. As cotas de janela contínua funcionam definindo o tamanho de uma "janela" de cota, como uma janela de uma hora ou um dia. Quando uma nova solicitação entra, a política determina se a cota foi excedida na última "janela".

Por exemplo, você define uma janela de duas horas que permite 1.000 solicitações. Uma nova solicitação chega às 16h45.A política calcula a contagem de cotas para as duas últimas horas, o que significa o número de solicitações desde as 14h45. Se o limite de cota não tiver sido excedido na janela de duas horas, a solicitação será permitida.

Um minuto depois, às 16h46, aparece outra solicitação. Agora, a política calcula a contagem de cotas desde 14h46, para determinar se o limite foi excedido.

Para o tipo rollingwindow, o contador nunca é redefinido, mas é recalculado em cada solicitação.

Noções básicas sobre contadores de cota

Por padrão, uma política de cotas mantém um único contador, independentemente de quantas vezes você faz referência a ela em um proxy de API. O nome do contador de cotas é baseado no atributo name da política.

Por exemplo, crie uma política de cotas chamada MyQuotaPolicy com um limite de cinco solicitações e coloque-a em vários fluxos (Fluxo A, B e C) no proxy da API. Mesmo sendo usado em vários fluxos, ele mantém um único contador atualizado por todas as instâncias da política:

  • O fluxo A é executado -> MyQuotaPolicy é executada e seu contador = 1
  • O fluxo B é executado -> MyQuotaPolicy é executada e seu contador = 2
  • O fluxo A é executado -> MyQuotaPolicy é executada e seu contador = 3
  • O fluxo C é executado -> MyQuotaPolicy é executada e seu contador = 4
  • O fluxo A é executado -> MyQuotaPolicy é executada e seu contador = 5

A próxima solicitação para qualquer um dos três fluxos é rejeitada porque o contador de cotas atingiu o limite.

Usar a mesma política de cotas em mais de um lugar em um fluxo de proxy de API, o que pode fazer com que a cota acabe mais rápido do que o esperado, é um antipadrão descrito em O livro dos antipadrões da Apigee Edge (em inglês).

Como alternativa, defina várias políticas de cota no proxy da API e use uma política diferente em cada fluxo. Cada política de cota mantém seu próprio contador, com base no atributo name da política.

Ou use os elementos <Class> ou <Identifier> na política de cotas para definir vários contadores exclusivos em uma única política. Ao usar esses elementos, uma única política pode manter diferentes contadores com base no aplicativo que faz a solicitação, no desenvolvedor do aplicativo que fez a solicitação, um ID do cliente ou outro identificador de cliente e muito mais. Veja os exemplos acima para mais informações sobre como usar os elementos <Class> ou <Identifier>.

Notação de tempo

Todos os horários de cota são definidos com o fuso horário Coordenado universal (UTC, na sigla em inglês).

A notação de tempo de cota segue a notação de data padrão internacional definida no padrão internacional ISO 8601.

As datas são definidas como ano, mês e dia no seguinte formato: YYYY-MM-DD. Por exemplo, 2015-02-04 representa 4 de fevereiro de 2015.

A hora do dia é definida como horas, minutos e segundos no seguinte formato: hours:minutes:seconds. Por exemplo, 23:59:59 representa o tempo um segundo antes da meia-noite.

Observe que duas notações, 00:00:00 e 24:00:00, estão disponíveis para distinguir as duas meias-noites que podem ser associadas a uma data. Portanto, 2015-02-04 24:00:00 tem a mesma data e hora que 2015-02-05 00:00:00. O último geralmente é a notação preferida.

Como conseguir configurações de cota da configuração do produto da API

Você pode definir limites de cota em configurações de produtos de API. Esses limites não impõem a cota automaticamente. Em vez disso, é possível fazer referência às configurações de cota do produto em uma política de cota. Veja algumas vantagens de definir uma cota no produto para políticas de cota:

  • As políticas de cota podem usar uma configuração uniforme em todos os proxies de API no produto da API.
  • Você pode fazer alterações no ambiente de execução na configuração de cota de um produto da API, e as políticas de cota que fazem referência ao valor têm valores de cota atualizados automaticamente.

Para saber mais sobre como usar as configurações de cota de um produto da API, consulte o exemplo "Cota dinâmica" acima..

Para informações sobre como configurar produtos de API com limites de cota, consulte Criar produtos de API.

Referência de elemento

Veja a seguir elementos e atributos que podem ser configurados com esta política. Observe que algumas combinações de elementos são mutuamente exclusivas ou não obrigatórias. Consulte as amostras para uso específico. As variáveis verifyapikey.VerifyAPIKey.apiproduct.* abaixo estão disponíveis por padrão quando uma política Verify Key da API chamada "VerifyAPIKey" é usada para verificar a chave de API do app na solicitação. Os valores das variáveis vêm das configurações de cota no produto da API a que a chave está associada, conforme descrito em Como conseguir configurações de cota da configuração de produto da API.

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>
   <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="5000"/>
        <Allow class="off_peak_time" count="1000"/>
      </Class>
   </Allow>
   <Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval> 
   <TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2017-7-16 12:00:00</StartTime> 
   <Distributed>false</Distributed> 
   <Synchronous>false</Synchronous> 
   <AsynchronousConfiguration> 
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds> 
      <SyncMessageCount>5</SyncMessageCount> 
   </AsynchronousConfiguration> 
   <Identifier/> 
   <MessageWeight/> 
</Quota>

Atributos de <Quota>

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">

Os atributos a seguir são específicos dessa política.

Atributo Descrição Padrão Presença
tipo

Use para determinar quando e como o contador de cotas verifica o uso da cota. Consulte Tipos de políticas de cota para mais informações.

Se você omitir um valor type, o contador começará no início do minuto/hora/dia/semana/mês.

Valores válidos:

  • calendar: configure uma cota com base em um horário de início explícito. O contador de cotas de cada aplicativo é atualizado com base nos valores de <StartTime>, <Interval> e <TimeUnit> que você definir.
  • rollingwindow: configure uma cota que usa uma "janela de rolamento" para determinar o uso da cota. Com rollingwindow, você determina o tamanho da janela com os elementos <Interval> e <TimeUnit>; por exemplo, um dia. Quando uma solicitação é recebida, o Edge analisa o horário exato da solicitação (por exemplo, 17h01), conta o número de solicitações recebidas entre as 17h e as 17h01 do dia anterior (1 dia). e determina se a cota foi excedida durante essa janela.
  • flexi: configure uma cota que faz com que o contador comece quando a primeira mensagem de solicitação for recebida de um app e é redefinida com base nos valores <Interval>, e <TimeUnit>.
Agenda Opcional

A tabela a seguir descreve atributos comuns a todos os elementos pai de políticas:

Atributo Descrição Padrão Presença
name

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.

N/A Obrigatório
continueOnError

Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas.

Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar.

falso Opcional
enabled

Defina como true para aplicar a política.

Defina como false para desativar a política. A política não será aplicada mesmo se ela permanecer anexada a um fluxo.

true Opcional
async

Esse atributo está obsoleto.

falso Obsoleto

Elemento <DisplayName>

Use em conjunto com o atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

<DisplayName>Policy Display Name</DisplayName>
Padrão

N/A

Se você omitir esse elemento, será usado o valor do atributo name da política.

Presença Opcional
Tipo String

Elemento <Allow>

Especifica o limite de contagem da cota. Se o contador da política atingir esse valor de limite, as chamadas subsequentes serão rejeitadas até que o contador seja redefinido.

Veja abaixo três maneiras de definir o elemento <Allow>:

<Allow count="2000"/> 
<Allow countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> 
<Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> 

Se você especificar count e countRef, countRef terá a prioridade. Se countRef não for resolvido no ambiente de execução, o valor de count será usado.

Padrão: N/A
Presença: Opcional
Tipo: Número inteiro

Atributos

Atributo Descrição Padrão Presença
count

Use para especificar um número de mensagens para a cota.

Por exemplo, um valor de atributo count de 100, Interval de 1 e TimeUnit do mês especifica uma cota de 100 mensagens por mês.

2000 Opcional
countRef

Use para especificar uma variável de fluxo que contenha a contagem de mensagens para uma cota. countRef tem precedência sobre o atributo count.

nenhum Opcional

Elemento <Allow>/<Class>

O elemento <Class> permite que você condicionalmente o valor do elemento <Allow> com base no valor de uma variável de fluxo. Para cada tag filha <Allow> diferente de <Class>, a política mantém um contador diferente.

Para usar o elemento <Class>, especifique uma variável de fluxo usando o atributo ref para a tag <Class>. O Edge usa o valor da variável de fluxo para selecionar uma das tags filhas <Allow> para determinar a contagem permitida da política. O Edge combina o valor da variável de fluxo com o atributo class da tag <Allow>, conforme mostrado abaixo.

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

Neste exemplo, o contador de cotas atual é determinado pelo valor do parâmetro de consulta time_variable transmitido com cada solicitação. Essa variável pode ter um valor de peak_time ou off_peak_time. Se o parâmetro de consulta contiver um valor inválido, a política retornará um erro de violação de cota.

Padrão: N/A
Presença: Opcional
Tipo: N/A

Atributos

Atributo Descrição Padrão Presença
ref

Use para especificar uma variável de fluxo contendo a classe de cota para uma cota.

nenhum Obrigatório

Elemento <Allow>/<Class>/<Allow>

O elemento <Allow> especifica o limite de um contador de cotas definido pelo elemento <Class>. Para cada tag filha <Allow> diferente de <Class>, a política mantém um contador diferente.

Exemplo:

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

Neste exemplo, a política de cotas mantém dois contadores de cota chamados peak_time e off_peak_time.

Padrão: N/A
Presença: Opcional
Tipo: N/A

Atributos

Atributo Descrição Padrão Presença
classe

Define o nome do contador de cotas.

nenhum Obrigatório
count Especifica o limite de cota para o contador. nenhum Obrigatório

Elemento <Interval>

Use para especificar um número inteiro (por exemplo, 1, 2, 5, 60 e assim por diante) que será pareado com a TimeUnit especificada (minuto, hora, dia, semana ou mês) para determinar um período em que o Edge calcula o uso da cota.

Por exemplo, uma Interval de 24 com TimeUnit de hour significa que a cota será calculada ao longo de 24 horas.

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>
Padrão: nenhum
Presença: Obrigatório
Tipo: Número inteiro

Atributos

Atributo Descrição Padrão Presença
ref

Use para especificar uma variável de fluxo contendo o intervalo de uma cota. ref tem precedência sobre um valor de intervalo explícito. Se a referência e o valor forem especificados, a referência terá a prioridade. Se ref não for resolvido no ambiente de execução, o valor será usado.

nenhum Opcional

Elemento <TimeUnit>

Use para especificar a unidade de tempo aplicável à cota.

Por exemplo, uma Interval de 24 com TimeUnit de hour significa que a cota será calculada ao longo de 24 horas.

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
Padrão: nenhum
Presença: Obrigatório
Tipo:

String. Selecione entre minute, hour, day, week ou month.

Atributos

Atributo Descrição Padrão Presença
ref Use para especificar uma variável de fluxo contendo a unidade de tempo de uma cota. ref tem precedência sobre um valor de intervalo explícito. Se ref não for resolvido no ambiente de execução, o valor será usado. nenhuma Opcional

Elemento <StartTime>

Quando type for definido como calendar,, especifica a data e a hora em que o contador de cotas começará a contagem, independentemente de as solicitações terem sido recebidas de qualquer aplicativo.

Forneça um StartTime explícito quando type estiver explicitamente definido como calendar,, não será possível usar uma referência a uma variável de fluxo, se você especificar um valor StartTime quando não houver type for definido, e você receberá um erro.

Exemplo:

<StartTime>2017-7-16 12:00:00</StartTime>
Padrão: nenhum
Presença: Obrigatório quando type estiver definido como calendar.
Tipo:

String no formato de data e hora ISO 8601.

Elemento <Distributed>

Uma instalação do Edge pode usar um ou mais processadores de mensagens para processar solicitações. Defina esse elemento como true para especificar que a política precisa manter um contador central e sincronizá-la continuamente em todos os processadores de mensagens. Os processadores de mensagens podem estar entre zonas de disponibilidade e/ou regiões.

Se você usar o valor padrão de false, poderá exceder sua cota porque a contagem de cada processador de mensagens não é compartilhada:

<Distributed>true</Distributed>

Para garantir que os contadores sejam sincronizados e atualizados em cada solicitação, defina <Distributed> e <Synchronous> como verdadeiro:

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>
Padrão: falso
Presença: Opcional
Tipo: Booleanos

Elemento <Synchronous>

Defina como true para atualizar um contador de cotas distribuídas de forma síncrona. Isso significa que a atualização para o contador é feita ao mesmo tempo em que a cota é verificada em uma solicitação à API. Defina como true se for essencial que você não permita chamadas de API acima da cota.

Defina como false para atualizar o contador de cotas de forma assíncrona. Isso significa que é possível que algumas chamadas de API que excedam a cota passem, dependendo de quando o contador de cotas no repositório central for atualizado de forma assíncrona. No entanto, você não enfrentará os possíveis impactos de desempenho associados a atualizações síncronas.

O intervalo de atualização assíncrona padrão é de 10 segundos. Use o elemento AsynchronousConfiguration para configurar esse comportamento assíncrono.

<Synchronous>false</Synchronous>
Padrão: falso
Presença: Opcional
Tipo: Booleanos

Elemento <AsynchronousConfiguration>

Configura o intervalo de sincronização entre contadores de cota distribuídos quando o elemento de configuração da política <Synchronous> não está presente ou presente e é definido como false.

É possível sincronizar após um período ou uma contagem de mensagens usando os elementos filhos SyncIntervalInSeconds ou SyncMessageCount. Eles são mutuamente exclusivos. Por exemplo:

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

ou

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
Padrão: SyncIntervalInSeconds = 10 segundos
Presença: Opcional; ignorado quando <Synchronous> está definido como true.
Tipo:

Complexo

Elemento <AsynchronousConfiguration>/<SyncIntervalInSeconds>

Use-o para modificar o comportamento padrão em que atualizações assíncronas são realizadas após um intervalo de 10 segundos.

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

O intervalo de sincronização precisa ser >= 10 segundos, conforme descrito no tópico Limites.

Padrão: 10
Presença: Opcional
Tipo:

Inteiro

Elemento <AsynchronousConfiguration>/<SyncMessageCount>

Especifica o número de solicitações em todos os processadores de mensagens da Apigee entre atualizações de cota.

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

Neste exemplo, especificamos que a contagem de cota é atualizada a cada cinco solicitações em cada processador de mensagens do Apigee Edge.

Padrão: n/a
Presença: Opcional
Tipo:

Inteiro

Elemento <Identifier>

Use o elemento <Identifier> para configurar a política e criar contadores exclusivos com base em uma variável de fluxo.

Você pode criar contadores exclusivos para as características definidas por uma variável de fluxo. Por exemplo, você pode usar o endereço de e-mail do desenvolvedor para vincular uma cota a um desenvolvedor específico. É possível usar uma variedade de variáveis para identificar uma cota, seja usando variáveis personalizadas ou predefinidas, como aquelas disponíveis com a política de verificação de chaves de API. Consulte também a referência de variáveis.

Se você não usar esse elemento, a política usará um único contador aplicado na cota.

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.

<Identifier ref="verifyapikey.verify-api-key.client_id"/>
Padrão: N/A
Presença: Opcional
Tipo:

String

Atributos

Atributo Descrição Padrão Presença
ref

Especifica uma variável de fluxo que identifica o contador a usar para a solicitação. O identificador pode ser um cabeçalho HTTP, parâmetro de consulta, parâmetro de formulário ou conteúdo de mensagem exclusivo para cada aplicativo, usuário do aplicativo, desenvolvedor de aplicativo, produto de API ou outra característica.

O <Identifier> mais usado para identificar apps de forma exclusiva é o client_id. O client_id é outro nome para a chave de API, ou chave de consumidor, gerada para um aplicativo quando ele é registrado em uma organização no Apigee Edge. Você pode usar esse identificador se tiver ativado as chaves de autorização da API ou do OAuth na API.

Em algumas circunstâncias, as configurações de cota precisam ser recuperadas onde nenhuma client_id está disponível, como quando nenhuma política de segurança está em vigor. Nessas situações, é possível usar a política de entidade de acesso para recuperar as configurações adequadas do produto de API, extrair valores usando ExtractVariables e, em seguida, usar a variável de contexto extraída na política de cota. Para mais informações, consulte Política de acesso a entidades.

N/D Opcional

Elemento <MessageWeight>

Use para especificar o peso atribuído a cada mensagem. Use o peso da mensagem para aumentar o impacto das mensagens de solicitação que, por exemplo, consomem mais recursos computacionais do que outras.

Por exemplo, você quer contar as mensagens POST como duas vezes mais pesadas ou caras, como as mensagens GET. Portanto, você define MessageWeight como 2 para um POST e 1 para um GET. É possível até mesmo definir MessageWeight como 0 para que a solicitação não afete o contador. Neste exemplo, se a cota for de 10 mensagens por minuto e o MessageWeight para solicitações POST for 2, a cota permitirá cinco solicitações POST em qualquer intervalo de 10 minutos. Qualquer solicitação adicional, POST ou GET, antes da rejeição das reinicializações.

Um valor que representa MessageWeight precisa ser especificado por uma variável de fluxo e pode ser extraído de cabeçalhos HTTP, parâmetros de consulta, uma carga de solicitação XML ou JSON ou qualquer outra variável de fluxo. Por exemplo, você a define em um cabeçalho chamado weight:

<MessageWeight ref="message_weight"/>
Padrão: N/A
Presença: Opcional
Tipo:

Inteiro

Variáveis de fluxo

As seguintes variáveis de fluxo predefinidas são preenchidas automaticamente quando uma política de cotas é executada. Para mais informações sobre as variáveis de fluxo, consulte a Referência de variáveis.

Variáveis Tipo Permissões Descrição
ratelimit.{policy_name}.allowed.count Longo Somente leitura Retorna a contagem de cotas permitida
ratelimit.{policy_name}.used.count Longo Somente leitura Retorna a cota atual usada dentro de um intervalo de cotas
ratelimit.{policy_name}.available.count Longo Somente leitura Retorna a contagem de cotas disponíveis no intervalo de cotas
ratelimit.{policy_name}.exceed.count Longo Somente leitura Retorna 1 após a cota ser excedida.
ratelimit.{policy_name}.total.exceed.count Longo Somente leitura Retorna 1 após a cota ser excedida.
ratelimit.{policy_name}.expiry.time Longo Somente leitura

Retorna o horário UTC em milissegundos que determina quando a cota expira e um novo intervalo é iniciado.

Quando o tipo de política de cotas é rollingwindow, esse valor não é válido porque o intervalo de cota nunca expira.

ratelimit.{policy_name}.identifier String Somente leitura Retorna a referência do identificador (cliente) anexada à política
ratelimit.{policy_name}.class String Somente leitura Retorna a classe associada ao identificador do cliente
ratelimit.{policy_name}.class.allowed.count Longo Somente leitura Retorna a contagem de cotas permitidas definida na classe
ratelimit.{policy_name}.class.used.count Longo Somente leitura Retorna a cota usada dentro de uma classe
ratelimit.{policy_name}.class.available.count Longo Somente leitura Retorna a contagem de cotas disponíveis na classe
ratelimit.{policy_name}.class.exceed.count Longo Somente leitura Retorna a contagem de solicitações que excede o limite da classe no intervalo de cota atual.
ratelimit.{policy_name}.class.total.exceed.count Longo Somente leitura Retorna a contagem total de solicitações que excedem o limite na classe em todos os intervalos de cota. Portanto, é a soma de class.exceed.count para todos os intervalos de cota.
ratelimit.{policy_name}.failed Booleano Somente leitura

Indica se a política falhou (verdadeiro ou falso).

Referência de erros

Nesta seção, descrevemos os códigos e as mensagens de erro retornados e as variáveis de falha definidas pelo Edge quando a 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 Correção
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 Ocorre se o elemento <Interval> não estiver definido na política de cotas. Esse elemento é obrigatório e usado para especificar o intervalo de tempo aplicável à cota. O intervalo de tempo pode ser minutos, horas, dias, semanas ou meses, conforme definido com o elemento <TimeUnit>.
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference 500 Ocorre se o elemento <TimeUnit> não estiver definido na política de cotas. Esse elemento é obrigatório e é usado para especificar a unidade de tempo aplicável à cota. O intervalo de tempo pode ser de minutos, horas, dias, semanas ou meses.
policies.ratelimit.InvalidMessageWeight 500 Ocorre se o valor do elemento <MessageWeight> especificado por meio de uma variável de fluxo for inválido (um valor não inteiro).
policies.ratelimit.QuotaViolation 500 O limite de cota foi excedido. N/A

Erros de implantação

Nome do erro Causa Correção
InvalidQuotaInterval Se o intervalo de cota especificado no elemento <Interval> não for um número inteiro, a implantação do proxy de API falhará. Por exemplo, se o intervalo de cota especificado for 0.1 no elemento <Interval>, a implantação do proxy de API falhará.
InvalidQuotaTimeUnit Se a unidade de tempo especificada no elemento <TimeUnit> não for compatível, a implantação do proxy de API falhará. As unidades de tempo compatíveis são minute, hour, day, week e month.
InvalidQuotaType Se o tipo de cota especificado pelo atributo type no elemento <Quota> for inválido, a implantação do proxy da API falhará. Os tipos de cota compatíveis são default, calendar, flexi e rollingwindow.
InvalidStartTime Se o formato do tempo especificado no elemento <StartTime> for inválido, a implantação do proxy de API falhará. O formato válido é yyyy-MM-dd HH:mm:ss, que é o formato de data e hora ISO 8601. Por exemplo, se o tempo especificado no elemento <StartTime> for 7-16-2017 12:00:00, a implantação do proxy da API falhará.
StartTimeNotSupported Se o elemento <StartTime> for especificado e tem um tipo de cota que não é calendar, a implantação do proxy da API falhará. O elemento <StartTime> é compatível apenas com o tipo de cota calendar. Por exemplo, se o atributo type estiver definido como flexi ou rolling window no elemento <Quota>, a implantação do proxy da API falhará.
InvalidTimeUnitForDistributedQuota Se o elemento <Distributed> estiver definido como true e o elemento <TimeUnit> estiver definido como second, a implantação do proxy de API falhará. A unidade de tempo second é inválida para uma cota distribuída.
InvalidSynchronizeIntervalForAsyncConfiguration Se o valor especificado para o elemento <SyncIntervalInSeconds> dentro do elemento <AsynchronousConfiguration> em uma política de cota menor que zero, a implantação do proxy da API falhará.
InvalidAsynchronizeConfigurationForSynchronousQuota Se o valor do elemento <AsynchronousConfiguration> estiver definido como true em uma política de cota, que também tem configuração assíncrona definida usando o elemento <AsynchronousConfiguration>, a implantação do proxy de API falhará.

Variáveis de falha

Essas variáveis são definidas quando esta política aciona um erro. 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 "QuotaViolation"
ratelimit.policy_name.failed policy_name é o nome especificado pelo usuário da política que causou a falha. ratelimit.QT-QuotaPolicy.failed = true

Exemplo de resposta de erro

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.QuotaViolation"
      },
      "faultstring":"Rate limit quota violation. Quota limit  exceeded. Identifier : _default"
   }
}

Exemplo de regra de falha

<FaultRules>
    <FaultRule name="Quota Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "QuotaViolation") </Condition>
        </Step>
        <Condition>ratelimit.Quota-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

Esquemas

Temas relacionados

Política ResetQuota

SpikeArrest política

Comparação de políticas de cotas, Detenção de pico e limite de taxa simultâneo