Política de cuotas

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

Qué

Usa la política de cuotas para configurar la cantidad de mensajes de solicitud que permite el proxy de API durante un período, como un minuto, una hora, un día, una semana o un mes. Puedes configurar la cuota para que sea la misma para todas las apps que acceden al proxy de API. También puedes configurar la cuota en función de lo siguiente:

  • El producto que contiene el proxy de API
  • La app que solicita la API
  • El programador de apps
  • Muchos otros criterios

No uses la cuota para protegerte contra los aumentos de tráfico generales. Para eso, usa la política SpikeArrest. Consulta la política SpikeArrest.

Videos

En estos videos, se presenta la administración de cuotas con la política de cuotas:

Introducción (Edge nuevo)

Introducción (Edge clásico)

Cuota dinámica

Sincrónico y distribuido

Peso del mensaje

Calendario

Ventana móvil

Flexi

Cuota condicional

Variables de flujo

Manejo de errores

Ejemplos

En estos ejemplos de código de política, se muestra cómo comenzar y finalizar los períodos 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 política de cuota única que aplique una configuración de cuota diferente según la información que se pase a la política de cuotas. Otro término para la configuración de cuotas en este contexto es el “Plan de servicio”. La cuota dinámica comprueba el “plan de servicio” de la app y, luego, aplica esa configuración.

Nota: Si especificas un valor y una referencia para un elemento, la referencia tiene la prioridad. Si la referencia no se resuelve en el tiempo de ejecución, se usa el valor.

Por ejemplo, cuando creas un producto de API, tienes la opción de configurar el límite de cuota, la unidad de tiempo y el intervalo permitidos. Sin embargo, establecer este valor en el producto de API no impone su uso en un proxy de API. También debes agregar una política de cuota al proxy de API que lea estos valores. Consulta Crea productos de API para obtener más información.

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 pasa en una solicitud. Luego, la política de cuotas accede a las variables de flujo de la política VerifyAPIKey para leer los valores de cuota establecidos en el producto de API. Para obtener más información sobre las variables de flujo de VerifyAPIKey, consulta Política de VerifyAPIKey.

Otra opción es configurar atributos personalizados en desarrolladores o apps individuales y, luego, leer esos valores en la política de cuotas. Por ejemplo, deseas establecer diferentes valores de cuotas por desarrollador. En este caso, debes configurar atributos personalizados en el desarrollador que contienen el límite, la unidad de tiempo y el intervalo. Luego, debes hacer referencia a estos valores en la política de cuotas 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 establecidos en el desarrollador.

Puedes usar cualquier variable para configurar los parámetros de la política de cuotas. Estas variables pueden provenir de las siguientes fuentes:

  • Variables de flujo
  • Propiedades en el producto, la app o el desarrollador de la API
  • Un mapa de clave-valor (KVM)
  • Un encabezado, parámetro de búsqueda, parámetro de formulario, etcétera

Para cada proxy de API, puedes agregar una política de cuotas que haga referencia a la misma variable que todas las demás políticas de cuotas, o la política de cuotas puede hacer referencia a variables únicas para esa política y proxy.

Hora de inicio

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

Para una cuota con type establecido como calendar, debes definir un valor <StartTime> explícito. El valor de tiempo es la hora GMT, no la hora local. Si no proporcionas un valor <StartTime> para una política de tipo calendar, Edge emite un error.

El contador de cuotas para cada app se actualiza en función de los valores <StartTime>, <Interval> y <TimeUnit>. En este ejemplo, la cuota comienza a contar a las 10:30 a.m. GMT del 18 de febrero de 2017 y se actualiza cada 5 horas. Por lo tanto, la próxima actualización es a las 3:30 p.m. GMT del 18 de febrero de 2017.

Contador de acceso

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

Un proxy de API tiene acceso a las variables de flujo que configura la política de cuotas. Puedes acceder a estas variables de flujo en el proxy de API para realizar el procesamiento condicional, supervisar la política a medida que se acerca al límite de la cuota, mostrar el recuento de cuota actual a una app o por otras razones.

Debido a que el acceso a las variables de flujo para la política se basa en el atributo name de las políticas, para la política anterior QuotaPolicy, puedes acceder a sus variables de flujo en el formato:

  • ratelimit.QuotaPolicy.allowed.count: Recuento Permitido
  • ratelimit.QuotaPolicy.used.count: Valor actual de contador
  • ratelimit.QuotaPolicy.expiry.time: Hora de UTC cuando se restablece el contador.

Existen muchas otras variables de flujo a las que puedes acceder, como se describe a continuación.

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

<AssignMessage async="false" continueOnError="false" enabled="true" name="ReturnQuotaVars">
    <AssignTo createNew="false" type="response"/>
    <Set>
        <Headers>
            <Header name="QuotaLimit">{ratelimit.QuotaPolicy.allowed.count}</Header>
            <Header name="QuotaUsed">{ratelimit.QuotaPolicy.used.count}</Header>
            <Header name="QuotaResetUTC">{ratelimit.QuotaPolicy.expiry.time}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

Primera solicitud

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

Usa este código de muestra para aplicar una cuota de 10,000 llamadas por hora. La política restablece el recuento de cuotas en la parte superior de cada hora. Si el recuento alcanza la cuota de 10,000 llamadas antes de que finalice la hora, se rechazan las llamadas que superen los 10,000.

Por ejemplo, si el recuento comienza el 2017-07-08 07:00:00, se restablece en 0 a las 2017-07-08 08:00:00 (1 hora desde la hora de inicio). Si el primer mensaje se recibe a las 2017-07-08 07:35:28 y el recuento de mensajes alcanza los 10,000 antes de 2017-07-08 08:00:00, las llamadas posteriores a ese recuento se rechazan hasta que el recuento se restablezca en la parte superior de la hora.

El tiempo de restablecimiento de contadores se basa en la combinación de <Interval> y <TimeUnit>. Por ejemplo, si estableces <Interval> en 12 por un <TimeUnit> de hora, el contador se restablece cada doce horas. Puedes configurar <TimeUnit> como minutos, horas, días, semanas o meses.

Puedes hacer referencia a esta política en varias partes del proxy de API. Por ejemplo, puedes ubicarla en el PreFlow del proxy para que se ejecute en cada solicitud. O bien, puedes ubicarla en varios flujos en el proxy de API. Si usas esta política en varios lugares del proxy, mantendrá un solo contador que se actualice para todas las instancias de la política.

También puedes definir varias políticas de cuotas en el proxy de API. Cada política de cuota mantiene su propio contador, según el atributo name de la política.

Identificador de conjunto

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

De forma predeterminada, una política de cuotas define un solo contador para el proxy de API, sin importar el origen de una solicitud. Como alternativa, puedes usar el atributo <Identifier> con una política de cuotas para mantener contadores separados según el valor del atributo <Identifier>.

Por ejemplo, usa la etiqueta <Identifier> a fin de definir contadores independientes para cada ID de cliente. En una solicitud a tu proxy, la app cliente pasa un encabezado que contiene clientID, como se muestra en el ejemplo anterior.

Puedes especificar cualquier variable de flujo para el atributo <Identifier>. Por ejemplo, puedes especificar que un parámetro de búsqueda llamado id contenga el identificador único:

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

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

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

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

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 establecer límites de cuotas de forma dinámica mediante un recuento de cuota basado en la clase. En este ejemplo, el límite de cuota se determina según el valor del encabezado developer_segment que se pasa con cada solicitud. Esa variable puede tener un valor de platinum o silver. Si el encabezado tiene un valor no válido, la política muestra un error de incumplimiento de cuota.


Acerca de la política de cuotas

Una cuota es una asignación de mensajes de solicitud que un proxy de API puede controlar durante un período, como un minuto, una hora, un día, una semana o un mes. La política mantiene contadores que registran la cantidad de solicitudes recibidas por el proxy de API. Esta capacidad permite que los proveedores de API apliquen límites a la cantidad de llamadas a la API que realizan las aplicaciones en un intervalo de tiempo. Mediante las políticas de cuotas, puedes, por ejemplo, limitar las apps a 1 solicitud por minuto o 10,000 solicitudes por mes.

Por ejemplo, si una cuota se define como 10,000 mensajes por mes, el límite de frecuencia comienza después del mensaje 10,000. No importa si se contaron 10,000 mensajes el primer o el último día de ese período. No se permite ningún área de solicitudes adicional hasta que el contador de cuotas se restablezca automáticamente al final del intervalo de tiempo especificado o hasta que la cuota se restablezca de forma explícita mediante Restablecer la política de cuota.

Una variación de Quota llamada SpikeArrest que impide los aumentos repentinos de tráfico (o aumentos de actividad) que pueden deberse a un aumento repentino en el uso, a clientes con errores o a ataques maliciosos. Para obtener más información sobre SpikeArrest, consulta la política de Arrestación de Spike.

Las cuotas se aplican a los proxies de API individuales y no se distribuyen entre los proxies de API. Por ejemplo, si tienes tres proxies de API en un producto de API, una sola cuota no se comparte en los tres, incluso si los tres usan la misma configuración de política de cuotas.

Tipos de políticas de cuotas

La política de cuotas admite varios tipos diferentes de políticas predeterminadas: calendar, flexi y rollingwindow. Cada tipo define cuándo se inicia el contador de cuota y se restablece, como se muestra en la siguiente tabla:

Unidad de tiempo Restablecimiento predeterminado (o nulo) restablecer calendario restablecer flexi
minuto Inicio del próximo minuto Un minuto después de <StartTime> Un minuto después de la primera solicitud
hora Parte superior de la próxima hora 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 del <StartTime> 24 horas después de la primera solicitud
semana El domingo a la medianoche GMT cuando termina 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

Para type="calendar", debes especificar el valor de <StartTime>.

La tabla no enumera el valor del tipo rollingwindow. Las cuotas de ventana móvil funcionan si configuras el tamaño de una "ventana" de cuota, como una ventana de una hora o un día. Cuando llega una solicitud nueva, la política determina si se superó la cuota en el “período” anterior de tiempo.

Por ejemplo, puedes definir un período de dos horas que permita 1,000 solicitudes. Se envía una solicitud nueva a las 4:45 p.m. La política calcula la cantidad de cuotas para las últimas dos horas, lo que significa la cantidad de solicitudes desde las 2:45 p.m. Si el límite de cuota no se excede en esa ventana de dos horas, se permite la solicitud.

Un minuto después, a las 4:46 p.m., ingresa otra solicitud. Ahora la política calcula el recuento de cuotas desde las 2:46 p.m. para determinar si se superó el límite.

Para el tipo rollingwindow, el contador nunca se restablece, pero se vuelve a calcular en cada solicitud.

Obtén información sobre los contadores de cuota

De forma predeterminada, una política de cuotas mantiene un solo contador, sin importar cuántas veces se haga referencia a ella en un proxy de API. El nombre del contador de cuotas se basa en el atributo name de la política.

Por ejemplo, creas una política de cuotas llamada MyQuotaPolicy con un límite de 5 solicitudes y la coloca en varios flujos (flujo A, B y C) en el proxy de API. Aunque se usa en varios flujos, mantiene un solo contador que se actualiza en 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 el contador = 2
  • Se ejecuta el flujo A -> Se ejecuta MyQuotaPolicy y el contador = 3
  • Se ejecuta el flujo C -> MyQuotaPolicy se ejecuta 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 es rechazada porque el contador de cuota alcanzó su límite.

El uso de la misma política de cuotas en más de un lugar de un flujo de proxy de API, que puede hacer que la cuota se agote por accidente más rápido de lo esperado, es un antipatrón que se describe en El libro de antipatrones de Apigee Edge.

Como alternativa, 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, según el atributo name de la política.

También puedes usar los elementos <Class> o <Identifier> en la política de cuotas para definir varios contadores únicos en una sola política. Si usas estos elementos, una sola política puede mantener diferentes contadores según la aplicación que realice la solicitud, el desarrollador de la aplicación que realiza la solicitud, un ID de cliente o cualquier otro identificador de cliente y más. Consulta los ejemplos anteriores para obtener más información sobre el uso de los elementos <Class> o <Identifier>.

Notación de tiempo

Todas las horas de la cuota se establecen en la zona horaria Horario universal coordinado (UTC).

La notación de hora de la cuota sigue la notación de fechas estándar internacional que se define en ISO 8601.

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

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

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

Obtén la configuración de cuotas desde la configuración de productos de la API

Puedes establecer límites de cuota en las configuraciones de productos de API. Esos límites no aplican automáticamente la cuota. En su lugar, puedes hacer referencia a la configuración de la cuota de productos en una política de cuotas. Estas son algunas ventajas de establecer una cuota en el producto para la referencia de las políticas de cuota:

  • Las políticas de cuotas pueden usar una configuración uniforme en todos los proxies de API del producto de la API.
  • Puedes realizar cambios en el entorno de ejecución a la configuración de cuotas en un producto de API y las políticas de cuota que hacen referencia al valor tienen automáticamente valores de cuota actualizados.

Si deseas obtener más información para usar la configuración de cuota desde un producto de la API, consulta el ejemplo de “Cuota dinámica” anterior..

Si deseas obtener más información para configurar productos de API con límites de cuota, consulta Crea productos de la API.

Referencia del elemento

A continuación, se describen los elementos y los atributos que puedes configurar en esta política. Ten en cuenta que algunas combinaciones de elementos son mutuamente excluyentes o no obligatorias. Consulta las muestras para un uso específico. Las variables verifyapikey.VerifyAPIKey.apiproduct.* a continuación están disponibles de forma predeterminada cuando se usa una política Verificar clave de API llamada “VerifyAPIKey” para verificar la clave de API de la app en la solicitud. Los valores de las variables provienen de la configuración de cuota del producto de la API con el que está asociada la clave, como se describe en Obtén la configuración de cuotas desde la configuración de productos de la API.

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>
   <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="5000"/>
        <Allow class="off_peak_time" count="1000"/>
      </Class>
   </Allow>
   <Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval> 
   <TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2017-7-16 12:00:00</StartTime> 
   <Distributed>false</Distributed> 
   <Synchronous>false</Synchronous> 
   <AsynchronousConfiguration> 
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds> 
      <SyncMessageCount>5</SyncMessageCount> 
   </AsynchronousConfiguration> 
   <Identifier/> 
   <MessageWeight/> 
</Quota>

Atributos <Quota>

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">

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

Atributo Descripción Predeterminada Presencia
tipo

Se usa para determinar cuándo y cómo el contador de cuota verifica el uso de la cuota. Consulta Tipos de políticas de cuotas para obtener más información.

Si omites un valor type, el contador comienza al comienzo del minuto, hora, día, semana o mes.

Estos son algunos de los valores válidos:

  • calendar: Configura una cuota según una hora de inicio explícita. El contador de cuotas para cada app se actualiza según los valores <StartTime>, <Interval> y <TimeUnit> que establezcas.
  • rollingwindow: Configura una cuota que use una “ventana móvil” para determinar el uso de la cuota. Con rollingwindow, determina el tamaño de la ventana con los elementos <Interval> y <TimeUnit>. por ejemplo, 1 día. Cuando llega una solicitud, Edge consulta la hora exacta de la solicitud (por ejemplo, a las 5:01 p.m.), cuenta la cantidad de solicitudes que se realizaron entre ese momento y las 5:01 p.m. del día anterior (1 día) y determina si se excedió o no la cuota durante ese período.
  • flexi: Configura una cuota que genere que el contador comience cuando se reciba el primer mensaje de solicitud de una app y se restablezca según los valores <Interval>, y <TimeUnit>.
calendario Opcional

En la siguiente tabla, se describen los atributos que son comunes a todos los elementos principales de las políticas:

Atributo Descripción Predeterminada 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.

De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

No disponible Obligatorias
continueOnError

Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas.

Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle.

false Opcional
enabled

Configúralo como true para aplicar la política.

Configúralo como false para desactivar la política. La política no se aplicará incluso si permanece adjunta a un flujo.

true Opcional
async

Este atributo dejó de estar disponible.

false Funciones obsoletas

Elemento <DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

<DisplayName>Policy Display Name</DisplayName>
Predeterminada

No disponible

Si omites este elemento, se usa el valor del atributo name de la política.

Presencia Opcional
Tipo Cadena

Elemento <Allow>

Especifica el límite de conteo para la cuota. Si el recuento de la política alcanza este valor de límite, las llamadas posteriores se rechazan hasta que se restablece el contador.

A continuación, se muestran tres formas de establecer 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 count y countRef, entonces countRef tiene la prioridad. Si countRef no se resuelve en el entorno de ejecución, se usa el valor de count.

Predeterminado: No disponible
Presencia: Opcional
Tipo: Número entero

Atributos

Atributo Descripción Predeterminada Presencia
count

Se usa para especificar un recuento de mensajes de la cuota.

Por ejemplo, un valor de atributo count de 100, Interval de 1 y TimeUnit de mes especifican una cuota de 100 mensajes por mes.

2000 Opcional
countRef

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

ninguno Opcional

Elemento <Allow>/<Class>

El elemento <Class> te permite normalizar el valor del elemento <Allow> según el valor de una variable de flujo. Por cada etiqueta secundaria <Allow> diferente de <Class>, la política mantiene un contador diferente.

Para usar el elemento <Class>, especifica una variable de flujo con el atributo ref a la etiqueta <Class>. Luego, Edge usa el valor de la variable de flujo para seleccionar una de las etiquetas secundarias <Allow> y determinar el recuento permitido de la política. Edge hace que el valor de la variable de flujo coincida con el atributo class de la etiqueta <Allow>, 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 la cuota actual se determina por el valor del parámetro de búsqueda time_variable que se pasa con cada solicitud. Esa variable puede tener un valor de peak_time o off_peak_time. Si el parámetro de consulta contiene un valor no válido, la política muestra un error de incumplimiento de cuota.

Predeterminado: No disponible
Presencia: Opcional
Tipo: No disponible

Atributos

Atributo Descripción Predeterminada Presencia
ref

Se usa para especificar una variable de flujo que contiene la clase de cuota de una cuota.

ninguno Obligatorio

Elemento <Allow>/<Class>/<Allow>

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

Por ejemplo:

<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, la política de cuotas mantiene dos contadores de cuotas con los nombres peak_time y off_peak_time.

Predeterminado: No disponible
Presencia: Opcional
Tipo: No disponible

Atributos

Atributo Descripción Predeterminada Presencia
clase

Define el nombre del contador de cuota.

ninguno Obligatorio
count Especifica el límite de cuota del contador. ninguno Obligatorio

Elemento <Interval>

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

Por ejemplo, un Interval de 24 con un TimeUnit de hour significa que la cuota se calculará durante 24 horas.

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>
Predeterminado: ninguno
Presencia: Obligatorio
Tipo: Número entero

Atributos

Atributo Descripción Predeterminada Presencia
ref

Se usa para especificar una variable de flujo que contiene el intervalo de una cuota. ref tiene prioridad sobre un valor del intervalo explícito. Si se especifican la referencia y el valor, la referencia obtiene la prioridad. Si ref no se resuelve en el entorno de ejecución, se usa el valor.

ninguna Opcional

Elemento <TimeUnit>

Se usa para especificar la unidad de tiempo aplicable a la cuota.

Por ejemplo, un Interval de 24 con un TimeUnit de hour significa que la cuota se calculará durante 24 horas.

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

String. Selecciona de minute, hour, day, week o month.

Atributos

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

Elemento <StartTime>

Cuando se configura type como calendar,, se especifica la fecha y la hora en que el contador de cuotas comenzará a contar, sin importar si se recibieron solicitudes de alguna app.

Debes proporcionar un StartTime explícito cuando type se establece de forma explícita como calendar,, no puedes usar una referencia a una variable de flujo. Si especificas un valor StartTime cuando no se estableció un valor type, recibirás un error.

Por ejemplo:

<StartTime>2017-7-16 12:00:00</StartTime>
Predeterminado: ninguno
Presencia: Obligatorio cuando type se establece como calendar.
Tipo:

String en formato de fecha y hora ISO 8601.

Elemento <Distributed>

Una instalación de Edge puede usar uno o más Message Processor para procesar solicitudes. Configura este elemento en true para especificar que la política debe mantener un recuento central y sincronizarlo continuamente en todos los procesadores de mensajes. Los procesadores de mensajes pueden encontrarse entre zonas de disponibilidad o regiones.

Si usas el valor predeterminado de false, puedes exceder tu cuota, ya que no se comparte el recuento de cada procesador de mensajes:

<Distributed>true</Distributed>

Para garantizar que los contadores se sincronicen y se actualicen en cada solicitud, configura <Distributed> y <Synchronous> como verdadero:

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>
Predeterminado: false
Presencia: Opcional
Tipo: Booleano

Elemento <Synchronous>

Configúralo como true para actualizar un contador de cuotas distribuidas de forma síncrona. Esto significa que la actualización del contador se realiza al mismo tiempo que se verifica la cuota en una solicitud a la API. Configúralo como true si es fundamental que no permitas ninguna llamada a la API cuando se supera la cuota.

Configúralo como false para actualizar el recuento de cuotas de forma asíncrona. Esto significa que es posible que algunas llamadas a la API que excedan la cuota se transferirán, dependiendo de cuándo se actualice de forma asíncrona el contador de cuota en el repositorio central. Sin embargo, no tendrás el impacto potencial de rendimiento asociado con las actualizaciones síncronas.

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

<Synchronous>false</Synchronous>
Predeterminado: false
Presencia: Opcional
Tipo: Booleano

Elemento <AsynchronousConfiguration>

Configura el intervalo de sincronización entre los contadores de cuota distribuida cuando el elemento de configuración de la política <Synchronous> no está presente o está presente y se establece en false.

Puedes sincronizar después de un período o un recuento de mensajes si usas los elementos secundarios SyncIntervalInSeconds o SyncMessageCount. Son mutuamente excluyentes. Por ejemplo:

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

o

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
Predeterminado: SyncIntervalInSeconds = 10 segundos
Presencia: Opcional; se ignora cuando <Synchronous> se configura como true.
Tipo:

Complejo

Elemento <AsynchronousConfiguration>/<SyncIntervalInSeconds>

Usa esto para anular el comportamiento predeterminado en el que las actualizaciones asíncronas se realizan después de un intervalo de 10 segundos.

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

El intervalo de sincronización debe ser mayor que 10 segundos, como se describe en el tema Límites.

Predeterminado: 10
Presencia: Opcional
Tipo:

Número entero

Elemento <AsymConfiguration>/<SyncMessageCount>

Especifica la cantidad de solicitudes en todos los procesadores de mensajes de Apigee entre las actualizaciones de cuota.

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

En este ejemplo, se especifica que el recuento de cuotas se actualiza cada 5 solicitudes en cada procesador de mensajes de Apigee Edge.

Predeterminado: N/A
Presencia: Opcional
Tipo:

Número entero

Elemento <Identifier>

Usa el elemento <Identifier> a fin de configurar la política para crear contadores únicos según una variable de flujo.

Puedes crear contadores únicos para las características que define una variable de flujo. Por ejemplo, puedes usar la dirección de correo electrónico del desarrollador para vincular una cuota a un desarrollador específico. Puedes usar diversas variables para identificar una cuota, ya sea que uses variables personalizadas o predefinidas, como las disponibles con la política de Verificar clave de API. Consulta también la Referencia de variables.

Si no usas este elemento, la política usa un solo contador que se aplica en la cuota.

Este elemento también se analiza en la siguiente publicación de la comunidad de Apigee: http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html.

<Identifier ref="verifyapikey.verify-api-key.client_id"/>
Predeterminado: No disponible
Presencia: Opcional
Tipo:

String

Atributos

Atributo Descripción Predeterminada Presencia
ref

Especifica una variable de flujo que identifica el recuento que se usará para la solicitud. El identificador puede ser un encabezado HTTP, un parámetro de búsqueda, un parámetro de formulario o un contenido del mensaje único para cada app, usuario de la app, desarrollador de la app, producto de la API, o cualquier otra característica.

El <Identifier> más usado para identificar de forma única las apps es el client_id. client_id es otro nombre para la clave de API, o clave de consumidor, que se genera para una app cuando se registra en una organización en Apigee Edge. Puedes usar este identificador si habilitaste la clave de API o las políticas de autorización de OAuth para tu API.

En algunas circunstancias, se debe recuperar la configuración de cuotas en la que no hay client_id disponible, como cuando no se implementa una política de seguridad. En esas situaciones, puedes usar la política de entidad de acceso para recuperar la configuración adecuada de los productos de API, luego extraer valores mediante ExtractVariables y, luego, usar la variable de contexto extraída en la política de cuotas. Para obtener más información, consulta Política de entidad de acceso.

No disponible Opcional

Elemento <MessageWeight>

Se usa para especificar el peso asignado a cada mensaje. Usa el peso de los mensajes para aumentar el impacto de los mensajes de solicitud que, por ejemplo, consumen más recursos de procesamiento que otros.

Por ejemplo, deseas contar los mensajes POST como el doble de “pesados” o costosos, en comparación con los mensajes GET. Por lo tanto, debes establecer MessageWeight en 2 para POST y 1 para GET. Incluso puedes establecer el MessageWeight en 0 para que la solicitud no afecte el contador. En este ejemplo, si la cuota es de 10 mensajes por minuto y el MessageWeight para las solicitudes POST es 2, la cuota permitirá 5 solicitudes POST en cualquier intervalo de 10 minutos. Se rechaza cualquier solicitud adicional, POST o GET, antes de que se restablezca el contador.

Se debe especificar un valor que represente MessageWeight por una variable de flujo y se puede extraer de los encabezados HTTP, los parámetros de búsqueda, una carga útil de la solicitud XML o JSON, o cualquier otra variable de flujo. Por ejemplo, lo configuras en un encabezado llamado weight:

<MessageWeight ref="message_weight"/>
Predeterminado: No disponible
Presencia: Opcional
Tipo:

Número entero

Variables de flujo

Las siguientes variables de flujo predefinidas se propagan automáticamente cuando se ejecuta una política de cuotas. Para obtener más información sobre las variables de flujo, consulta Referencia de las variables.

Variables Tipo Permisos Descripción
ratelimit.{policy_name}.allowed.count Long Solo lectura Muestra el recuento de cuotas permitido
ratelimit.{policy_name}.used.count Largo Solo lectura Muestra la cuota actual que se usó en un intervalo de cuota
ratelimit.{policy_name}.available.count Long Solo lectura Muestra el recuento de cuotas disponible en el intervalo de cuota
ratelimit.{policy_name}.exceed.count Long Solo lectura Muestra 1 después de que se excede la cuota.
ratelimit.{policy_name}.total.exceed.count Long Solo lectura Muestra 1 después de que se excede la cuota.
ratelimit.{policy_name}.expiry.time Long Solo lectura

Muestra la hora UTC en milisegundos, que determina cuándo vence la cuota y comienza el nuevo intervalo de cuota.

Cuando el tipo de política de cuota es rollingwindow, este valor no es válido porque el intervalo de cuota nunca vence.

ratelimit.{policy_name}.identifier String Solo lectura Muestra la referencia del identificador (cliente) adjunto a la política.
ratelimit.{policy_name}.class String Solo lectura Muestra la clase asociada con el identificador del cliente.
ratelimit.{policy_name}.class.allowed.count Long Solo lectura Muestra el recuento de cuotas permitido en la clase
ratelimit.{policy_name}.class.used.count Largo Solo lectura Muestra la cuota que se usa en una clase.
ratelimit.{policy_name}.class.available.count Long Solo lectura Muestra el recuento de cuotas disponible en la clase
ratelimit.{policy_name}.class.exceed.count Largo Solo lectura Muestra el recuento de solicitudes que exceden el límite en la clase en el intervalo de cuota actual
ratelimit.{policy_name}.class.total.exceed.count Long Solo lectura Muestra el recuento total de solicitudes que exceden el límite en la clase en todos los intervalos de cuota, por lo que es la suma de class.exceed.count para todos los intervalos de cuota.
ratelimit.{policy_name}.failed Booleano Solo lectura

Indica si la política falló (verdadero o falso).

Referencia de errores

En esta sección, se describen los códigos y mensajes de error que se muestran y las variables de fallas que establece Edge 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 de cuotas. Este elemento es obligatorio y se usa para especificar el intervalo de tiempo aplicable a la cuota. El intervalo de tiempo pueden ser 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 de cuotas. 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. No disponible

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 cuotas es menor que cero, la implementación del proxy de API falla.
InvalidAsynchronizeConfigurationForSynchronousQuota Si el valor del elemento <AsynchronousConfiguration> se establece en true en una política de cuotas, que también tiene una configuración asíncrona definida con el elemento <AsynchronousConfiguration>, fallará la implementación del proxy de la API.

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

Compara las políticas de cuotas, de protección contra aumentos de tráfico y de límites de frecuencia simultánea