Política de quotas

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Vista geral

Uma quota é uma atribuição de pedidos que um proxy de API aceita durante um período, como um minuto, uma hora, um dia, uma semana ou um mês. A política de quotas mantém contadores que registam o número de pedidos recebidos pelo proxy da API. Esta capacidade permite que os fornecedores de APIs apliquem limites ao número de chamadas de API feitas pelas apps durante um intervalo de tempo. Através das políticas de quotas, pode, por exemplo, limitar as apps a 1 pedido por minuto ou a 10 000 pedidos por mês.

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

Quando um proxy de API atinge o limite de quota, o Apigee rejeita as chamadas de API subsequentes e devolve uma mensagem de erro até que o contador de quotas seja reposto automaticamente no final do intervalo de tempo especificado ou até que a quota seja reposta explicitamente através da política ResetQuota.

Por exemplo, se uma quota for definida como 10 000 mensagens por mês, a limitação de taxa começa após a 10 000.ª mensagem. Não importa se foram contabilizadas 10 000 mensagens no primeiro dia ou no último dia desse mês.

Com o Apigee, cada chamada API pode ser ponderada dinamicamente. Por exemplo, com uma API de modelo de linguagem grande (GML), pode aplicar um limite de taxa com base no número de tokens no pedido ou na resposta, ou em ambos. Além disso, os próprios limites de quota podem ser dinâmicos, o que significa que pode aplicar quotas mais rigorosas quando o sistema está mais ocupado ou flexibilizar as quotas durante as horas fora de pico.

Uma variação da política de quotas, a política SpikeArrest, impede picos (ou rajadas) de tráfego que podem ser causados por um aumento repentino na utilização, clientes com erros ou ataques maliciosos.

Pode definir a mesma quota para todas as apps que acedem ao proxy da API ou pode definir limites de quota diferentes, consoante:

• O produto que contém o proxy de API
• A app que pede a API
• O programador de apps
• O serviço a montante
• Muitos outros critérios
• Combinações de qualquer um dos critérios disponíveis

Não use a política de quotas para se proteger contra picos de tráfego gerais. Para isso, use a política SpikeArrest.

Dica: precisa de ajuda para decidir que política de limitação de taxa usar? Consulte a secção Comparar as políticas de Quota e SpikeArrest.

Vídeos

Nota: os vídeos seguintes mostram o editor de proxy clássico na IU do Apigee. A Apigee está a introduzir uma nova versão do Proxy Editor, que tem um design diferente da versão clássica apresentada nos vídeos.

Estes vídeos apresentam a gestão de quotas com a política de quotas:

Introdução

Quota dinâmica

Distribuído e síncrono

Peso da mensagem

Calendário

Janela contínua

Flexi

Quota condicional

Variáveis do fluxo

Processamento de erros

Tipos de políticas de quotas

A Política de Quotas suporta várias formas diferentes de início e reposição do contador de quotas. Pode definir qual usar com o atributo type no elemento <Quota>, como mostra o exemplo seguinte:

<Quota name="QuotaPolicy" type="calendar">
  ...
</Quota>

Os valores válidos de type incluem:

• calendar: configura uma quota com base numa hora de início explícita. O contador de quota de cada app é atualizado com base nos valores de <StartTime>, <Interval> e <TimeUnit> que definir.
• rollingwindow: configura uma quota que usa uma "janela contínua" para determinar a utilização da quota. Com rollingwindow, determina a dimensão do período com os elementos <Interval> e <TimeUnit>; por exemplo, 1 dia. Quando recebe um pedido, o Apigee analisa a hora exata do pedido (por exemplo, 17:01), conta o número de pedidos recebidos entre essa hora e as 17:01 do dia anterior (1 dia) e determina se a quota foi excedida ou não durante esse período.
• flexi: configura uma quota que faz com que o contador comece quando a primeira mensagem de pedido é recebida de uma app e é reposta com base nos valores <Interval> e <TimeUnit>.

A tabela seguinte descreve quando a quota é reposta para cada tipo:

Unidade de tempo	Tipo
	default (ou nulo)	calendar	flexi
minuto	Início do minuto seguinte	Um minuto depois de <StartTime>	Um minuto após o primeiro pedido
hora	Início da próxima hora	Uma hora após <StartTime>	Uma hora após o primeiro pedido
dia	Meia-noite GMT do dia atual	24 horas após <StartTime>	24 horas após o primeiro pedido
semana	Domingo à meia-noite GMT no final da semana	Uma semana após <StartTime>	Uma semana após o primeiro pedido
mês	Meia-noite GMT do último dia do mês	Um mês (28 dias) após <StartTime>	Um mês (28 dias) após o primeiro pedido

Nota: se precisar de limitar o pico no tráfego de pedidos através de um intervalo de tempo medido em segundos, recomendamos que use a política SpikeArrest em vez da política de quota.

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

A tabela não descreve quando a contagem é reposta para o tipo rollingwindow. Isto deve-se ao facto de as quotas de período contínuo funcionarem de forma ligeiramente diferente, com base num período de análise, como uma hora ou um dia. Para o tipo rollingwindow, o contador nunca é reposto, mas é recalculado em cada pedido. Quando chega um novo pedido, a política determina se a quota foi excedida no período anterior.

Por exemplo, define um período de duas horas que permite 1000 pedidos. Um novo pedido é recebido às 16:45.A política calcula a contagem de quotas para o período de duas horas anterior, o que significa o número de pedidos desde as 14:45. Se o limite de quota não tiver sido excedido nesse período de duas horas, o pedido é permitido.

Um minuto depois, às 16:46, chega outro pedido. Agora, a política calcula a contagem de quotas desde as 14:46 para determinar se o limite foi excedido.

Compreender os contadores de quotas

Quando uma política de quotas é executada num fluxo de proxy de API, um contador de quotas é decrementado. Quando o contador atinge o limite, não são permitidas mais chamadas API associadas a esse contador. Consoante a sua configuração, a política de quotas pode usar um ou mais contadores. É importante compreender quando são usados vários contadores e como se comportam.

Como são contabilizadas as quotas para produtos de API

Se o seu proxy de API estiver incluído num produto de API, pode configurar a política de quotas para usar as regras de quotas definidas nesse produto. Um produto API pode especificar regras de quota ao nível do produto ou ao nível de operações individuais.

É mantido um contador de quota separado para cada operação definida num produto da API, e são observadas as seguintes regras:

• Se uma operação tiver uma quota definida, as regras de quota da operação têm precedência sobre as regras de quota definidas ao nível do produto. É criado um contador de quota separado para cada operação. Todas as chamadas API para o caminho de uma operação incrementam o respetivo contador.
• Se uma operação não tiver uma quota definida, é aplicada a regra de quota ao nível do produto. No entanto, é mantido um contador de quotas separado para a operação. É importante compreender neste caso que, embora a regra de quota seja retirada da definição ao nível do produto, a operação continua a manter o seu próprio contador.
• Se o produto da API não incluir definições de quotas, nem ao nível do produto nem da operação, aplicam-se as regras de quotas especificadas na política. No entanto, também neste caso, é mantido um contador de quotas separado para cada operação no produto da API.

As secções seguintes descrevem as opções e o comportamento dos contadores mais detalhadamente.

Configurar contadores ao nível do proxy da API

É possível configurar um produto de API para manter uma contagem de quotas ao nível do proxy de API. Neste caso, a configuração de quota especificada ao nível do produto da API é partilhada por todas as operações que não têm a sua própria quota especificada. O efeito desta configuração é criar um contador global ao nível do proxy da API para este produto de API.

Para alcançar esta configuração, tem de usar a API Apigee/apiproducts para criar ou atualizar o produto e definir o atributo quotaCountScope como PROXY no pedido de criação ou atualização. Com a configuração PROXY, todas as operações definidas para o produto de API que estão associadas ao mesmo proxy e não têm o seu próprio contador, partilham o mesmo contador de quotas definido ao nível do produto de API.

Na Figura 1, as operações 1 e 2 estão associadas ao Proxy1, e as operações 4 e 5 estão associadas ao Proxy3. Uma vez que quotaCounterScope=PROXY está definido no produto API, cada uma destas operações partilha a definição de quota ao nível do produto API. Tenha em atenção que, embora estas operações partilhem a mesma configuração de quota, usam contadores separados com base na respetiva associação de proxy. Por outro lado, a operação 3 tem a sua própria configuração de quota definida e, por isso, não é afetada pela flag quotaCounterScope.

Figura 1: utilização da flag quotaCounterScope

Se quotaCounterScope=PROXY, recomendamos que não configure operações em que alguns recursos de proxy tenham uma configuração de quota definida e outros não. Por exemplo, na Figura 1, se a Operação 4 tiver a sua própria configuração de quota e a Operação 5 não tiver, essa configuração é considerada um antipadrão.

Por predefinição, se uma operação não tiver uma quota definida, é aplicada a regra de quota ao nível do produto. No entanto, é mantido um contador de quotas separado para a operação.

Como são contabilizadas as quotas se não estiverem a ser usados produtos da API

Se não existir nenhum produto API associado a um proxy API, uma política de quotas mantém um único contador, independentemente do número de vezes que o referencia num proxy API. O nome do contador de quota baseia-se no atributo name da política.

Por exemplo, cria uma política de quotas denominada MyQuotaPolicy com um limite de 5 pedidos e coloca-a em vários fluxos (fluxo A, B e C) no proxy da API. Embora seja usada em vários fluxos, mantém um único contador que é atualizado por todas as instâncias da política:

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

O pedido seguinte a qualquer um dos três fluxos é rejeitado porque o contador de quotas atingiu o limite.

A utilização da mesma política de quotas em mais do que um local num fluxo de proxy de API, o que pode provocar involuntariamente o esgotamento das quotas mais rapidamente do que o esperado, é um padrão de solução descrito na Introdução aos padrões de solução.

Em alternativa, pode definir várias políticas de quotas no seu proxy de API e usar uma política diferente em cada fluxo. Cada política de quotas mantém o seu próprio contador, com base no atributo name da política.

Criar vários contadores através da configuração de políticas

Pode usar os elementos <Class> ou <Identifier> na política de quotas para definir vários contadores únicos numa única política. Ao usar estes elementos, uma única política pode manter diferentes contadores com base na app que faz o pedido, no programador da app que faz o pedido, num ID de cliente ou noutro identificador de cliente, entre outros. Consulte os exemplos acima para mais informações sobre a utilização dos elementos <Class> ou <Identifier>.

Nota: os contadores de quota estão no âmbito do proxy da API que contém a política de quotas. Se vários proxies de API contiverem políticas de quota com o mesmo nome, os contadores são mantidos separadamente.

Notação de tempo

Todas as horas de quota estão definidas para o fuso horário do Tempo Universal Coordenado (UTC).

A notação de tempo de quota segue a notação de data padrão internacional definida na norma internacional ISO 8601.

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

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

Tenha em atenção que estão disponíveis duas notações, 00:00:00 e 24:00:00, para distinguir as duas meias-noites que podem ser associadas a uma data. Por conseguinte, 2021-02-04 24:00:00 é a mesma data e hora que 2021-02-05 00:00:00. Normalmente, a última é a notação preferida.

Obter definições de quota da configuração do produto API

Pode definir limites de quota nas configurações de produtos de API. Esses limites não aplicam automaticamente a quota. Em alternativa, pode fazer referência às definições de quota de produtos numa política de quotas. Seguem-se algumas vantagens de definir uma quota no produto para que as políticas de quotas possam fazer referência:

• As políticas de quotas podem usar uma definição uniforme em todos os proxies de API no produto de API.
• Pode fazer alterações em tempo de execução à definição de quota num produto API e as políticas de quota que referenciam o valor têm automaticamente valores de quota atualizados.

Para mais informações sobre a utilização das definições de quota de um produto de API, consulte o exemplo "Quota dinâmica" acima.

Para informações sobre a configuração de produtos API com limites de quota, consulte o artigo Gerir produtos API.

Configurar contadores de quotas partilhados

No caso simples, a política de quotas incrementa o respetivo contador uma vez para cada pedido enviado para um proxy de API, durante o processamento inicial do pedido. Em alguns casos, pode querer verificar se a quota foi excedida no processamento inicial do pedido recebido, mas incrementar o contador apenas durante o processamento da resposta. Isto faz sentido quando o custo ou o peso da chamada API só pode ser conhecido depois de o sistema a montante ou de destino responder. No caso de uma API de GML, o tamanho da resposta em tokens pode determinar o custo. No caso de uma API BigQuery, o total_slot_ms na resposta pode determinar o custo.

Três elementos da política de quotas: <SharedName>, <CountOnly> e <EnforceOnly>, quando usados em conjunto, permitem-lhe personalizar a política de quotas para aplicar a quota ao pedido recebido e acumular contagens em função da quota com base nas informações derivadas das respostas de destino.

Por exemplo, suponha que tem um proxy de API que usa um MDG como destino e quer aplicar uma quota de 100 000 tokens por hora. As respostas do MDG fornecem um valor totalTokenCount. Para o fazer, siga estes passos:

• Anexe uma política de quota ao fluxo de pedidos do ProxyEndpoint com o elemento <SharedName> definido com um valor de nome e o elemento <EnforceOnly> definido como true.
• Ao fluxo de resposta ProxyEndpoint, anexe uma política ExtractVariables para extrair o valor totalTokenCount da resposta recebida do alvo do MDG.
• Anexe uma segunda política de quota ao fluxo de resposta do ProxyEndpoint com o elemento <SharedName> definido para o mesmo valor de nome que o da primeira política de quota e o elemento <CountOnly> definido como true. Defina o elemento <MessageWeight> para usar o valor totalTokenCount extraído.

Para ver um exemplo que mostra como usar contadores partilhados, consulte Contadores partilhados na secção Exemplos.

Amostras

Estes exemplos de código de políticas ilustram como iniciar e terminar períodos de quota:

Quota mais 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 quotas dinâmicas permitem-lhe configurar uma única política de quotas que aplica diferentes definições de quotas com base nas informações transmitidas à política de quotas. Outro termo para as definições de quota neste contexto é plano de serviço. A quota dinâmica verifica o plano de serviço das apps e, em seguida, aplica essas definições.

Nota: se especificar um valor e uma referência para um elemento, a referência tem prioridade. Se a referência não for resolvida no tempo de execução, é usado o valor.

Por exemplo, quando cria um produto API, pode definir opcionalmente o limite de quota permitido, a unidade de tempo e o intervalo. No entanto, a definição destes valores no produto API não impõe a respetiva utilização num proxy de API. Também tem de adicionar uma política de quotas ao proxy de API que lê estes valores. Consulte o artigo Crie produtos da API para mais informações.

No exemplo acima, o proxy de API que contém a política de quota usa uma política VerifyAPIKey, denominada verify-api-key, para validar a chave de API transmitida num pedido. A política de quotas acede então às variáveis de fluxo da política VerifyAPIKey para ler os valores de quota definidos no produto de API.

Outra opção é definir atributos personalizados em programadores ou apps individuais e, em seguida, ler esses valores na política de quotas. Por exemplo, para definir valores de quota diferentes por programador, define atributos personalizados no programador que contenham o limite, a unidade de tempo e o intervalo. Em seguida, faz referência a estes valores na política de quotas, 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 programador.

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

• Variáveis de fluxo
• Propriedades no produto da API, na app ou no programador
• Um mapa de chaves-valores (KVM)
• Um cabeçalho, um parâmetro de consulta, um parâmetro de formulário e outros

Para cada proxy de API, pode adicionar uma política de quotas que faça referência à mesma variável que todas as outras políticas de quotas em todos os outros proxies, ou a política de quotas pode fazer referência a variáveis únicas para essa política e proxy.

Hora de início

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

Para uma quota com type definido como calendar, tem de definir um valor <StartTime> explícito. O valor de tempo é a hora GMT e não a hora local. Se não fornecer um valor <StartTime> para uma política do tipo calendar, o Apigee emite um erro.

O contador de quota de cada app é atualizado com base nos valores <StartTime>, <Interval> e <TimeUnit>. Para este exemplo, a quota começa a ser contabilizada às 10:30 GMT a 18 de fevereiro de 2021 e é atualizada a cada 5 horas. Por isso, a próxima atualização é às 15:30 GMT a 18 de fevereiro de 2021.

Contador de acesso

<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 quota. Pode aceder a estas variáveis de fluxo no proxy da API para realizar o processamento condicional, monitorizar a política à medida que se aproxima do limite de quota, devolver o contador de quotas atual a uma app ou por outros motivos.

Uma vez que o acesso às variáveis de fluxo da política se baseia no atributo name, para a política acima denominada <Quota>, acede às respetivas variáveis de fluxo no formato:

• ratelimit.QuotaPolicy.allowed.count: contagem permitida.
• ratelimit.QuotaPolicy.used.count: valor atual do contador.
• ratelimit.QuotaPolicy.expiry.time: hora UTC em que o contador é reposto.

Existem muitas outras variáveis de fluxo às quais pode aceder, conforme descrito abaixo.

Por exemplo, pode usar a seguinte política AssignMessage para devolver os valores das variáveis de fluxo de quotas como cabeçalhos de resposta:

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

Contadores partilhados

O exemplo seguinte ilustra como configurar um contador partilhado para um proxy de API, em que o contador de quota também é incrementado quando a resposta de destino é o estado HTTP 200. Uma vez que ambas as políticas de quota usam o mesmo valor de <SharedName>, ambas as políticas de quota partilham o mesmo contador de quotas. Para mais informações, consulte o artigo Configurar contadores de quotas partilhados.

Exemplo de configuração de ProxyEndpoint:

<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>Quota-Enforce-Only</Name>
      </Step>
    </Request>
    <Response>
      <Step>
        <Name>EV-Token-Count</Name>
      </Step>
      <Step>
        <Name>Quota-Count-Only</Name>
      </Step>
    </Response>
    <Response/>
  </PreFlow>
  <Flows/>
  <PostFlow name="PostFlow">
    <Request/>
    <Response/>
  </PostFlow>
  <HTTPProxyConnection>
    <BasePath>/quota-shared-name</BasePath>
  </HTTPProxyConnection>
  <RouteRule name="noroute"/>
</ProxyEndpoint>

Primeiro exemplo de política de quotas:

<Quota name="Quota-Enforce-Only" type="rollingwindow">
  <SharedName>common-counter</SharedName>
  <EnforceOnly>true</EnforceOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
</Quota>

Exemplo da política ExtractVariable:

<ExtractVariables name='EV-Token-Count'>
  <Source>response</Source>
  <VariablePrefix>extracted</VariablePrefix>
  <JSONPayload>
    <Variable name='tokenCount'>
      <JSONPath>$[1].usageMetadata.totalTokenCount</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

Segundo exemplo de política de quotas:

<Quota name="Quota-Count-Only" type="rollingwindow">
  <SharedName>common-counter</SharedName>  <!-- Same name as the first Quota policy -->
  <CountOnly>true</CountOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
  <MessageWeight ref="extracted.tokenCount"/>
</Quota>

Primeiro pedido

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

Use este exemplo de código para aplicar uma quota de 10 000 chamadas por hora. A política repõe o contador de quotas no início de cada hora. Se o contador atingir a quota de 10 000 chamadas antes do final da hora, as chamadas que excedam as 10 000 são rejeitadas.

Por exemplo, se o contador começar em 2021-07-08 07:00:00, é reposto para 0 às 2021-07-08 08:00:00 (1 hora após a hora de início). Se a primeira mensagem for recebida a 2021-07-08 07:35:28 e o número de mensagens atingir 10 000 antes das 2021-07-08 08:00:00, as chamadas que excedam esse número são rejeitadas até que o número seja reposto no início da hora.

A hora de reposição do contador baseia-se na combinação de <Interval> e <TimeUnit>. Por exemplo, se definir <Interval> como 12 para um <TimeUnit> de horas, o contador é reposto a cada doze horas. Pode definir <TimeUnit> para minuto, hora, dia, semana ou mês.

Pode fazer referência a esta política em vários locais no seu proxy de API. Por exemplo, pode colocá-la no Proxy PreFlow para que seja executada em todos os pedidos. Em alternativa, pode colocá-lo em vários fluxos no proxy de API. Se usar esta política em vários locais no proxy, mantém um único contador que é atualizado por todas as instâncias da política.

Em alternativa, pode definir várias políticas de quota no seu proxy de API. Cada política de quotas mantém o seu próprio contador, com base no atributo name da política.

Defina o identificador

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

Por predefinição, uma política de quotas define um único contador para o proxy de API, independentemente da origem de um pedido. Em alternativa, pode usar o atributo <Identifier> com uma política de quotas para manter contadores separados com base no valor do atributo <Identifier>.

Por exemplo, use a etiqueta <Identifier> para definir contadores separados para cada ID do cliente. Num pedido ao seu proxy, a app cliente passa então um cabeçalho que contém o clientID, conforme mostrado no exemplo acima.

Pode especificar qualquer variável de fluxo para o atributo <Identifier>. Por exemplo, pode especificar que um parâmetro de consulta denominado id contém o identificador exclusivo:

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

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

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

Cada valor client_id único define agora o seu próprio contador na política de quotas.

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>

Pode definir limites de quota dinamicamente através de uma contagem de quotas baseada em classes. Neste exemplo, o limite da quota é determinado pelo valor do cabeçalho developer_segment transmitido com cada pedido. Essa variável pode ter um valor de platinum ou silver. Se o cabeçalho tiver um valor inválido, a política devolve um erro de violação de quota.

Nota: não pode usar os elementos <Class> e <Identifier> na mesma política de quotas.

---

Nota: para aceder a um tutorial com um exemplo funcional completo de um proxy que integra uma política de quotas após a política VerifyAPIKey, consulte o repositório de exemplos do Apigee.

<Quota> elemento

Seguem-se os atributos e os elementos secundários de <Quota>. Tenha em atenção que algumas combinações de elementos são mutuamente exclusivas ou não são obrigatórias. Consulte os exemplos para ver a utilização específica.

As variáveis verifyapikey.my-verify-key-policy.apiproduct.* abaixo estão disponíveis por predefinição quando uma política VerifyAPIKey denominada my-verify-key-policy é usada para verificar a chave da API da app no pedido. Os valores das variáveis provêm das definições de quota no produto da API ao qual a chave está associada, conforme descrito em Obter definições de quota a partir da configuração do produto da API.

<Quota continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="UPPER_REQUEST_LIMIT" countRef="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.limit"/>
   <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="UPPER_LIMIT_DURING_PEAK"/>
        <Allow class="off_peak_time" count="UPPER_LIMIT_DURING_OFFPEAK"/>
      </Class>
   </Allow>
   <Interval ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.interval">1</Interval>
   <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2021-7-16 12:00:00</StartTime>
   <Distributed>false</Distributed>
   <Synchronous>false</Synchronous>
   <AsynchronousConfiguration>
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
      <SyncMessageCount>5</SyncMessageCount>
   </AsynchronousConfiguration>
   <Identifier/>
   <MessageWeight/>
   <UseQuotaConfigInAPIProduct>
     <DefaultConfig>
       <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.my-verify-key-policy.apiproduct.developer.quota.interval">1</Interval>
       <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.timeunit">month</TimeUnit>
     </DefaultConfig>
   </UseQuotaConfigInAPIProduct>
   </SharedName>
   </CountOnly>
   </EnforceOnly>
</Quota>

Os seguintes atributos são específicos desta política:

Atributo	Descrição	Predefinição	Presença
escrever	Define o tipo de política de quotas, que determina quando e como o contador de quotas verifica a utilização de quotas, bem como a forma como é reposto. Se não definir type, o contador começa no início do minuto/hora/dia/semana/mês. Os valores válidos incluem: calendar rollingwindow flexi Para uma descrição completa de cada tipo, consulte os tipos de políticas de quotas.	N/A	Opcional

A tabela seguinte descreve os atributos comuns a todos os elementos principais de políticas:

Atributo	Descrição	Predefinição	Presença
name	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres. Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.	N/A	Obrigatória
continueOnError	Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar falhas no fluxo atual	falso	Opcional
enabled	Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça associada a um fluxo.	verdadeiro	Opcional
async	Este atributo foi descontinuado.	falso	Descontinuado

Elemento <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

Predefinição	N/A Se omitir este elemento, é usado o valor do atributo name da política.
Presença	Opcional
Tipo	String

<Allow>

Especifica o limite de contagem para a quota. Se o contador da política atingir este valor, as chamadas subsequentes são rejeitadas até o contador ser reposto.

Também pode conter um elemento <Class> que condicione o elemento <Allow> com base numa variável de fluxo.

Valor predefinido	N/A
Obrigatório?	Opcional
Tipo	Tipo inteiro ou complexo
Elemento principal	<Quota>
Elementos subordinados	<Class>

Abaixo, são apresentadas três formas 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 especificar count e countRef, countRef tem prioridade. Se countRef não for resolvido no tempo de execução, é usado o valor de count.

Também pode especificar um elemento <Class> como filho de <Allow> para determinar a quantidade permitida da política com base numa variável de fluxo. O Apigee faz corresponder o valor da variável de fluxo ao atributo class do elemento <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>

A tabela seguinte indica os atributos de <Allow>:

Atributo	Descrição	Predefinição	Presença
contagem	Use para especificar uma contagem de mensagens para a quota. Por exemplo, um valor do atributo count de 100, um valor do atributo Interval de 1 e um valor do atributo TimeUnit de mês especificam uma quota 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 quota. countRef tem precedência sobre o atributo count.	nenhum	Opcional

<Class>

Permite condicionar o valor do elemento <Allow> com base no valor de uma variável de fluxo. Para cada <Allow> etiqueta secundária diferente de <Class>, a política mantém um contador diferente.

Valor predefinido	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento principal	<Allow>
Elementos subordinados	<Allow> (filho de <Class>)

Para usar o elemento <Class>, especifique uma variável de fluxo através do atributo ref no elemento <Class>. Em seguida, o Apigee usa o valor da variável de fluxo <Allow> para selecionar um dos elementos secundários <Allow> para determinar a contagem permitida da política. O Apigee faz corresponder o valor da variável de fluxo ao atributo class do elemento <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 quota atual é determinado pelo valor do parâmetro de consulta time_variable transmitido com cada pedido. 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 devolve um erro de violação de quota.

Nota: não pode usar os elementos <Class> e <Identifier> na mesma política de quotas.

A tabela seguinte indica os atributos de <Class>:

Atributo	Descrição	Predefinição	Presença
ref	Use para especificar uma variável de fluxo que contenha a classe de quota para uma quota.	nenhum	Obrigatória

<Allow> (filho de <Class>)

Especifica o limite de um contador de quota definido pelo elemento <Class>. Para cada etiqueta de criança <Allow> diferente de <Class>, a política mantém um contador diferente.

Valor predefinido	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento principal	<Class>
Elementos subordinados	Nenhum

Por exemplo:

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

Neste exemplo, a política de quotas mantém dois contadores de quotas denominados peak_time e off_peak_time. A opção usada depende do parâmetro de consulta transmitido, conforme mostrado no exemplo <Class>.

A tabela seguinte indica os atributos de <Allow>:

Atributo	Descrição	Predefinição	Presença
classe	Define o nome do contador de quota.	nenhum	Obrigatória
contagem	Especifica o limite de quota para o contador.	nenhum	Obrigatória

<Interval>

Especifica o número de períodos em que as quotas são calculadas.

Valor predefinido	N/A
Obrigatório?	Obrigatória
Tipo	Número inteiro
Elemento principal	<Quota>
Elementos subordinados	Nenhum

Use para especificar um número inteiro (por exemplo, 1, 2, 5, 60, etc.) que vai ser associado ao elemento <TimeUnit> que especificar (minuto, hora, dia, semana ou mês) para determinar um período durante o qual o Apigee calcula a utilização da quota.

Por exemplo, um intervalo de 24 com um <TimeUnit> de hour significa que a quota vai ser calculada ao longo de 24 horas.

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>

A tabela seguinte indica os atributos de <Interval>:

Atributo	Descrição	Predefinição	Presença
ref	Use para especificar uma variável de fluxo que contenha o intervalo para uma quota. ref tem precedência sobre um valor de intervalo explícito. Se forem especificados a referência e o valor, a referência tem prioridade. Se ref não for resolvido no momento da execução, é usado o valor.	nenhum	Opcional

<TimeUnit>

Especifica a unidade de tempo aplicável à quota.

Valor predefinido	N/A
Obrigatório?	Obrigatória
Tipo	String
Elemento principal	<Quota>
Elementos subordinados	Nenhum

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

Nota: a política de quotas também suporta second como unidade de tempo. No entanto, second só é suportado para contadores não distribuídos (quando <Distributed> está definido como false). A Google recomenda que use a política SpikeArrest para limitar os picos no tráfego de pedidos ao nível do segundo, em vez de usar o valor second aqui.

Por exemplo, um Interval de 24 com um TimeUnit de hour significa que a quota vai ser calculada ao longo de 24 horas.

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>

Predefinição:	nenhum
Presença:	Obrigatória
Tipo:	String

A tabela seguinte indica os atributos de <TimeUnit>:

Atributo	Descrição	Predefinição	Presença
ref	Especifica uma variável de fluxo que contém a unidade de tempo para uma quota. ref tem precedência sobre um valor de intervalo explícito. Se ref não for resolvido no momento da execução, é usado o valor do intervalo.	nenhum	Opcional

<StartTime>

Quando type está definido como calendar, especifica a data e a hora em que o contador de quota começa a contar, independentemente de terem sido recebidos pedidos de quaisquer apps.

Valor predefinido	N/A
Obrigatório?	Opcional (obrigatório quando type está definido como calendar)
Tipo	String no formato de data e hora ISO 8601
Elemento principal	<Quota>
Elementos subordinados	Nenhum

Importante: se omitir o elemento <StartTime> da configuração da política de quotas, o período de quotas começa no primeiro dia do mês atual, por predefinição.

Por exemplo:

<StartTime>2021-7-16 12:00:00</StartTime>

<Distributed>

Determina se o Apigee usa um ou mais nós para processar pedidos.

Valor predefinido	falso
Obrigatório?	Opcional
Tipo	Booleano
Elemento principal	<Quota>
Elementos subordinados	Nenhum

Defina como true para especificar que a política deve manter um contador central e sincronizá-lo continuamente em todos os nós. Os nós podem estar em várias zonas de disponibilidade e/ou regiões.

Nota: se tiver uma conta do Apigee paga, normalmente, tem vários processadores de mensagens na sua instalação, e esse número pode variar com base na sua carga de tráfego. Normalmente, as contas de avaliação têm dois processadores de mensagens.

Se usar o valor predefinido de false, pode exceder a sua quota porque a contagem de cada nó não é partilhada:

<Distributed>false</Distributed>

Para garantir que os contadores são sincronizados e atualizados em cada pedido, defina <Distributed> e <Synchronous> como true:

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>

<Synchronous>

Determina se deve atualizar um contador de quotas distribuído de forma síncrona.

Valor predefinido	falso
Obrigatório?	Opcional
Tipo	Booleano
Elemento principal	<Quota>
Elementos subordinados	Nenhum

Defina como true para atualizar um contador de quotas distribuídas de forma síncrona. Isto significa que as atualizações dos contadores são feitas ao mesmo tempo que a quota é verificada num pedido à API. Defina como true se for essencial que não permita chamadas API acima da quota.

Nota: ao implementar atualizações síncronas no contador, existe o potencial de impactos no desempenho e taxas de transferência mais baixas. Em alguns casos, a utilização de <Synchronous>true</Synchronous> pode fazer com que a política de quotas não consiga processar algumas transações.

Definido como false para atualizar o contador de quotas de forma assíncrona. Isto significa que é possível que algumas chamadas API que excedam a quota sejam processadas, consoante o momento em que o contador de quotas no repositório central é atualizado de forma assíncrona. No entanto, não vai enfrentar os potenciais impactos no desempenho associados às atualizações síncronas.

O intervalo de atualização assíncrono predefinido é de 10 segundos. Use o elemento <AsynchronousConfiguration> para configurar este comportamento assíncrono.

<Synchronous>false</Synchronous>

<AsynchronousConfiguration>

Configura o intervalo de sincronização entre contadores de quotas distribuídos quando o elemento de configuração da política <Synchronous> não está presente ou está presente e definido como false. O Apigee ignora este elemento quando <Synchronous> está definido como true.

Valor predefinido	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento principal	<Quota>
Elementos subordinados	<SyncIntervalInSeconds> <SyncMessageCount>

Pode especificar o comportamento de sincronização através dos elementos secundários <SyncIntervalInSeconds> ou <SyncMessageCount>. Use um ou ambos os elementos. Por exemplo,

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

ou

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

• Quando apenas <SyncIntervalInSeconds> está presente, a quota é sincronizada a cada N segundos, onde N é o valor especificado no elemento, independentemente do número de mensagens processadas.
• Quando apenas <SyncMessageCount> está presente, a quota é sincronizada a cada M mensagens, em que M é o valor especificado no elemento, ou a cada 10 segundos, consoante o que ocorrer primeiro.
• Quando ambos os elementos estão presentes, a quota é sincronizada a cada M mensagens ou a cada N segundos, consoante o que ocorrer primeiro.
• Quando <AsynchronousConfiguration> não está presente ou nenhum dos elementos secundários está presente, a quota é sincronizada a cada 10 segundos, independentemente do número de mensagens processadas.

<SyncIntervalInSeconds>

Substitui o comportamento predefinido em que as atualizações assíncronas são realizadas após um intervalo de 10 segundos.

Valor predefinido	10 segundos
Obrigatório?	Opcional
Tipo	Número inteiro
Elemento principal	<AsynchronousConfiguration>
Elementos subordinados	Nenhum

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

O intervalo de sincronização tem de ser >= 10 segundos, conforme descrito nos Limites.

<SyncMessageCount>

Especifica o número de pedidos a processar antes de sincronizar o contador de quota.

Valor predefinido	N/A
Obrigatório?	Opcional
Tipo	Número inteiro
Elemento principal	<AsynchronousConfiguration>
Elementos subordinados	Nenhum

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

Usando a configuração neste exemplo, em cada nó, a contagem de quotas é sincronizada após cada 5 pedidos ou a cada 10 segundos, consoante o que ocorrer primeiro.

<Identifier>

Configura a política para criar contadores únicos com base numa variável de fluxo.

Valor predefinido	N/A
Obrigatório?	Opcional
Tipo	String
Elemento principal	<Quota>
Elementos subordinados	Nenhum

Através do elemento Identificador, pode atribuir contagens de chamadas a grupos distintos definidos pelo valor numa variável de fluxo. Por exemplo, pode usar a variável developer.id, que é preenchida após uma política VerifyAPIKey, para aplicar um limite de quota a todas as instâncias de todas as apps criadas por cada programador específico, ou pode usar a variável client_id para aplicar um limite de quota a cada app específica. A configuração para a última opção tem o seguinte aspeto:

<Identifier ref="client_id"/>

Pode referir-se a uma variável personalizada que pode definir com a política AssignMessage ou a política JavaScript, ou a uma variável definida implicitamente, como as definidas pela política VerifyAPIKey ou a política VerifyJWT. Para mais informações sobre as variáveis, consulte o artigo Usar variáveis de fluxo e, para ver uma lista de variáveis conhecidas definidas pelo Apigee, consulte a referência de variáveis de fluxo.

Se não usar este elemento, a política atribui todas as contagens de chamadas a um único contador para a política de quotas específica.

Se fizer referência a developer.id ou developer.app.id para a quota <Identifier>, ou usar essas variáveis como um elemento numa variável personalizada usada como <Identifier>, tenha em atenção que os valores destas variáveis podem mudar durante um período de manutenção futuro. Esta situação é rara e não ocorre com frequência. No entanto, se tal ocorresse e tivesse uma política de quota a usar uma dessas variáveis como o <Identifier>, a quota não seria rigorosamente aplicada durante o período em que a alteração ocorreu.

Este elemento também é abordado no artigo Como funciona a política de quotas quando não é especificado nenhum identificador?

Nota: não pode usar os elementos <Class> e <Identifier> na mesma política de quotas.

A tabela seguinte descreve os atributos de <Identifier>:

Atributo	Descrição	Predefinição	Presença
ref	Especifica uma variável de fluxo que identifica o contador a usar para o pedido. A variável pode referir-se a um cabeçalho HTTP, um parâmetro de consulta, um parâmetro de formulário ou um elemento do conteúdo da mensagem ou outro valor para identificar como atribuir contagens de chamadas. O client_id é usado frequentemente como variável. O client_id também é conhecido como chave da API ou chave de consumidor e é gerado para uma app quando esta é registada numa organização no Apigee. Pode usar este identificador se tiver ativado políticas de autorização de OAuth ou de chave da API para a sua API.	N/A	Opcional

<MessageWeight>

Especifica o custo atribuído a cada mensagem para efeitos de quota. Use este elemento para atribuir um impacto diferente aos pedidos da API com base no respetivo conteúdo ou no valor da chamada.

Valor predefinido	N/A
Obrigatório?	Opcional
Tipo	Número inteiro
Elemento principal	<Quota>
Elementos subordinados	Nenhum

Por exemplo, quando o Apigee está a gerir uma API de modelo de linguagem (conteúdo extenso), pode usar o número de tokens no pedido ou na resposta, ou ambos, como o <MessageWeight>.

Em alternativa, se quiser considerar que as mensagens POST são duas vezes mais caras do que as mensagens GET, deve definir o valor <MessageWeight> como 2 para uma mensagem POST e 1 para uma mensagem GET. Suponhamos que a quota é de 10 mensagens por minuto e que o proxy processa 5 pedidos POST nos primeiros 35 segundos. O proxy rejeita qualquer pedido adicional, POST ou GET, até que o contador seja reposto.

Tem de especificar um valor que represente <MessageWeight> através de uma variável de fluxo, e este pode ser extraído de cabeçalhos HTTP, parâmetros de consulta, uma carga útil de pedido XML ou JSON, ou qualquer outra variável de fluxo. Por exemplo, pode extrair o valor de uma carga útil de resposta para uma variável denominada extracted.message_weight e, em seguida, usá-la para <MessageWeight>:

<MessageWeight ref="extracted.message_weight"/>

Se a variável de fluxo for resolvida como 0, o pedido não afeta o contador.

<UseQuotaConfigInAPIProduct>

Define as definições de quota para um produto de API, como as unidades de tempo, o intervalo e o máximo permitido.

Valor predefinido	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento principal	<Quota>
Elementos subordinados	<DefaultConfig>

Se adicionar o elemento <UseQuotaConfigInAPIProduct> à política de quotas, o Apigee ignora todos os elementos secundários <Allow>, <Interval> e <TimeUnit> de <Quota>.

O elemento <UseQuotaConfigInAPIProduct> é simplesmente um contentor para as predefinições que define através do elemento <DefaultConfig>, como mostra o exemplo seguinte:

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>...</DefaultConfig>
</UseQuotaConfigInAPIProduct>

Pode usar o atributo stepName para fazer referência a uma política VerifyAPIKey ou a uma operação de política ValidateToken da política OAuthv2 no fluxo.

A tabela seguinte descreve os atributos de <UseQuotaConfigInAPIProduct>:

Atributo	Descrição	Predefinição	Presença
stepName	Identifica o nome da política de autenticação no fluxo. O destino pode ser uma política VerifyAPIKey ou uma política OAuthv2.	N/A	Obrigatória

Para mais informações, consulte o seguinte:

• <DefaultConfig>
• O que é um produto de API?
• Gerir produtos de API

<DefaultConfig>

Contém os valores predefinidos da quota de um produto API. Quando define um <DefaultConfig>, todos os três elementos secundários são obrigatórios.

Valor predefinido	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento principal	<UseQuotaConfigInAPIProduct>
Elementos subordinados	<Allow> <Interval> <TimeUnit>

É possível definir estes valores na operação do produto de API (através da IU ou da API Products API) e na política de quotas. No entanto, se o fizer, as definições no produto da API têm precedência e as definições na política de quotas são ignoradas.

A sintaxe deste elemento é a seguinte:

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>
    <Allow>allow_count</Allow>
    <Interval>interval</Interval>
    <TimeUnit>[minute|hour|day|week|month]</TimeUnit>
  </DefaultConfig>
</UseQuotaConfigInAPIProduct>

O exemplo seguinte especifica uma quota de 10 000 todas as semanas:

<DefaultConfig>
  <Allow>10000</Allow>
  <Interval>1</Interval>
  <TimeUnit>week</TimeUnit>
</DefaultConfig>

Para mais informações, consulte o seguinte:

• O que é um produto de API?
• Gerir produtos de API

<SharedName>

Identifica esta política de quotas como partilhada. Todas as políticas de quotas num proxy de API com o mesmo valor <SharedName> partilham o mesmo contador de quotas subjacente. Se este elemento estiver presente, o elemento <EnforceOnly> ou o elemento <CountOnly> também tem de estar presente.

Para mais informações e exemplos, consulte o artigo Configurar contadores de quota partilhados.

Valor predefinido	N/A
Obrigatório?	Opcional
Tipo	String
Elemento principal	<Quota>
Elementos subordinados	Nenhum

<CountOnly>

Coloque uma política de quota com este elemento definido como true num passo no fluxo de resposta do ProxyEndpoint para incrementar o contador de quotas subjacente sem enviar um erro de volta ao cliente quando o limite de quota for excedido. Se este elemento estiver presente, o elemento <SharedName> também tem de estar presente e o elemento <EnforceOnly> não pode estar presente.

Para mais informações e exemplos, consulte o artigo Configurar contadores de quota partilhados.

Valor predefinido	falso
Obrigatório?	Opcional
Tipo	Booleano
Elemento principal	<Quota>
Elementos subordinados	Nenhum

<EnforceOnly>

Coloque uma política de quotas com este elemento definido como true no fluxo de pedidos de um proxy de API para aplicar uma quota sem incrementar o contador de quotas. Esta configuração permite a aplicação diferida de limites de taxa com base em pesos das mensagens que só podem ser conhecidos no fluxo de resposta. Se este elemento estiver presente, o elemento <SharedName> também tem de estar presente e o elemento <CountOnly> não pode estar presente.

Para mais informações e exemplos, consulte o artigo Configurar contadores de quota partilhados.

Valor predefinido	falso
Obrigatório?	Opcional
Tipo	Booleano
Elemento principal	<Quota>
Elementos subordinados	Nenhum

Variáveis de fluxo

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

Variáveis	Tipo	Autorizações	Descrição
ratelimit.{policy_name}.allowed.count	Longo	Só de leitura	Devolve a contagem da quota permitida.
ratelimit.{policy_name}.used.count	Longo	Só de leitura	Devolve a quota atual usada num intervalo de quota.
ratelimit.{policy_name}.available.count	Longo	Só de leitura	Devolve a contagem de quota disponível no intervalo de quota.
ratelimit.{policy_name}.exceed.count	Longo	Só de leitura	Devolve 1 após a quota ser excedida.
ratelimit.{policy_name}.total.exceed.count	Longo	Só de leitura	Devolve 1 após a quota ser excedida.
ratelimit.{policy_name}.expiry.time	Longo	Só de leitura	Devolve a hora UTC (em milissegundos), que determina quando a quota expira e quando o novo intervalo de quota começa. Quando o tipo da política de quota é rollingwindow, este valor não é válido porque o intervalo de quota nunca expira.
ratelimit.{policy_name}.identifier	String	Só de leitura	Devolve a referência do identificador (cliente) anexada à política
ratelimit.{policy_name}.class	String	Só de leitura	Devolve a classe associada ao identificador do cliente
ratelimit.{policy_name}.class.allowed.count	Longo	Só de leitura	Devolve a contagem da quota permitida definida na classe
ratelimit.{policy_name}.class.used.count	Longo	Só de leitura	Devolve a quota usada numa classe
ratelimit.{policy_name}.class.available.count	Longo	Só de leitura	Devolve a contagem de quota disponível na classe
ratelimit.{policy_name}.class.exceed.count	Longo	Só de leitura	Devolve a contagem de pedidos que excede o limite na classe no intervalo de quota atual
ratelimit.{policy_name}.class.total.exceed.count	Longo	Só de leitura	Devolve a contagem total de pedidos que excede o limite na classe em todos os intervalos de quotas, pelo que é a soma de class.exceed.count para todos os intervalos de quotas.
ratelimit.{policy_name}.failed	Booleano	Só de leitura	Indica se a política falhou ou não (verdadeiro ou falso).

Referência de erro

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa 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.

Dica: precisa de ajuda para resolver um erro? Clique em na coluna "Correção" para ver informações detalhadas sobre solução de problemas.

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 Quota. 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 Quota. 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 na implantação

Dica: precisa de ajuda para resolver um erro? Clique em na coluna "Correção" para ver informações detalhadas sobre solução de problemas.

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 Quota for menor que zero, a implantação do proxy de API falhará.
InvalidAsynchronizeConfigurationForSynchronousQuota	Se o valor do elemento <AsynchronousConfiguration> estiver definido como true em uma política Quota, que também tem uma 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

Observação: para tratamento de erros, a prática recomendada é interceptar a parte errorcode da resposta de erro. Não confie no texto do faultstring, porque ele pode mudar.

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

Nota: quando a taxa de pedidos recebidos excede os limites definidos pela política de quota ou SpikeArrest, o sistema devolve um código de estado HTTP 429 Too Many Requests.

Esquemas

Exemplo: consulte os exemplos do nosso repositório do GitHub para ver os esquemas mais recentes.

Tópicos relacionados

Política ResetQuota

Política SpikeArrest

Comparar as políticas de Quota e Spike Arrest