Política de cotas

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Visão geral

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 de cotas mantém contadores que contam 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.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

Observação: quando um proxy de API atinge o limite de cota, as chamadas subsequentes da API são rejeitadas. O Apigee retorna uma mensagem de erro para cada solicitação que exceder a cota. A política de cotas permite redefinir cotas imediatamente, depois que um aplicativo excede o limite.

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.000 mensagens foram contadas no primeiro dia ou no último dia desse período. nenhuma solicitação adicional é 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 ResetQuota.

Uma variação na política da cota, chamada política 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.

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 política de cotas para se proteger contra picos de tráfego gerais. Para isso, use a política SpikeArrest.

Dica: precisa de ajuda para decidir qual política de limitação de taxa usar? Consulte Como comparar as políticas de cota e detenção de pico.

Vídeos

Observação: os vídeos a seguir mostram o editor proxy clássico na interface da Apigee. A Apigee está introduzindo uma nova versão do Editor de Proxy, que tem um design diferente da versão clássica mostrada nos vídeos.

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

Introdução

Cota dinâmica

Distribuído e síncrono

Peso da mensagem

Agenda

Janela contínua

Flexi

Cota condicional

Variáveis de fluxo

Tratamento de erros

Tipos de políticas de cotas

A política de cotas é compatível com as diferentes maneiras de início e redefinição do contador de cotas. É possível definir qual usar com o atributo type no elemento <Quota>, como no exemplo a seguir:

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

Os valores válidos de type incluem:

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

Veja na tabela a seguir a redefinição das cotas de cada tipo:

Unidade de tempo	Tipo
	default (ou nulo)	calendar	flexi
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

Observação: a política da cota também é compatível com second como unidade de tempo. No entanto, second é compatível apenas com contadores não distribuídos, conforme definido por Distributed=false. Em vez de usar second, o Google recomenda usar a política SpikeArrest para limitar os picos no tráfego de solicitação no segundo nível.

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

Quando uma política de cota é executada em um fluxo de proxy de API, um contador de cotas é reduzido. Quando o contador atinge o limite, não são permitidas outras chamadas de API associadas a ele. Dependendo da configuração, a política de cotas pode empregar um ou mais contadores. É importante entender quando vários contadores são empregados e como eles se comportam.

Como as cotas são contabilizadas para produtos de API

Se o proxy de API estiver incluído em um produto de API, será possível configurar a política de cota para usar as regras de cota definidas nesse produto. Um produto de API pode especificar regras de cota no nível do produto ou no nível de operations individuais.

Um contador de cotas separado é mantido para cada operação definida em um produto de API, e as seguintes regras são observadas:

• Se uma operação tiver uma cota definida, as regras de cota da operação terão precedência sobre as regras definidas no nível do produto. Um contador de cotas separado é criado para cada operação. Qualquer chamada de API para o caminho de uma operação incrementa o contador.
• Se uma operação não tiver uma cota definida, a regra de cota no nível do produto será aplicada. No entanto, um contador de cotas separado ainda é mantido para a operação. É importante entender nesse caso que, embora a regra de cota seja retirada da definição no nível do produto, a operação ainda mantém seu próprio contador.
• Se o produto da API não incluir definições de cota (nem no nível do produto nem da operação), as regras de cota especificadas na política serão aplicadas. Nesse caso, um contador de cotas separado é mantido para cada operação no produto da API.

As seções a seguir descrevem as opções de contador e o comportamento em mais detalhes.

Como configurar contadores no nível do proxy de API

É possível configurar um produto de API para manter uma contagem de cotas no escopo do proxy da API. Nesse caso, a configuração de cota especificada no nível do produto de API é compartilhada por todas as operações que não têm a própria cota especificada. O efeito dessa configuração é criar um contador global no nível do proxy de API para este produto de API.

Para isso, use o API/apiproducts da Apigee para criar ou atualizar o produto e definir o quotaCountScope atributo aPROXY na solicitação de criação ou atualização. Com a configuração do PROXY, todas as operações definidas para o produto da API associadas ao mesmo proxy e que não têm um contador próprio compartilham o mesmo contador de cotas definido no nível do produto da API.

Na Figura 1, a Operação 1 e 2 está associada ao Proxy 1, e as Operações 4 e 5 estão associadas ao Proxy 3. Como quotaCounterScope=PROXY é definido no produto da API, cada uma dessas operações compartilha a configuração de cota no nível do produto da API. Embora essas operações compartilhem a mesma configuração de cota, elas usam contadores separados com base na associação de proxy. Por outro lado, a Operação 3 tem o próprio conjunto de configurações de cotas e, portanto, não é afetada pela sinalização quotaCounterScope.

Figura 1: uso da sinalização cotaCounterScope

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

Por padrão, se uma operação não tiver uma cota definida para ela, a regra de cota no nível do produto será aplicada. No entanto, um contador de cotas separado ainda é mantido para a operação.

Como as cotas são contadas se nenhum produto de API estiver em uso

Se não houver um produto de API associado a um proxy de API, uma política de cotas manterá um único contador, independentemente de quantas vezes você fará referência a ele 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 cota em mais de um local em um fluxo de proxy da API, o que pode fazer com que a cota acabe antes do esperado, é um antipadrão descrito em Introdução aos antipadrões.

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.

Como criar vários contadores por meio da configuração de políticas

É possível usar 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>.

Observação: os contadores de cota têm como escopo o proxy da API que contém a política de cotas. Se vários proxies de API contiverem políticas de cota com o mesmo nome, os contadores serão mantidos separadamente.

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, 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 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, 2021-02-04 24:00:00 tem a mesma data e hora que 2021-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 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 Gerenciar produtos de API.

Como configurar contadores de cotas compartilhados

Normalmente, a política de cotas conta todas as solicitações enviadas a um proxy de API. Para alguns casos de uso, pode ser útil aplicar a contagem de cotas de solicitação recebida, mas também incrementar a contagem de cotas para respostas de destino que atendam a uma condição especificada. Três elementos de política de cota quando usados juntos, <SharedName>, <CountOnly> e <EnforceOnly>, permitem personalizar a política de cotas para aplicar a cota de solicitação recebida e contar as respostas de destino com base em uma condição especificada.

Por exemplo, suponha que você queira incrementar o contador de cotas de um proxy de API em que as respostas do destino de back-end têm um código de status HTTP 200. Para atingir essa contagem especializada, faça o seguinte:

• Adicione uma política de cotas ao fluxo de solicitação ProxyEndpoint com o elemento <SharedName> definido com um valor de nome e o elemento <EnforceOnly> definido como true.
• Adicione outra política de cota ao fluxo de resposta ProxyEndpoint com o elemento <SharedName> definido com o mesmo valor de nome da primeira política e o elemento <CountOnly> definido como true.
• Coloque a segunda política de cotas (a que tem <CountOnly>) em uma etapa condicional que defina a condição para incrementar o contador de cotas.

Para ver um exemplo de como usar contadores compartilhados, consulte Contadores compartilhados na seção Amostras.

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 é o plano de serviço. A cota dinâmica verifica o plano de serviços dos aplicativos 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.

Outra opção é definir atributos personalizados em desenvolvedores ou apps individuais e ler esses valores na política de cotas. Por exemplo, para definir valores de cotas diferentes por desenvolvedor. você define atributos personalizados no desenvolvedor que contêm 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 ou parâmetro de formulário, entre outros

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>2021-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, a Apigee emitirá um erro.

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

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 <Quota>, 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 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 compartilhados

O exemplo a seguir ilustra como configurar um contador compartilhado para um proxy de API, em que o contador de cotas também é incrementado quando a resposta de destino é o status HTTP 200. Como as duas políticas de cotas usam o mesmo valor <SharedName>, ambas compartilharão o mesmo contador. Para mais informações, consulte Como configurar contadores de cota compartilhados.

Exemplo de configuração ProxyEndpoint:

<ProxyEndpoint name="default">
    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Name>Enforce-Only</Name>  <!--First quota policy enforces quota count -->
            </Step>
        </Request>
        <Response>
            <Step>
                <Name>Count-Only</Name>   <!-- Second quota policy counts quota if call is successful -->
                <Condition>response.status.code = 200</Condition>
            </Step>
        </Response>
        <Response/>
    </PreFlow>
    <Flows/>
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <HTTPProxyConnection>
        <BasePath>/quota-shared-name</BasePath>
    </HTTPProxyConnection>
    <RouteRule name="noroute"/>
</ProxyEndpoint>

Exemplo da primeira política de cotas:

<Quota continueOnError="false" enabled="true" name="Enforce-Only" type="rollingwindow">
    <DisplayName>Enforce-Only</DisplayName>
    <Properties/>
    <Allow count="5"/>
    <Interval>2</Interval>
    <TimeUnit>minute</TimeUnit>
    <Distributed>true</Distributed>
    <Synchronous>true</Synchronous>
    <EnforceOnly>true</EnforceOnly>
    <SharedName>common-proxy</SharedName>  <!-- Notice that SharedName value is the same for both Quota policies -->
</Quota>

Exemplo da segunda política de cotas:

<Quota continueOnError="false" enabled="true" name="Count-Only" type="rollingwindow">
    <DisplayName>Count-Only</DisplayName>
    <Properties/>
    <Allow count="5"/>
    <Interval>2</Interval>
    <TimeUnit>minute</TimeUnit>
    <Distributed>true</Distributed>
    <Synchronous>true</Synchronous>
    <CountOnly>true</CountOnly>
    <SharedName>common-proxy</SharedName>  <!-- Same name as the first policy -->
</Quota>

Observação: não é possível usar os elementos <Class> e <Identifier> na mesma política de cota.

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 2021-07-08 07:00:00, ele será redefinido para 0 às 2021-07-08 08:00:00 (1 hora a partir do horário de início). Se a primeira mensagem for recebida em 2021-07-08 07:35:28 e a contagem de mensagens alcançar 10.000 antes de 2021-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>2021-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.

Observação: não é possível usar os elementos <Class> e <Identifier> na mesma política de cota.

---

Elemento <Quota>

Veja a seguir os atributos e elementos filho de <Quota>. 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.my-verify-key-policy.apiproduct.* abaixo estão disponíveis por padrão quando uma política VerifyAPIKey chamada my-verify-key-policy é 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 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 atributos a seguir são específicos dessa política:

Atributo	Descrição	Padrão	Presence
Tipo	Define o Tipo de política de cota, que determina quando e como o contador de cotas verifica o uso da cota, além de como ela é redefinida. Se você não definir type, o contador começará no início do minuto, da hora, do dia, da semana ou do mês. Valores válidos: calendar rollingwindow flexi Para ver uma descrição completa de cada tipo, consulte Tipos de políticas de cota.	N/A	Opcional

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

Atributo	Descrição	Padrão	Presence
name	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.	N/A	Obrigatório
continueOnError	Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas. Defina como true para que a execução do fluxo continue mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual	false	Opcional
enabled	Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo se ela permanecer anexada a um fluxo.	true	Opcional
async	Esse atributo está obsoleto.	false	Descontinuado

Elemento <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

Padrão	N/A Se você omitir esse elemento, será usado o valor do atributo name da política.
Presence	Opcional
Tipo	String

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

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

Valor padrão	n/a
Obrigatório?	Opcional
Tipo	Tipo inteiro ou complexo
Elemento pai	<Quota>
Elemento filho	<Class>

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.

Também é possível especificar um elemento <Class> como filho de <Allow> para determinar a contagem permitida da política com base em uma variável de fluxo. A Apigee combina o valor da variável de fluxo com o elemento 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>

A tabela a seguir lista os atributos de <Allow>:

Atributo	Descrição	Padrão	Presence
count	Use para especificar um número de mensagens para a cota. Por exemplo, um valor de atributo count de 100, Interval de 1 e TimeUnit do mês especifica uma cota de 100 mensagens por mês.	2000	Opcional
countRef	Use para especificar uma variável de fluxo que contenha a contagem de mensagens para uma cota. countRef tem precedência sobre o atributo count.	nenhum	Opcional

<Class>

Permite que você condicione 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.

Valor padrão	n/a
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	<Allow>
Elemento filho	<Allow> (Filho de <Class>)

Para usar o elemento <Class>, especifique uma variável de fluxo usando o atributo ref para a elemento <Class>. Em seguida, a Apigee usa o valor da variável de fluxo para selecionar um dos elementos filhos <Allow> e determinar a contagem permitida da política. A Apigee combina o valor da variável de fluxo com o elemento 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.

Observação: não é possível usar os elementos <Class> e <Identifier> na mesma política de cota.

A tabela a seguir lista os atributos de <Class>:

Atributo	Descrição	Padrão	Presence
ref	Use para especificar uma variável de fluxo contendo a classe de cota para uma cota.	nenhum	Obrigatório

<Allow> (filho de <Class>)

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.

Valor padrão	n/a
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	<Class>
Elemento filho	Nenhum

Por exemplo:

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

Neste exemplo, a política de cotas mantém dois contadores de cota chamados peak_time e off_peak_time. Dependendo disso, você usará o parâmetro de consulta transmitido, como mostrado no exemplo de <Class>.

A tabela a seguir lista os atributos de <Allow>:

Atributo	Descrição	Padrão	Presence
classe	Define o nome do contador de cotas.	nenhum	Obrigatório
count	Especifica o limite de cota para o contador.	nenhum	Obrigatório

<Interval>

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

Valor padrão	n/a
Obrigatório?	Obrigatório
Tipo	Número inteiro
Elemento pai	<Quota>
Elemento filho	Nenhum

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

Por exemplo, um intervalo 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>

A tabela a seguir lista os atributos de <Interval>:

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

<TimeUnit>

Especifica a unidade de tempo aplicável à cota.

Valor padrão	n/a
Obrigatório?	Obrigatório
Tipo	String
Elemento pai	<Quota>
Elemento filho	Nenhum

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

Observação: a cota também é compatível com second como unidade de tempo. No entanto, second é compatível apenas com contadores não distribuídos (quando <Distributed> está definido como false). O Google recomenda que você use a política SpikeArrest para limitar os picos no tráfego de solicitação no segundo nível em vez de usar o valor second aqui.

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

A tabela a seguir lista os atributos de <TimeUnit>:

Atributo	Descrição	Padrão	Presence
ref	Especifica uma variável de fluxo que contém 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 do intervalo será usado.	nenhum	Opcional

<StartTime>

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

Valor padrão	n/a
Obrigatório?	Opcional (obrigatório quando type estiver definido como calendar)
Tipo	String no formato de data e hora ISO 8601
Elemento pai	<Quota>
Elemento filho	Nenhum

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 nenhum valor type for definido, e a Apigee receberá um erro.

Por exemplo:

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

<Distributed>

Determina se a Apigee usa um ou mais nós para processar solicitações.

Valor padrão	false
Obrigatório?	Opcional
Tipo	Booleano
Elemento pai	<Quota>
Elemento filho	Nenhum

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

Observação: se você tem uma conta paga da Apigee, normalmente tem vários processadores de mensagens na instalação, e esse número pode variar de acordo com a carga do tráfego. As contas de avaliação normalmente têm dois processadores de mensagens.

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

<Distributed>false</Distributed>

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

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

<Synchronous>

Determina se um contador de cota distribuída precisa ser atualizado de forma síncrona.

Valor padrão	false
Obrigatório?	Opcional
Tipo	Booleano
Elemento pai	<Quota>
Elemento filho	Nenhum

Defina como true para atualizar um contador de cotas distribuídas de forma síncrona. Isso significa que as atualizações nos contadores são feitas ao mesmo tempo, 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.

Observação: ao implementar atualizações síncronas no contador, há potencial de impacto no desempenho e capacidades menores. Em alguns casos, o uso de <Synchronous>true</Synchronous> pode fazer com que a política de cotas não processe algumas transações.

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>

<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. A Apigee ignora esse elemento quando <Synchronous> está definido como true.

Valor padrão	n/a
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	<Quota>
Elemento filho	<SyncIntervalInSeconds> <SyncMessageCount>

É possível especificar o comportamento da sincronização usando os elementos filhos <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> estiver presente, a cota será sincronizada a cada N segundos, em que N é o valor especificado no elemento, independentemente do número de mensagens processadas.
• Quando apenas <SyncMessageCount> está presente, a cota sincroniza a cada M mensagens, em que M é o valor especificado no elemento ou a cada 10 segundos, o que ocorrer primeiro.
• Quando ambos os elementos estiverem presentes, a cota sincroniza a cada M mensagens ou a cada N segundos, o que ocorrer primeiro.
• Quando <AsynchronousConfiguration> não estiver presente ou nenhum elemento filho estiver presente, a cota é sincronizada a cada 10 segundos, independente do número de mensagens processadas.

<SyncIntervalInSeconds>

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

Valor padrão	10 segundos
Obrigatório?	Opcional
Tipo	Número inteiro
Elemento pai	<AsynchronousConfiguration>
Elemento filho	Nenhum

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

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

<SyncMessageCount>

Especifica o número de solicitações a serem processadas antes de sincronizar o contador de cotas.

Valor padrão	n/a
Obrigatório?	Opcional
Tipo	Número inteiro
Elemento pai	<AsynchronousConfiguration>
Elemento filho	Nenhum

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

Usando a configuração deste exemplo, em cada nó, a contagem de cota será sincronizada a cada 5 solicitações ou a cada 10 segundos, o que ocorrer primeiro.

<Identifier>

Configura a política para criar contadores exclusivos com base em uma variável de fluxo.

Valor padrão	n/a
Obrigatório?	Opcional
Tipo	String
Elemento pai	<Quota>
Elemento filho	Nenhum

Usando o elemento identificador, você pode alocar contagens de chamada a buckets diferentes definidos pelo valor em uma variável de fluxo. Por exemplo, é possível usar a variável developer.id, que é preenchida após uma política VerifyAPIKey, para aplicar um limite de cota a todas as instâncias de todos os apps criados por cada desenvolvedor específico . Você também pode usar o client_id para aplicar um limite de cota a cada app. A configuração do último é semelhante a esta:

<Identifier ref="client_id"/>

Você pode consultar uma variável personalizada que pode ser definida com aPolítica de "AssignMessage" ou aPolítica do JavaScript ou uma variável definida implicitamente, como as definidas peloPolítica VerifyAPIKey ou aVerificar política JWT de dados. Para mais informações sobre variáveis, consulte Como usar variáveis de fluxo. Para ver uma lista de variáveis conhecidas definidas pela Apigee, consulte a Referência de variáveis de fluxo.

Se você não usar esse elemento, a política alocará todas as contagens de chamadas em um único contador para a política de cotas específica.

Se você se referir a developer.id ou developer.app.id para a cota <Identifier> ou usar essas variáveis como um elemento em uma variável personalizada usada como a <Identifier>, esteja ciente de que o os valores dessas variáveis podem mudar, durante algum período de manutenção futuro. Isso seria raro, não é uma ocorrência comum. Mas se isso acontecesse e se você tivesse uma política de cotas usando uma dessas variáveis como <Identifier>, a cota não seria aplicada com restrições durante o período em que a mudança ocorreu. de dados.

Esse elemento também é discutido em Como a política de cotas do Edge funciona quando nenhum identificador é especificado?

Observação: não é possível usar os elementos <Class> e <Identifier> na mesma política de cota.

A tabela a seguir descreve os atributos de <Identifier>:

Atributo	Descrição	Padrão	Presence
ref	Especifica uma variável de fluxo que identifica o contador a usar para a solicitação. A variável pode se referir 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 algum outro valor para identificar como alocar contagens de chamadas. Geralmente, o client_id é usado como variável. O client_id também é conhecido como a chave de API ou chave do cliente e é gerado para um app quando ele é registrado em uma organização na Apigee. Você pode usar esse identificador se tiver ativado as chaves de autorização da API ou do OAuth na API.	N/A	Opcional

<MessageWeight>

Especifica o custo atribuído a cada mensagem para fins de cota. Use esse elemento para aumentar o impacto das mensagens de solicitação que, por exemplo, consomem mais recursos computacionais do que outros.

Valor padrão	n/a
Obrigatório?	Opcional
Tipo	Número inteiro
Elemento pai	<Quota>
Elemento filho	Nenhum

Por exemplo, você quer contar as mensagens POST como duas vezes mais caras do que as mensagens GET. Portanto, você define <MessageWeight> como 2 para POST e 1 para 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á 5 solicitações POST em qualquer intervalo de 10 minutos. Qualquer solicitação adicional, POST ou GET, antes da rejeição do contador.

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

<UseQuotaConfigInAPIProduct>

Define configurações de cota para um produto da API, como unidades de tempo, intervalo e máximo permitido.

Valor padrão	n/a
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	<Quota>
Elemento filho	<DefaultConfig>

Se você adicionar o elemento <UseQuotaConfigInAPIProduct> à política de cota, a Apigee ignorará os elementos filhos <Allow>, <Interval> e <TimeUnit> de <Quota>.

O elemento <UseQuotaConfigInAPIProduct> é simplesmente um contêiner das configurações padrão definidas usando o elemento <DefaultConfig>, como no exemplo a seguir:

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

É possível usar o atributo stepName para referenciar uma política VerifyAPIKey ou uma operação ValidateToken da política OAuthv2 no fluxo.

A tabela a seguir descreve os atributos de <UseQuotaConfigInAPIProduct>:

Atributo	Descrição	Padrão	Presence
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ório

Para ver mais informações, consulte os seguintes tópicos:

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

<DefaultConfig>

Contém valores padrão para a cota de um produto da API. Quando você define um <DefaultConfig>, os três elementos filhos são obrigatórios.

Valor padrão	n/a
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	<UseQuotaConfigInAPIProduct>
Elemento filho	<Allow> <Interval> <TimeUnit>

É possível definir esses valores na operação do produto da API, seja com a IU ou com a API de produtos de API e na política de cotas. No entanto, se as configurações no produto da API tiverem precedência e as configurações na Política de cotas forem ignoradas.

A sintaxe para esse 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 a seguir especifica uma cota de 10.000 todas as semanas:

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

Para ver mais informações, consulte os seguintes tópicos:

• O que é um produto de API?
• Como gerenciar produtos de API

<SharedName>

Identifica esta política de cotas como compartilhada. Todas as políticas de cota em um proxy de API com o mesmo valor <SharedName> compartilham o mesmo contador de cotas subjacente. Se esse elemento estiver presente, os elementos <EnforceOnly> ou <CountOnly> também precisarão estar presentes.

Para mais informações e exemplos, consulte Como configurar contadores de cotas compartilhados.

Valor padrão	n/a
Obrigatório?	Opcional
Tipo	String
Elemento pai	<Quota>
Elemento filho	Nenhum

<CountOnly>

Coloque uma política de cotas com esse elemento definido como true em uma etapa condicional no fluxo de resposta ProxyEndpoint para incrementar condicionalmente o contador de cotas subjacente. Se esse elemento estiver presente, os elementos <SharedName> e <EnforceOnly> também precisarão estar presentes.

Para mais informações e exemplos, consulte Como configurar contadores de cotas compartilhados.

Valor padrão	false
Obrigatório?	Opcional
Tipo	Booleano
Elemento pai	<Quota>
Elemento filho	Nenhum

<EnforceOnly>

Coloque uma política de cotas com esse elemento definido como true no fluxo de solicitação de um proxy de API. Essa configuração permite que as contagens de cota sejam compartilhadas para qualquer política de cotas no proxy de API com o mesmo valor <SharedName>. Se esse elemento estiver presente, os elementos <SharedName> e <CountOnly> também precisarão estar presentes.

Para mais informações e exemplos, consulte Como configurar contadores de cotas compartilhados.

Valor padrão	false
Obrigatório?	Opcional
Tipo	Booleano
Elemento pai	<Quota>
Elemento filho	Nenhum

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, consulte a Referência de variáveis de fluxo.

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 quando o novo intervalo de cota é iniciado. Quando o tipo de política de cotas é rollingwindow, esse valor não é válido porque o intervalo de cota nunca expira.
ratelimit.{policy_name}.identifier	String	Somente leitura	Retorna a referência do identificador (cliente) anexada à política
ratelimit.{policy_name}.class	String	Somente leitura	Retorna a classe associada ao identificador do cliente
ratelimit.{policy_name}.class.allowed.count	Longo	Somente leitura	Retorna a contagem de cotas permitidas definida na classe
ratelimit.{policy_name}.class.used.count	Longo	Somente leitura	Retorna a cota usada dentro de uma classe
ratelimit.{policy_name}.class.available.count	Longo	Somente leitura	Retorna a contagem de cotas disponíveis na classe
ratelimit.{policy_name}.class.exceed.count	Longo	Somente leitura	Retorna a contagem de solicitações que excede o limite da classe no intervalo de cota atual.
ratelimit.{policy_name}.class.total.exceed.count	Longo	Somente leitura	Retorna a contagem total de solicitações que excedem o limite na classe em todos os intervalos de cota. Portanto, é a soma de class.exceed.count para todos os intervalos de cota.
ratelimit.{policy_name}.failed	Booleano	Somente leitura	Indica se a política falhou (verdadeiro ou falso).

Referência de erros

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>

Observação: atualmente, a política de cotas retorna um código de status de 500 quando impõe um limite de taxa. Se você usa o serviço gerenciado pela Apigee e quer que sua Política de cotas retorne 429, entre em contato com o Cloud Customer Care. para ativar a propriedade features.isHTTPStatusTooManyRequestEnabled. Consulte Http 429 como código de status padrão para violação da política de cotas para mais detalhes.

Observação: ao atualizar as propriedades, você precisa transmitir todas as propriedades existentes à API, mesmo que elas não estejam sendo alteradas. Se você omitir propriedades no payload, as propriedades serão removidas.

curl -u email:password -X POST -H "Content-type:application/xml" \
  http://LOAD_BALANCER_IP:8080/v1/o/myorg \
  -d '<Organization type="trial" name="MyOrganization">
    <DisplayName>MyOrganization</DisplayName>
    <Environments/>
    <Properties>
        <Property name="features.isHTTPStatusTooManyRequestEnabled">true</Property>
    </Properties>
  </Organization>'

Esquemas

Amostra: veja nossas amostras de repositório do GitHub para os esquemas mais recentes.

Temas relacionados

Política ResetQuota

Política de Detenção de pico

Comparação de políticas de cota e detenção de pico