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:

Amostras

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

<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>

<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>

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

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

<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>

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

<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>

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

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

<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>

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:

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.

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

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>

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.

Atributos

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.

Atributos

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.

Atributos

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>

Atributos

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>

Atributos

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>

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>

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>

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>

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.

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.

Elemento <Identifier>

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

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"/>

Atributos

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"/>

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.

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.

Erros de implantação

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.

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