Política de cuotas

Estás viendo la documentación de Apigee Edge.
Ve a 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:

Ejemplos

En estos ejemplos de código de política, se muestra cómo comenzar y finalizar los períodos de cuota:

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

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

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

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

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

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

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

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

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

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

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 día o el último día de ese período; no se permite ninguna otra área de solicitudes hasta que el contador de cuotas se restablece automáticamente al final del intervalo de tiempo especificado o hasta que la Cuota se haya restablecer con la opción Restablecer cuota política.

Una variación de la cuota llamada SpikeArrest evita aumentos repentinos de tráfico (o aumentos de actividad) que pueden causada por un aumento repentino en el uso, clientes con errores o ataques maliciosos. Para ver más información sobre SpikeArrest, consulte la política de Spike Arrest.

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:

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.

Usar la misma política de cuotas en más de un lugar en un flujo de proxy de API, que puede causa involuntariamente que la cuota se acabe más rápido de lo esperado, es un antipatrón descrito en 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.

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

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>

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.

Atributos

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>. Edge usará el valor del campo de de flujo para seleccionar una de las etiquetas secundarias <Allow> y determinar las etiquetas recuento de la política. Edge hace coincidir el valor de la variable de flujo con 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.

Atributos

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 cuota llamados de peak_time y off_peak_time.

Atributos

Elemento <Interval>

Se usa para especificar un número entero (por ejemplo, 1, 2, 5, 60, etc.) que se sincronizará con el TimeUnit que especifiques (minuto, hora, día, semana o mes) para determinar una hora 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>

Atributos

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>

Atributos

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>

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>

Elemento <Synchronous>

Configúralo como true para actualizar un contador de cuotas distribuidas de forma síncrona. Esta 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>

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>

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.

Elemento <AsynchronousConfiguration>/<SyncMessageCount>

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

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

En este ejemplo, se especifica que el recuento de la cuota se actualiza cada 5 solicitudes en cada instancia de Apigee. Procesador de mensajes perimetral

Elemento <Identifier>

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

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

Atributos

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, quieres que los mensajes POST sean el doble de “pesados” o costoso, como GET mensajes nuevos. Por lo tanto, establece MessageWeight en 2 para una POST y en 1 para una GET. Incluso puedes establecer el MessageWeight en 0 para que la solicitud no tenga que afectará el contador. En este ejemplo, si la cuota es de 10 mensajes por minuto y el MessageWeight para las solicitudes POST es 2, entonces la cuota permite 5 solicitudes POST en cualquier intervalo de 10 minutos. Cualquier solicitud adicional, ya sea POST o GET, antes de que se rechacen los restablecimientos del 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"/>

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.

Referencia de errores

En esta sección, se describen los códigos y mensajes de error que se muestran, y las variables de falla 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.

Errores en la implementación

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.

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

SpikeArrest política

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