Política de cuotas

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Icono de política

Información general

Una cuota es una asignación de solicitudes que un proxy de API aceptará durante un periodo determinado, como un minuto, una hora, un día, una semana o un mes. La política de cuotas mantiene contadores que registran el número de solicitudes recibidas por el proxy de API. Esta función permite a los proveedores de APIs aplicar límites al número de llamadas a la API que realizan las aplicaciones durante un intervalo de tiempo. Con las políticas de cuota, puedes, por ejemplo, limitar las aplicaciones a 1 solicitud por minuto o a 10.000 solicitudes al mes.

Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

Cuando un proxy de API alcanza su límite de cuota, Apigee rechaza las llamadas a la API posteriores y devuelve un mensaje de error hasta que el contador de cuota se restablece automáticamente al final del intervalo de tiempo especificado o hasta que la cuota se restablece explícitamente mediante la política ResetQuota.

Por ejemplo, si una cuota se define como 10.000 mensajes al mes, la limitación de la frecuencia comienza después del mensaje número 10.000. No importa si se han contabilizado 10.000 mensajes el primer día o el último día de ese mes.

Con Apigee, cada llamada a la API se puede ponderar de forma dinámica. Por ejemplo, con una API de modelo de lenguaje extenso (LLM), puedes aplicar un límite de frecuencia en función del número de tokens de la solicitud o de la respuesta, o de ambos. Además, los límites de las cuotas pueden ser dinámicos, lo que significa que puedes aplicar cuotas más estrictas cuando el sistema esté más ocupado o reducir las cuotas durante las horas de menor actividad.

Una variante de la política de cuota, la política SpikeArrest, evita los picos de tráfico (o ráfagas) que pueden deberse a un aumento repentino del uso, a clientes con errores o a ataques maliciosos.

Puedes definir la misma cuota para todas las aplicaciones que accedan al proxy de API o puedes definir límites de cuota diferentes en función de lo siguiente:

  • El producto que contiene el proxy de API
  • La aplicación que solicita la API
  • El desarrollador de la aplicación
  • El servicio de subida
  • Muchos otros criterios
  • Combinaciones de cualquiera de los criterios disponibles

No uses la política de cuotas para protegerte frente a picos de tráfico generales. Para ello, usa la política SpikeArrest.

Vídeos

En estos vídeos se presenta la gestión de cuotas con la política de cuotas:

Introducción

Cuota dinámica

Distribuido y síncrono

Peso del mensaje

Calendar

Ventana de tiempo

Flexi

Cuota condicional

Variables de flujo

Gestión de errores

Tipos de políticas de cuotas

La política de cuotas admite varias formas de iniciar y restablecer el contador de cuotas. Puede definir cuál usar con el atributo type en el elemento <Quota>, como se muestra en el siguiente ejemplo:

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

Los valores válidos de type son los siguientes:

  • calendar: configura una cuota basada en una hora de inicio explícita. El contador de cuota de cada aplicación se actualiza en función de los valores <StartTime>, <Interval> y <TimeUnit> que hayas definido.
  • rollingwindow: configura una cuota que usa una "ventana acumulativa" para determinar el uso de la cuota. Con rollingwindow, puedes determinar el tamaño de la ventana con los elementos <Interval> y <TimeUnit>. Por ejemplo, 1 día. Cuando llega una solicitud, Apigee analiza la hora exacta de la solicitud (por ejemplo, las 17:01), cuenta el número de solicitudes que han llegado entre ese momento y las 17:01 del día anterior (1 día) y determina si se ha superado la cuota durante ese periodo.
  • flexi: configura una cuota que hace que el contador empiece cuando se recibe el primer mensaje de solicitud de una aplicación y se restablece en función de los valores <Interval> y <TimeUnit>.

En la siguiente tabla se describe cuándo se restablece la cuota de cada tipo:

Unidad de tiempo Tipo
default (o null) calendar flexi
minuto Inicio del minuto siguiente Un minuto después de las <StartTime> Un minuto después de la primera solicitud
hora Al principio de la hora siguiente Una hora después de <StartTime> Una hora después de la primera solicitud
día Medianoche GMT del día actual 24 horas después de <StartTime> 24 horas después de la primera solicitud
semana Domingo a medianoche (GMT) al final de la semana Una semana después de <StartTime> Una semana después de la primera solicitud
mes Medianoche GMT del último día del mes Un mes (28 días) después de <StartTime> Un mes (28 días) después de la primera solicitud

En el caso de type="calendar", debe especificar el valor de <StartTime>.

En la tabla no se describe cuándo se restablece el recuento del tipo rollingwindow. Esto se debe a que las cuotas de ventana de tiempo funcionan de forma diferente, ya que se basan en una ventana retrospectiva, como una hora o un día. En el caso del tipo rollingwindow, el contador nunca se reinicia, sino que se vuelve a calcular en cada solicitud. Cuando se recibe una nueva solicitud, la política determina si se ha superado la cuota en el periodo anterior.

Por ejemplo, defines un periodo de dos horas que permite 1000 solicitudes. A las 16:45, se recibe una nueva solicitud.La política calcula el número de solicitudes de las dos horas anteriores, es decir, el número de solicitudes desde las 14:45. Si no se ha superado el límite de cuota en ese periodo de dos horas, se permitirá la solicitud.

Un minuto después, a las 16:46, llega otra solicitud. Ahora, la política calcula el número de cuotas desde las 14:46 para determinar si se ha superado el límite.

Información sobre los contadores de cuotas

Cuando se ejecuta una política de cuotas en un flujo de proxy de API, se reduce un contador de cuotas. Cuando el contador alcanza su límite, no se permiten más llamadas a la API asociadas a ese contador. En función de tu configuración, la política de cuotas puede usar uno o varios contadores. Es importante saber cuándo se usan varios contadores y cómo se comportan.

Cómo se contabilizan las cuotas de los productos de APIs

Si tu proxy de API está incluido en un producto de API, puedes configurar la política de cuota para que use las reglas de cuota definidas en ese producto. En un producto de API se pueden especificar reglas de cuota a nivel de producto o de operación.

Se mantiene un contador de cuota independiente para cada operación definida en un producto de API y se aplican las siguientes reglas:

  • Si una operación tiene una cuota definida, las reglas de cuota de la operación tienen prioridad sobre las reglas de cuota definidas a nivel de producto. Se crea un contador de cuota independiente para cada operación. Las llamadas a la API a la ruta de una operación incrementan su contador.
  • Si una operación no tiene una cuota definida, se aplica la regla de cuota a nivel de producto. Sin embargo, se mantiene un contador de cuota independiente para la operación. En este caso, es importante tener en cuenta que, aunque la regla de cuota se toma de la definición a nivel de producto, la operación sigue manteniendo su propio contador.
  • Si el producto de API no incluye ninguna definición de cuota (ni a nivel de producto ni de operación), se aplican las reglas de cuota especificadas en la política. Sin embargo, en este caso también se mantiene un contador de cuota independiente para cada operación del producto de API.

En las siguientes secciones se describen las opciones y el comportamiento de los contadores con más detalle.

Configurar contadores a nivel de proxy de API

Es posible configurar un producto de API para que mantenga un recuento de cuotas en el ámbito del proxy de API. En este caso, la configuración de cuota especificada a nivel de producto de API se comparte entre todas las operaciones que no tienen su propia cuota especificada. Esta configuración crea un contador global a nivel del proxy de API para este producto de API.

Para conseguir esta configuración, debes usar la API/apiproducts de Apigee para crear o actualizar el producto y definir el atributo quotaCountScope en PROXY en la solicitud de creación o actualización. Con la configuración de PROXY, todas las operaciones definidas para el producto de API que estén asociadas al mismo proxy y no tengan su propio contador compartirán el mismo contador de cuota definido a nivel del producto de API.

En la figura 1, las operaciones 1 y 2 están asociadas a Proxy1, y las operaciones 4 y 5 están asociadas a Proxy3. Como quotaCounterScope=PROXY se define en el producto de API, cada una de estas operaciones comparte la configuración de cuota a nivel de producto de API. Ten en cuenta que, aunque estas operaciones comparten la misma configuración de cuota, usan contadores independientes en función de su asociación de proxy. Por otro lado, la operación 3 tiene su propia configuración de cuota, por lo que no se ve afectada por la marca quotaCounterScope.

Figura 1: Uso de la marca quotaCounterScope

De forma predeterminada, si una operación no tiene una cuota definida, se aplica la regla de cuota a nivel de producto. Sin embargo, se mantiene un contador de cuota independiente para la operación.

Cómo se contabilizan las cuotas si no se usan productos de API

Si no hay ningún producto de API asociado a un proxy de API, una política de cuota mantiene un solo contador, independientemente del número de veces que se haga referencia a él en un proxy de API. El nombre del contador de cuota se basa en el atributo name de la política.

Por ejemplo, creas una política de cuota llamada MyQuotaPolicy con un límite de 5 solicitudes y la colocas en varios flujos (A, B y C) del proxy de API. Aunque se usa en varios flujos, mantiene un solo contador que actualizan todas las instancias de la política:

  • Se ejecuta el flujo A -> Se ejecuta MyQuotaPolicy y su contador = 1
  • Se ejecuta el flujo B -> Se ejecuta MyQuotaPolicy y su contador = 2
  • Se ejecuta el flujo A -> se ejecuta MyQuotaPolicy y su contador = 3
  • Se ejecuta el flujo C -> se ejecuta MyQuotaPolicy y su contador = 4
  • Se ejecuta el flujo A -> Se ejecuta MyQuotaPolicy y su contador = 5

La siguiente solicitud a cualquiera de los tres flujos se rechaza porque el contador de cuotas ha alcanzado su límite.

Usar la misma política de cuotas en más de un lugar del flujo de un proxy de API, lo que puede provocar que las cuotas se agoten más rápido de lo esperado, es un antipatrón que se describe en el artículo Introducción a los antipatrones.

También puedes definir varias políticas de cuotas en tu proxy de API y usar una política diferente en cada flujo. Cada política de cuota mantiene su propio contador, basado en el atributo name de la política.

Crear varios contadores mediante la configuración de políticas

Puedes usar los elementos <Class> o <Identifier> en la política de cuotas para definir varios contadores únicos en una sola política. Al usar estos elementos, una sola política puede mantener diferentes contadores en función de la aplicación que haga la solicitud, el desarrollador de la aplicación que haga la solicitud, un ID de cliente u otro identificador de cliente, entre otros. Consulta los ejemplos anteriores para obtener más información sobre cómo usar los elementos <Class> o <Identifier>.

Notación de tiempo

Todas las horas de las cuotas se definen en la zona horaria Tiempo universal coordinado (UTC).

La notación de tiempo de cuota sigue la notación de fecha estándar internacional definida en la norma internacional ISO 8601.

Las fechas se definen como año, mes y día, con el siguiente formato: YYYY-MM-DD. Por ejemplo, 2021-02-04 representa el 4 de febrero del 2021.

La hora del día se define como horas, minutos y segundos en el siguiente formato: hours:minutes:seconds. Por ejemplo, 23:59:59 representa la hora un segundo antes de medianoche.

Ten en cuenta que hay dos notaciones, 00:00:00 y 24:00:00, para distinguir las dos medianoches que se pueden asociar a una fecha. Por lo tanto, 2021-02-04 24:00:00 es la misma fecha y hora que 2021-02-05 00:00:00. Esta última suele ser la notación preferida.

Obtener la configuración de cuota de la configuración del producto de API

Puedes definir límites de cuota en las configuraciones de productos de API. Esos límites no aplican la cuota automáticamente. En su lugar, puedes hacer referencia a los ajustes de cuota de producto en una política de cuota. Estas son algunas de las ventajas de definir una cuota en el producto para que las políticas de cuota puedan hacer referencia a ella:

  • Las políticas de cuotas pueden usar un ajuste uniforme en todos los proxies de API del producto de API.
  • Puede hacer cambios en el tiempo de ejecución en la configuración de la cuota de un producto de API y las políticas de cuota que hagan referencia al valor tendrán automáticamente valores de cuota actualizados.

Para obtener más información sobre cómo usar los ajustes de cuota de un producto de API, consulta el ejemplo "Cuota dinámica" de arriba.

Para obtener información sobre cómo configurar productos de API con límites de cuota, consulta Gestionar productos de API.

Configurar contadores de cuota compartidos

En el caso más sencillo, la política de cuotas incrementa su contador una vez por cada solicitud enviada a un proxy de API durante el procesamiento inicial de la solicitud. En algunos casos, puede que quieras comprobar si se ha superado la cuota en la gestión inicial de la solicitud entrante, pero incrementar el contador solo durante la gestión de la respuesta. Esto tiene sentido cuando el coste o el peso de la llamada a la API solo se pueden conocer después de que responda el sistema upstream o de destino. En el caso de una API de LLM, el tamaño de la respuesta en tokens puede determinar el coste. En el caso de una API de BigQuery, el total_slot_ms de la respuesta puede determinar el coste.

Tres elementos de la política de cuotas (<SharedName>, <CountOnly> y <EnforceOnly>) que, cuando se usan juntos, te permiten personalizar la política de cuotas para aplicar la cuota a la solicitud entrante y acumular recuentos en la cuota en función de la información derivada de las respuestas de destino.

Por ejemplo, supongamos que tienes un proxy de API que usa un LLM como destino y quieres aplicar una cuota de 100.000 tokens por hora. Las respuestas del LLM proporcionan un valor totalTokenCount. Para ello, sigue estos pasos:

  • Adjunta una política de cuota al flujo de solicitudes de ProxyEndpoint con el elemento <SharedName> definido con un valor de nombre y el elemento <EnforceOnly> definido como true.
  • En el flujo de respuesta de ProxyEndpoint, adjunta una política ExtractVariables para extraer el valor totalTokenCount de la respuesta recibida del destino LLM.
  • Vincula una segunda política de cuota al flujo de respuesta de ProxyEndpoint con el elemento <SharedName> definido con el mismo valor de nombre que la primera política de cuota y el elemento <CountOnly> definido como true. Define el elemento <MessageWeight> para usar el valor totalTokenCount extraído.

Para ver un ejemplo de cómo usar contadores compartidos, consulta Contadores compartidos en la sección Ejemplos.

Ejemplos

Estos ejemplos de código de la política muestran cómo iniciar y finalizar periodos de cuota:

Más cuota 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>

Las cuotas dinámicas te permiten configurar una sola política de cuotas que aplique diferentes ajustes de cuota en función de la información que se le transfiera. Otro término para los ajustes de cuota en este contexto es plan de servicio. La cuota dinámica comprueba el plan de servicio de las aplicaciones y, a continuación, aplica esos ajustes.

Por ejemplo, cuando creas un producto de API, puedes definir de forma opcional el límite de cuota permitido, la unidad de tiempo y el intervalo. Sin embargo, si se definen estos valores en el producto de API, no se obliga a usarlos en un proxy de API. También debes añadir una política de cuota al proxy de API que lea estos valores. Consulta más información sobre cómo crear productos de API.

En el ejemplo anterior, el proxy de API que contiene la política de cuotas usa una política VerifyAPIKey, llamada verify-api-key, para validar la clave de API que se ha enviado en una solicitud. La política de cuota accede a las variables de flujo de la política VerifyAPIKey para leer los valores de cuota definidos en el producto de API.

Otra opción es definir atributos personalizados en desarrolladores o aplicaciones concretos y, a continuación, leer esos valores en la política de cuota. Por ejemplo, para definir diferentes valores de cuota por desarrollador, debe definir atributos personalizados en el desarrollador que contengan el límite, la unidad de tiempo y el intervalo. A continuación, haz referencia a estos valores en la política de cuotas, tal como se muestra a continuación:

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

En este ejemplo también se usan las variables de flujo VerifyAPIKey para hacer referencia a los atributos personalizados definidos en el desarrollador.

Puede usar cualquier variable para definir los parámetros de la política de cuota. Estas variables pueden proceder de:

  • Variables de flujo
  • Propiedades del producto de API, la aplicación o el desarrollador
  • Un mapa de clave-valor (KVM)
  • Un encabezado, un parámetro de consulta, un parámetro de formulario, etc.

En cada proxy de API, puedes añadir una política de cuotas que haga referencia a la misma variable que todas las demás políticas de cuotas de los demás proxies, o bien puedes hacer que la política de cuotas haga referencia a variables únicas de esa política y ese proxy.

Hora de inicio

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

En el caso de una cuota con el valor type definido como calendar, debes definir un valor <StartTime> explícito. El valor de la hora es la hora GMT, no la hora local. Si no proporciona un valor de <StartTime> para una política de tipo calendar, Apigee emitirá un error.

El contador de cuota de cada aplicación se actualiza en función de los valores de <StartTime>, <Interval> y <TimeUnit>. En este ejemplo, la cuota empieza a contabilizarse a las 10:30 (GMT) del 18 de febrero del 2021 y se actualiza cada 5 horas. Por lo tanto, la próxima actualización se realizará el 18 de febrero del 2021 a las 15:30 (GMT).

Contador de accesos

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

Un proxy de API tiene acceso a las variables de flujo definidas por la política de cuotas. Puedes acceder a estas variables de flujo en el proxy de API para realizar un procesamiento condicional, monitorizar la política a medida que se acerca al límite de cuota, devolver el contador de cuota actual a una aplicación o por otros motivos.

Como el acceso a las variables de flujo de la política se basa en el atributo name de las políticas, para la política anterior llamada <Quota>, puedes acceder a sus variables de flujo de la siguiente forma:

  • ratelimit.QuotaPolicy.allowed.count: recuento permitido.
  • ratelimit.QuotaPolicy.used.count: valor actual del contador.
  • ratelimit.QuotaPolicy.expiry.time: hora UTC en la que se restablece el contador.

Puedes acceder a muchas otras variables de flujo, como se describe a continuación.

Por ejemplo, puede usar la siguiente política AssignMessage para devolver los valores de las variables de flujo de cuota como encabezados de respuesta:

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

En el siguiente ejemplo se muestra cómo configurar un contador compartido para un proxy de API, donde el contador de cuota también se incrementa cuando la respuesta de destino es el estado HTTP 200. Como ambas políticas de cuotas usan el mismo valor de <SharedName>, compartirán el mismo contador de cuotas. Para obtener más información, consulta Configurar contadores de cuota compartidos.

Ejemplo de configuración 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>

Primer ejemplo de política de cuotas:

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

Ejemplo de 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 ejemplo de política de cuotas:

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

Primera solicitud

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

Usa este código de ejemplo para aplicar una cuota de 10.000 llamadas por hora. La política restablece el contador de cuota al principio de cada hora. Si el contador alcanza la cuota de 10.000 llamadas antes de que finalice la hora, las llamadas que superen las 10.000 se rechazarán.

Por ejemplo, si el contador empieza en 2021-07-08 07:00:00, se restablecerá a 0 a las 2021-07-08 08:00:00 (1 hora después de la hora de inicio). Si el primer mensaje se recibe a las 2021-07-08 07:35:28 y el recuento de mensajes llega a 10.000 antes de las 2021-07-08 08:00:00, las llamadas que superen ese recuento se rechazarán hasta que el recuento se restablezca al principio de la hora.

La hora de restablecimiento del contador se basa en la combinación de <Interval> y <TimeUnit>. Por ejemplo, si asignas el valor <Interval> a 12 para un <TimeUnit> de una hora, el contador se restablecerá cada doce horas. Puedes definir <TimeUnit> en minutos, horas, días, semanas o meses.

Puedes hacer referencia a esta política en varios lugares de tu proxy de API. Por ejemplo, puede colocarla en Proxy PreFlow para que se ejecute en cada solicitud. También puedes colocarlo en varios flujos del proxy de API. Si usa esta política en varios lugares del proxy, se mantendrá un solo contador que se actualizará con todas las instancias de la política.

También puede definir varias políticas de cuota en su proxy de API. Cada política de cuota mantiene su propio contador, basado en el atributo name de la 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>

De forma predeterminada, una política de cuotas define un único contador para el proxy de API, independientemente del origen de una solicitud. También puede usar el atributo <Identifier> con una política de cuotas para mantener contadores independientes en función del valor del atributo <Identifier>.

Por ejemplo, use la etiqueta <Identifier> para definir contadores independientes para cada ID de cliente. En una solicitud a tu proxy, la aplicación cliente envía un encabezado que contiene el clientID, como se muestra en el ejemplo anterior.

Puede especificar cualquier variable de flujo en el atributo <Identifier>. Por ejemplo, puede especificar que un parámetro de consulta llamado id contenga el identificador único:

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

Si usas la política VerifyAPIKey para validar la clave de API o las políticas OAuthV2 con tokens de OAuth, puedes usar la información de la clave de API o del token para definir contadores individuales de la misma política de cuota. Por ejemplo, el siguiente elemento <Identifier> usa la variable de flujo client_id de una política VerifyAPIKey llamada verify-api-key:

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

Cada valor client_id único define ahora su propio contador en la política Quota.

Clase

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

Puedes definir límites de cuota de forma dinámica usando un recuento de cuota basado en clases. En este ejemplo, el límite de cuota se determina mediante el valor del encabezado developer_segment que se envía con cada solicitud. Esta variable puede tener el valor platinum o silver. Si el encabezado tiene un valor no válido, la política devuelve un error de infracción de cuota.

Elemento <Quota>

A continuación, se muestran los atributos y los elementos secundarios de <Quota>. Ten en cuenta que algunas combinaciones de elementos son mutuamente excluyentes o no son obligatorias. Consulta los ejemplos para ver cómo se usa.

Las variables verifyapikey.my-verify-key-policy.apiproduct.* que se muestran a continuación están disponibles de forma predeterminada cuando se usa una política VerifyAPIKey llamada my-verify-key-policy para comprobar la clave de API de la aplicación en la solicitud. Los valores de las variables proceden de la configuración de cuota del producto de API al que está asociada la clave, tal como se describe en el artículo Obtener la configuración de cuota del producto de 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>

Los siguientes atributos son específicos de esta política:

Atributo Descripción Predeterminado Presencia
tipo

Define el tipo de política de cuota, que determina cuándo y cómo comprueba el contador de cuota el uso de la cuota, así como la forma en que se restablece.

Si no defines type, el contador empieza al principio del minuto, la hora, el día, la semana o el mes.

A continuación se muestran los valores válidos.

  • calendar
  • rollingwindow
  • flexi

Para ver una descripción completa de cada tipo, consulta Tipos de políticas de cuota.

 N/A Opcional

En la siguiente tabla se describen los atributos que son comunes a todos los elementos superiores de la política:

Atributo Descripción Predeterminado Presencia
name

El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres.

Opcionalmente, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

 N/A Obligatorio
continueOnError

Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas.

Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también:

 falso Opcional
enabled

Asigna el valor true para aplicar la política.

Selecciona false para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo.

 true Opcional
async

Este atributo está obsoleto.

 falso Obsoleto

Elemento <DisplayName>

Úsalo junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

<DisplayName>Policy Display Name</DisplayName>
Predeterminado

N/A

Si omite este elemento, se usará el valor del atributo name de la política.
Presencia Opcional
Tipo Cadena

<Allow>

Especifica el límite de recuento de la cuota. Si el contador de la política alcanza este límite, se rechazarán las llamadas posteriores hasta que se restablezca el contador.

También puede contener un elemento <Class> que condicione el elemento <Allow> en función de una variable de flujo.

Valor predeterminado n/a
¿Es obligatorio? Opcional
Tipo Tipo Entero o Complejo
Elemento principal <Quota>
Elementos secundarios <Class>

A continuación, se muestran tres formas de definir el elemento <Allow>:

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

Si especificas tanto count como countRef, countRef tiene prioridad. Si countRef no se resuelve en el tiempo de ejecución, se usa el valor de count.

También puede especificar un elemento <Class> como elemento secundario de <Allow> para determinar el número permitido de la política en función de una variable de flujo. Apigee compara el valor de la variable de flujo con el atributo class del elemento <Allow>, tal como se muestra a continuación:

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

En la siguiente tabla se enumeran los atributos de <Allow>:

Atributo Descripción Predeterminado Presencia
recuento

Se usa para especificar el número de mensajes de la cuota.

Por ejemplo, si el valor del atributo count es 100, el de Interval es 1 y el de TimeUnit es "month" (mes), se especifica una cuota de 100 mensajes al mes.

 2000 Opcional
countRef

Se usa para especificar una variable de flujo que contenga el recuento de mensajes de una cuota. countRef tiene prioridad sobre el atributo count.

 ninguno Opcional

<Class>

Te permite condicionar el valor del elemento <Allow> en función del valor de una variable de flujo. Para cada etiqueta secundaria <Allow> diferente de <Class>, la política mantiene un contador diferente.

Valor predeterminado n/a
¿Es obligatorio? Opcional
Tipo Tipo complejo
Elemento principal <Allow>
Elementos secundarios <Allow> (elemento secundario de <Class>)

Para usar el elemento <Class>, especifica una variable de flujo mediante el atributo ref del elemento <Class>. A continuación, Apigee usa el valor de la variable de flujo para seleccionar uno de los elementos secundarios <Allow> y determinar el número permitido de la política. Apigee compara el valor de la variable de flujo con el atributo class del elemento <Allow>, tal como se muestra a continuación:

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

En este ejemplo, el contador de cuota actual se determina mediante el valor del parámetro de consulta time_variable que se envía con cada solicitud. Esta variable puede tener el valor peak_time o off_peak_time. Si el parámetro de consulta contiene un valor no válido, la política devuelve un error de infracción de cuota.

En la siguiente tabla se enumeran los atributos de <Class>:

Atributo Descripción Predeterminado Presencia
ref Se usa para especificar una variable de flujo que contenga la clase de cuota de una cuota. ninguno Obligatorio

<Allow> (hijo de <Class>)

Especifica el límite de un contador de cuota definido por el elemento <Class>. Para cada etiqueta secundaria <Allow> diferente de <Class>, la política mantiene un contador diferente.

Valor predeterminado n/a
¿Es obligatorio? Opcional
Tipo Tipo complejo
Elemento principal <Class>
Elementos secundarios Ninguno

Por ejemplo:

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

En este ejemplo, la política de cuota mantiene dos contadores de cuota llamados peak_time y off_peak_time. El que se use dependerá del parámetro de consulta que se haya enviado, como se muestra en el ejemplo de <Class>.

En la siguiente tabla se enumeran los atributos de <Allow>:

Atributo Descripción Predeterminado Presencia
clase Define el nombre del contador de cuota. ninguno Obligatorio
recuento Especifica el límite de cuota del contador. ninguno Obligatorio

<Interval>

Especifica el número de periodos en los que se calculan las cuotas.

Valor predeterminado n/a
¿Es obligatorio? Obligatorio
Tipo Entero
Elemento principal <Quota>
Elementos secundarios Ninguno

Se usa para especificar un número entero (por ejemplo, 1, 2, 5, 60, etc.) que se emparejará con el elemento <TimeUnit> que especifiques (minuto, hora, día, semana o mes) para determinar un periodo durante el cual Apigee calcula el uso de la cuota.

Por ejemplo, un intervalo de 24 con un <TimeUnit> de hour significa que la cuota se calculará a lo largo de 24 horas.

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

En la siguiente tabla se enumeran los atributos de <Interval>:

Atributo Descripción Predeterminado Presencia
ref

Se usa para especificar una variable de flujo que contenga el intervalo de una cuota. ref tiene prioridad sobre un valor de intervalo explícito. Si se especifican tanto la referencia como el valor, la referencia tiene prioridad. Si ref no se resuelve en el tiempo de ejecución, se usa el valor.

 ninguno Opcional

<TimeUnit>

Especifica la unidad de tiempo aplicable a la cuota.

Valor predeterminado n/a
¿Es obligatorio? Obligatorio
Tipo Cadena
Elemento principal <Quota>
Elementos secundarios Ninguno

Elige entre minute, hour, day, week, month o year.

Por ejemplo, si el Interval es 24 y el TimeUnit es hour, la cuota se calculará a lo largo de 24 horas.

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
Valor predeterminado: ninguno
Presencia: Obligatorio
Tipo: Cadena

En la siguiente tabla se enumeran los atributos de <TimeUnit>:

Atributo Descripción Predeterminado Presencia
ref Especifica una variable de flujo que contiene la unidad de tiempo de una cuota. ref tiene prioridad sobre un valor de intervalo explícito. Si ref no se resuelve en el tiempo de ejecución, se usa el valor del intervalo. ninguno Opcional

<StartTime>

Si type se define como calendar, se especifica la fecha y la hora en las que el contador de cuota empieza a contar, independientemente de si se han recibido solicitudes de alguna aplicación.

Valor predeterminado n/a
¿Es obligatorio? Opcional (obligatorio si type tiene el valor calendar)
Tipo Cadena en formato de fecha y hora ISO 8601
Elemento principal <Quota>
Elementos secundarios Ninguno

Por ejemplo:

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

<Distributed>

Determina si Apigee usa uno o varios nodos para procesar solicitudes.

Valor predeterminado falso
¿Es obligatorio? Opcional
Tipo Booleano
Elemento principal <Quota>
Elementos secundarios Ninguno

Defina el valor true para especificar que la política debe mantener un contador central y sincronizarlo continuamente en todos los nodos. Los nodos pueden estar en zonas de disponibilidad o regiones diferentes.

Si usas el valor predeterminado false, es posible que superes tu cuota, ya que el recuento de cada nodo no se comparte:

<Distributed>false</Distributed>

Para asegurarte de que los contadores se sincronicen y se actualicen en cada solicitud, define <Distributed> y <Synchronous> como true:

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

<Synchronous>

Determina si se debe actualizar un contador de cuota distribuida de forma síncrona.

Valor predeterminado falso
¿Es obligatorio? Opcional
Tipo Booleano
Elemento principal <Quota>
Elementos secundarios Ninguno

Se define como true para actualizar un contador de cuota distribuida de forma síncrona. Esto significa que los contadores se actualizan al mismo tiempo que se comprueba la cuota de una solicitud a la API. Asigna el valor true si es fundamental que no permitas ninguna llamada a la API que supere la cuota.

Asigna el valor false para actualizar el contador de cuota de forma asíncrona. Esto significa que es posible que se completen algunas llamadas a la API que superen la cuota, en función de cuándo se actualice de forma asíncrona el contador de cuotas en el repositorio central. Sin embargo, no se verá afectado por los posibles problemas de rendimiento asociados a las actualizaciones síncronas.

El intervalo de actualización asíncrona predeterminado es de 10 segundos. Usa el elemento <AsynchronousConfiguration> para configurar este comportamiento asíncrono.

<Synchronous>false</Synchronous>

<AsynchronousConfiguration>

Configura el intervalo de sincronización entre los contadores de cuota distribuidos cuando el elemento de configuración de la política <Synchronous> no está presente o está presente y se ha definido como false. Apigee ignora este elemento cuando <Synchronous> tiene el valor true.

Valor predeterminado n/a
¿Es obligatorio? Opcional
Tipo Tipo complejo
Elemento principal <Quota>
Elementos secundarios <SyncIntervalInSeconds>
<SyncMessageCount>

Puedes especificar el comportamiento de la sincronización mediante los elementos secundarios <SyncIntervalInSeconds> o <SyncMessageCount>. Usa uno de los elementos o ambos. Por ejemplo,

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

o

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
  • Si solo está presente <SyncIntervalInSeconds>, la cuota se sincroniza cada N segundos, donde N es el valor especificado en el elemento, independientemente del número de mensajes que se hayan gestionado.
  • Si solo se incluye <SyncMessageCount>, la cuota se sincroniza cada M mensajes, donde M es el valor especificado en el elemento, o cada 10 segundos, lo que ocurra primero.
  • Cuando ambos elementos están presentes, la cuota se sincroniza cada M mensajes o cada N segundos, lo que ocurra primero.
  • Si <AsynchronousConfiguration> no está presente o no hay ningún elemento secundario, la cuota se sincroniza cada 10 segundos, independientemente del número de mensajes que se hayan gestionado.

<SyncIntervalInSeconds>

Anula el comportamiento predeterminado, en el que las actualizaciones asíncronas se realizan después de un intervalo de 10 segundos.

Valor predeterminado 10 segundos
¿Es obligatorio? Opcional
Tipo Entero
Elemento principal <AsynchronousConfiguration>
Elementos secundarios Ninguno
 
<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

El intervalo de sincronización debe ser igual o superior a 10 segundos, tal como se describe en la sección Límites.

<SyncMessageCount>

Especifica el número de solicitudes que se deben procesar antes de sincronizar el contador de cuota.

Valor predeterminado n/a
¿Es obligatorio? Opcional
Tipo Entero
Elemento principal <AsynchronousConfiguration>
Elementos secundarios Ninguno
 
<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

Con la configuración de este ejemplo, en cada nodo, el recuento de cuota se sincronizará cada 5 solicitudes o cada 10 segundos, lo que ocurra primero.

<Identifier>

Configura la política para crear contadores únicos basados en una variable de flujo.

Valor predeterminado n/a
¿Es obligatorio? Opcional
Tipo Cadena
Elemento principal <Quota>
Elementos secundarios Ninguno

Con el elemento Identifier, puede asignar recuentos de llamadas a distintos contenedores definidos por el valor de una variable de flujo. Por ejemplo, puede usar la variable developer.id, que se rellena después de una política VerifyAPIKey, para aplicar un límite de cuota a todas las instancias de todas las aplicaciones creadas por cada desarrollador específico, o bien puede usar client_id para aplicar un límite de cuota a cada aplicación concreta. La configuración de esta última opción es la siguiente:

<Identifier ref="client_id"/>

Puedes hacer referencia a una variable personalizada que hayas definido con la política AssignMessage o la política JavaScript, o bien a una variable que se haya definido implícitamente, como las que definen la política VerifyAPIKey o la política VerifyJWT. Para obtener más información sobre las variables, consulta el artículo Usar variables de flujo. Para ver una lista de las variables conocidas definidas por Apigee, consulta la referencia de variables de flujo.

Si no usas este elemento, la política asigna todos los recuentos de llamadas a un solo contador de la política de cuotas en cuestión.

Este elemento también se explica en ¿Cómo funciona la política de cuota cuando no se especifica ningún identificador?

En la siguiente tabla se describen los atributos de <Identifier>:

Atributo Descripción Predeterminado Presencia
ref

Especifica una variable de flujo que identifica el contador que se va a usar en la solicitud. La variable puede hacer referencia a un encabezado HTTP, un parámetro de consulta, un parámetro de formulario o un elemento del contenido del mensaje, o bien a otro valor para identificar cómo asignar los recuentos de llamadas.

El client_id se suele usar como variable. La client_id también se conoce como clave de API o clave de consumidor, y se genera para una aplicación cuando se registra en una organización de Apigee. Puedes usar este identificador si has habilitado las políticas de autorización de claves de API u OAuth para tu API.

 N/A Opcional

<MessageWeight>

Especifica el coste asignado a cada mensaje a efectos de cuota. Utiliza este elemento para asignar un impacto diferente a las solicitudes de API en función de su contenido o del valor de la llamada.

Valor predeterminado n/a
¿Es obligatorio? Opcional
Tipo Entero
Elemento principal <Quota>
Elementos secundarios Ninguno

Por ejemplo, cuando Apigee gestiona una API de modelo de lenguaje extenso (LLM), puedes usar el número de tokens de la solicitud o de la respuesta, o de ambas, como <MessageWeight>.

O bien, si quieres que los mensajes POST cuesten el doble que los mensajes GET, asigna el valor 2 a <MessageWeight> para POST y el valor 1 para GET. Supongamos que la cuota es de 10 mensajes por minuto y que el proxy procesa 5 solicitudes POST en los primeros 35 segundos. El proxy rechazará cualquier solicitud adicional, POST o GET, hasta que se restablezca el contador.

El valor que representa <MessageWeight> se debe especificar mediante una variable de flujo y se puede extraer de encabezados HTTP, parámetros de consulta, una carga útil de solicitud XML o JSON, o cualquier otra variable de flujo. Por ejemplo, puedes extraer el valor de una carga útil de respuesta en una variable llamada extracted.message_weight y, a continuación, usarla para <MessageWeight>:

<MessageWeight ref="extracted.message_weight"/>

Si la variable de flujo se resuelve como 0, la solicitud no afectará al contador.

<UseQuotaConfigInAPIProduct>

Define los ajustes de cuota de un producto de API, como las unidades de tiempo, el intervalo y el máximo permitido.

Valor predeterminado n/a
¿Es obligatorio? Opcional
Tipo Tipo complejo
Elemento principal <Quota>
Elementos secundarios <DefaultConfig>

Si añade el elemento <UseQuotaConfigInAPIProduct> a la política de cuota, Apigee ignorará los elementos secundarios <Allow>, <Interval> y <TimeUnit> de <Quota>.

El elemento <UseQuotaConfigInAPIProduct> es simplemente un contenedor de los ajustes predeterminados que definas con el elemento <DefaultConfig>, como se muestra en el siguiente ejemplo:

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

Puede usar el atributo stepName para hacer referencia a una política VerifyAPIKey o a una operación de política ValidateToken de la política OAuthv2 en el flujo.

En la siguiente tabla se describen los atributos de <UseQuotaConfigInAPIProduct>:

Atributo Descripción Predeterminado Presencia
stepName Identifica el nombre de la política de autenticación en el flujo. El objetivo puede ser una política VerifyAPIKey o una política OAuthv2. N/A Obligatorio

Para obtener más información, consulta las siguientes secciones:

<DefaultConfig>

Contiene los valores predeterminados de la cuota de un producto de la API. Cuando defines un <DefaultConfig>, los tres elementos secundarios son obligatorios.

Valor predeterminado n/a
¿Es obligatorio? Opcional
Tipo Tipo complejo
Elemento principal <UseQuotaConfigInAPIProduct>
Elementos secundarios <Allow>
<Interval>
<TimeUnit>

Puedes definir estos valores en la operación del producto de API (ya sea con la interfaz de usuario o con la API Products API) y en la política de cuota. Sin embargo, si lo hace, los ajustes del producto de API tendrán prioridad y se ignorarán los de la política de cuota.

La sintaxis de este elemento es la siguiente:

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

En el siguiente ejemplo se especifica una cuota de 10.000 cada semana:

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

Para obtener más información, consulta las siguientes secciones:

<SharedName>

Identifica esta política de cuotas como compartida. Todas las políticas de cuotas de un proxy de API con el mismo valor de <SharedName> comparten el mismo contador de cuotas subyacente. Si este elemento está presente, también debe estarlo el elemento <EnforceOnly> o <CountOnly>.

Para obtener más información y ejemplos, consulta Configurar contadores de cuota compartida.

Valor predeterminado n/a
¿Es obligatorio? Opcional
Tipo Cadena
Elemento principal <Quota>
Elementos secundarios Ninguno

<CountOnly>

Coloca una política de cuota con este elemento definido como true en un paso del flujo de respuesta de ProxyEndpoint para aumentar el contador de cuota subyacente sin enviar un error al cliente cuando se supere el límite de cuota. Si este elemento está presente, el elemento <SharedName> también debe estarlo, y el elemento <EnforceOnly> no debe estar presente.

Para obtener más información y ejemplos, consulta Configurar contadores de cuota compartidos.

Valor predeterminado falso
¿Es obligatorio? Opcional
Tipo Booleano
Elemento principal <Quota>
Elementos secundarios Ninguno

<EnforceOnly>

Coloca una política de cuotas con este elemento definido como true en el flujo de solicitudes de un proxy de API para aplicar una cuota sin incrementar el contador de cuotas. Esta configuración permite aplicar los límites de frecuencia de forma diferida en función del peso de los mensajes, que solo se puede conocer en el flujo de respuesta. Si este elemento está presente, también debe estarlo <SharedName>, y el elemento <CountOnly> no debe estar presente.

Para obtener más información y ejemplos, consulta Configurar contadores de cuota compartidos.

Valor predeterminado falso
¿Es obligatorio? Opcional
Tipo Booleano
Elemento principal <Quota>
Elementos secundarios Ninguno

Variables de flujo

Las siguientes variables de flujo predefinidas se rellenan automáticamente cuando se ejecuta una política de cuota. Para obtener más información, consulta la referencia de variables de flujo.

Variables Tipo Permisos Descripción
ratelimit.{policy_name}.allowed.count Long Solo lectura Devuelve el recuento de cuota permitido.
ratelimit.{policy_name}.used.count Long Solo lectura Devuelve la cuota actual usada en un intervalo de cuota.
ratelimit.{policy_name}.available.count Long Solo lectura Devuelve el número de cuotas disponibles en el intervalo de cuota.
ratelimit.{policy_name}.exceed.count Long Solo lectura Devuelve 1 cuando se supera la cuota.
ratelimit.{policy_name}.total.exceed.count Long Solo lectura Devuelve 1 cuando se supera la cuota.
ratelimit.{policy_name}.expiry.time Long Solo lectura

Devuelve la hora UTC (en milisegundos), que determina cuándo vence la cuota y cuándo empieza el nuevo intervalo de cuota.

Cuando el tipo de la política de cuota es rollingwindow, este valor no es válido porque el intervalo de cuota nunca caduca.
ratelimit.{policy_name}.identifier Cadena Solo lectura Devuelve la referencia del identificador (de cliente) adjunta a la política.
ratelimit.{policy_name}.class Cadena Solo lectura Devuelve la clase asociada al identificador de cliente.
ratelimit.{policy_name}.class.allowed.count Long Solo lectura Devuelve el recuento de cuota permitido definido en la clase.
ratelimit.{policy_name}.class.used.count Long Solo lectura Devuelve la cuota utilizada en una clase.
ratelimit.{policy_name}.class.available.count Long Solo lectura Devuelve el número de cuotas disponibles en la clase.
ratelimit.{policy_name}.class.exceed.count Long Solo lectura Devuelve el número de solicitudes que supera el límite de la clase en el intervalo de cuota actual.
ratelimit.{policy_name}.class.total.exceed.count Long Solo lectura Devuelve el recuento total de solicitudes que superan el límite de la clase en todos los intervalos de cuota, por lo que es la suma de class.exceed.count de todos los intervalos de cuota.
ratelimit.{policy_name}.failed Booleano Solo lectura

Indica si la política ha fallado (true o false).

Referencia de errores

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Código de falla Estado de HTTP Causa Corregir
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 Ocurre si el elemento <Interval> no está definido dentro de la política Quota. Este elemento es obligatorio y se usa para especificar el intervalo de tiempo aplicable a la cuota. El intervalo de tiempo puede ser de minutos, horas, días, semanas o meses, según se defina con el elemento <TimeUnit>.
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference 500 Ocurre si el elemento <TimeUnit> no está definido dentro de la política Quota. Este elemento es obligatorio y se usa para especificar la unidad de tiempo aplicable a la cuota. El intervalo de tiempo puede ser en minutos, horas, días, semanas o meses.
policies.ratelimit.InvalidMessageWeight 500 Este error se produce si el valor del elemento <MessageWeight> que se especificó a través de una variable de flujo no es válido (un número que no es entero).
policies.ratelimit.QuotaViolation 500 Se superó el límite de la cuota. N/A

Errores en la implementación

Nombre del error Causa Corregir
InvalidQuotaInterval Si el intervalo de cuota especificado en el elemento <Interval> no es un número entero, fallará la implementación del proxy de la API. Por ejemplo, si el intervalo de cuota especificado es 0.1 en el elemento <Interval>, fallará la implementación del proxy de API.
InvalidQuotaTimeUnit Si la unidad de tiempo especificada en el elemento <TimeUnit> no es compatible, fallará la implementación del proxy de API. Las unidades de tiempo admitidas son minute, hour, day, week y month.
InvalidQuotaType Si el tipo de cuota especificado por el atributo type en el elemento <Quota> no es válido, fallará la implementación del proxy de la API. Los tipos de cuota admitidos son default, calendar, flexi y rollingwindow.
InvalidStartTime Si el formato del tiempo especificado en el elemento <StartTime> no es válido, fallará la implementación del proxy de la API. El formato válido es yyyy-MM-dd HH:mm:ss, que es el formato de fecha y hora ISO 8601. Por ejemplo, si la hora especificada en el elemento <StartTime> es 7-16-2017 12:00:00, fallará la implementación del proxy de API.
StartTimeNotSupported Si se especifica el elemento <StartTime> cuyo tipo de cuota no es calendar, fallará la implementación del proxy de API. El elemento <StartTime> solo es compatible con el tipo de cuota calendar. Por ejemplo, si el atributo type se establece en flexi o rolling window en el elemento <Quota>, fallará la implementación del proxy de la API.
InvalidTimeUnitForDistributedQuota Si el elemento <Distributed> se configura como true y el elemento <TimeUnit> se configura como second, fallará la implementación del proxy de la API. La unidad de tiempo second no es válida para una cuota distribuida.
InvalidSynchronizeIntervalForAsyncConfiguration Si el valor especificado para el elemento <SyncIntervalInSeconds> dentro del elemento <AsynchronousConfiguration> en una política de Quota es inferior a cero, fallará la implementación del proxy de la API.
InvalidAsynchronizeConfigurationForSynchronousQuota Si el valor del elemento <AsynchronousConfiguration> se establece en true en una política Quota, que también tiene una configuración asíncrona definida con el elemento <AsynchronousConfiguration>, la implementación del proxy de la API falla.

Variables con fallas

Estas variables se establecen cuando esta política activa un error. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables Donde Ejemplo
fault.name="fault_name" fault_name es el nombre de la falla, como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla. fault.name Matches "QuotaViolation"
ratelimit.policy_name.failed policy_name es el nombre especificado por el usuario de la política que generó la falla. ratelimit.QT-QuotaPolicy.failed = true

Ejemplo de respuesta de error

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

Ejemplo de regla de falla

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

Esquemas

Temas relacionados

Política ResetQuota

Política SpikeArrest

Comparación de las políticas de cuotas y de retención de picos