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 Valores válidos:
|
Agenda | Opcional |
The following table describes attributes that are common to all policy parent elements:
Attribute | Description | Default | Presence |
---|---|---|---|
name |
The internal name of the policy. The value of the Optionally, use the |
N/A | Required |
continueOnError |
Set to Set to |
false | Optional |
enabled |
Set to Set to |
true | Optional |
async |
This attribute is deprecated. |
false | Deprecated |
<DisplayName> element
Use in addition to the name
attribute to label the policy in the
management UI proxy editor with a different, natural-language name.
<DisplayName>Policy Display Name</DisplayName>
Default |
N/A If you omit this element, the value of the policy's |
---|---|
Presence | Optional |
Type | 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 |
2000 | Opcional |
countRef |
Use para especificar uma variável de fluxo que contenha a contagem de mensagens para uma cota.
|
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. |
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 |
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.
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 Em algumas circunstâncias, as configurações de cota precisam ser recuperadas onde nenhuma
|
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 é |
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> . |
build |
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. |
build |
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). |
build |
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á.
|
build |
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 .
|
build |
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 .
|
build |
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á.
|
build |
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á.
|
build |
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. |
build |
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á. |
build |
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á. |
build |
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
Comparação de políticas de cotas, Detenção de pico e limite de taxa simultâneo