Política de SpikeArrest

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

Consulta la documentación de Apigee Edge.

La política SpikeArrest protege contra los picos de tráfico con el elemento <Rate>. Este elemento limita el número de solicitudes procesadas por un proxy de API y enviadas a un backend, lo que protege contra los retrasos en el rendimiento y el tiempo de inactividad.

Esta política es una política estándar y se puede implementar en cualquier tipo de entorno. Para obtener información sobre los tipos de políticas y la disponibilidad de cada tipo de entorno, consulta Tipos de políticas.

Diferencia entre SpikeArrest y Quota

La política de cuotas configura el número de mensajes de solicitud que una aplicación cliente puede enviar a una API en el transcurso de una hora, un día, una semana o un mes. La política de cuotas aplica límites de consumo a las aplicaciones cliente manteniendo un contador distribuido que registra las solicitudes entrantes.

Usa Cuota para aplicar contratos empresariales o acuerdos de nivel de servicio con desarrolladores y partners, en lugar de para gestionar el tráfico operativo. Usa SpikeArrest para protegerte frente a picos repentinos en el tráfico de las APIs. Consulta también Comparación de las políticas de cuota y SpikeArrest.

Vídeos

En estos vídeos se explican algunos casos prácticos de esta política:

Por qué lo necesitas

Comparar la política de cuotas

Elemento <SpikeArrest>

Define la política de SpikeArrest.

Valor predeterminado	Consulta la pestaña Política predeterminada que aparece más abajo.
¿Es obligatorio?	Opcional
Tipo	Objeto Complex
Elemento principal	n/a
Elementos secundarios	<Identifier> <MessageWeight> <Rate> (obligatorio) <UseEffectiveCount>

Sintaxis

El elemento <SpikeArrest> utiliza la siguiente sintaxis:

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <DisplayName>display_name</DisplayName>
  <Properties/>
  <Identifier ref="flow_variable"/>
  <MessageWeight ref="flow_variable"/>
  <Rate ref="flow_variable">rate[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
</SpikeArrest>

Política predeterminada

En el siguiente ejemplo se muestran los ajustes predeterminados cuando añade una política de SpikeArrest a su flujo en la interfaz de usuario:

<SpikeArrest async="false" continueOnError="false" enabled="true" name="Spike-Arrest-1">
  <DisplayName>Spike Arrest-1</DisplayName>
  <Properties/>
  <Identifier ref="request.header.some-header-name"/>
  <MessageWeight ref="request.header.weight"/>
  <Rate>30ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

Este elemento tiene los siguientes atributos, que son comunes a todas las políticas:

Atributo	Predeterminado	¿Es obligatorio?	Descripción
name	N/A	Obligatorio	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.
continueOnError	falso	Opcional	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: Las reglas de errores solo se activan cuando hay un error (sobre continueOnError) Gestionar fallos en el flujo actual
enabled	true	Opcional	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.
async	falso	Obsoleto	Este atributo está obsoleto.

Ejemplos

En los siguientes ejemplos se muestran algunas de las formas en las que puedes usar la política SpikeArrest:

Ejemplo 1

En el siguiente ejemplo se establece la frecuencia en cinco por segundo:

<SpikeArrest name="SA-Static-5ps">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

Esta política de ejemplo permite un máximo de 5 solicitudes por segundo. Mediante el suavizado, se aplica un máximo de una solicitud por cada intervalo de 200 milisegundos (1000/5).

Ejemplo 2

En el siguiente ejemplo se establece la tarifa en 12 por minuto:

<SpikeArrest name="SA-Static-12pm">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Esta política de ejemplo permite un máximo de 12 solicitudes por minuto a un ritmo de una solicitud cada 5 segundos (60/12). Si hay más de una solicitud en el intervalo de 5 segundos, se permiten dichas solicitudes (sin suavizado) siempre que el número de solicitudes sea inferior al límite de frecuencia configurado de 12 por minuto.

Ejemplo 3

En el siguiente ejemplo, se restringen las solicitudes a 12 por minuto (se permite una solicitud cada cinco segundos, o 60/12):

<SpikeArrest name="SA-With-Dynamic-Weight-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request_specific_weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Además, el elemento <MessageWeight> acepta un valor personalizado (el encabezado weight) que ajusta los pesos de los mensajes de aplicaciones o clientes específicos. Esto proporciona un control adicional sobre la limitación de las entidades identificadas con el elemento <Identifier>.

Ejemplo 4

En el siguiente ejemplo, se indica a SpikeArrest que busque un valor de tiempo de ejecución definido mediante la solicitud que se transfiere como variable de flujo request.header.runtime_rate:

<SpikeArrest name="SA-From-Inbound-Header-1">
  <Rate ref="request.header.runtime_rate" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

El valor de la variable de flujo debe tener el formato intpm o intps.

Para probar este ejemplo, ejecuta una solicitud como la siguiente:

curl http://myorg-myenv.apigee.net/price -H 'runtime_rate:30ps'

Nota: Consulta el artículo ¿Cómo puedo usar productos de API para definir límites de SpikeArrest?, donde se explica cómo definir la frecuencia de SpikeArrest mediante variables personalizadas definidas en un producto de API.

Referencia de elemento secundario

En esta sección se describen los elementos secundarios de <SpikeArrest>.

<DisplayName>

Se usa junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de usuario de gestión con un nombre diferente que suene más natural.

El elemento <DisplayName> es común a todas las políticas.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional. Si omite <DisplayName>, se usará el valor del atributo name de la política.
Tipo	Cadena
Elemento principal	<PolicyElement>
Elementos secundarios	Ninguno

El elemento <DisplayName> utiliza la siguiente sintaxis:

Sintaxis

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Ejemplo

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

El elemento <DisplayName> no tiene atributos ni elementos secundarios.

<Identifier>

Te permite elegir cómo agrupar las solicitudes para que la política SpikeArrest se pueda aplicar en función del cliente. Por ejemplo, puedes agrupar las solicitudes por ID de desarrollador. En ese caso, las solicitudes de cada desarrollador se contabilizarán en su propia cuota de SpikeArrest y no en todas las solicitudes al proxy.

Úsalo junto con el elemento <MessageWeight> para tener un control más preciso sobre la limitación de solicitudes.

Si dejas el elemento <Identifier> vacío, se aplicará un límite de frecuencia a todas las solicitudes de ese proxy de API.

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

Sintaxis

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <Identifier ref="flow_variable"/>
</SpikeArrest>
        

Ejemplo 1

En el siguiente ejemplo se aplica la política SpikeArrest por ID de desarrollador:

<SpikeArrest name="Spike-Arrest-1">
  <Identifier ref="developer.id"/>
  <Rate>42pm</Rate/>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

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

Atributo	Descripción	Predeterminado	Presencia
ref	Identifica la variable por la que SpikeArrest agrupa las solicitudes entrantes. Puede usar cualquier variable de flujo para indicar un cliente único, como las disponibles con la política VerifyAPIKey. También puedes definir variables personalizadas con la política JavaScript o la política AssignMessage.	n/a	Obligatorio

Este elemento también se explica en esta publicación de la comunidad de Apigee.

<MessageWeight>

Especifica la ponderación definida para cada mensaje. El peso del mensaje modifica el impacto de una sola solicitud en el cálculo de la tasa de SpikeArrest. El peso del mensaje puede ser cualquier variable de flujo, como un encabezado HTTP, un parámetro de consulta, un parámetro de formulario o el contenido del cuerpo del mensaje. También puedes usar variables personalizadas con la política de JavaScript o la política AssignMessage.

Úsala junto con <Identifier> para limitar aún más las solicitudes de clientes o aplicaciones específicos.

Por ejemplo, si el <Rate> de SpikeArrest es 10pm y una aplicación envía solicitudes con un peso de 2, solo se permitirán cinco mensajes por minuto de ese cliente, ya que cada solicitud cuenta como 2.

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

Sintaxis

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <MessageWeight ref="flow_variable"/>
</SpikeArrest>

Ejemplo 1

En el siguiente ejemplo, se restringen las solicitudes a 12 por minuto (se permite una solicitud cada cinco segundos, o 60/12):

<SpikeArrest name="SA-With-Dynamic-Weight-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request_specific_weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

En este ejemplo, <MessageWeight> acepta un valor personalizado (el encabezado weight de la solicitud) que ajusta los pesos de los mensajes de clientes específicos. Esto proporciona un control adicional sobre la limitación de las entidades identificadas con el elemento <Identifier>.

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

Atributo	Descripción	Presencia	Predeterminado
ref	Identifica la variable de flujo que contiene el peso del mensaje del cliente específico. Puede ser cualquier variable de flujo, como un parámetro de consulta HTTP, un encabezado o el contenido del cuerpo de un mensaje. Para obtener más información, consulta la referencia de variables de flujo. También puedes definir variables personalizadas con la política JavaScript o la política AssignMessage.	Obligatorio	N/A

<Rate>

Especifica la frecuencia con la que se limitan los picos (o ráfagas) de tráfico. Para ello, se define el número de solicitudes que se permiten en intervalos de un minuto o de un segundo. También puede usar este elemento junto con <Identifier> y <MessageWeight> para limitar el tráfico de forma fluida en el tiempo de ejecución aceptando valores del cliente. Usa el elemento <UseEffectiveCount> para definir el algoritmo de limitación de frecuencia que usa la política.

Nota: No se admite el uso de <UseEffectiveCount> con un valor o false en ninguna organización de Apigee ni en organizaciones híbridas de Apigee que ejecuten cargas de trabajo de producción. Para obtener más información, consulta <UseEffectiveCount>

.

Consulta la sección SpikeArrest de la página Límites para ver los límites de frecuencia máximos que puedes especificar.

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

Sintaxis

Puedes especificar las tarifas de una de las siguientes formas:

• Un precio estático que especifiques como cuerpo del elemento <Rate>
• Valor de una variable, que puede transferir el cliente. Identifica el nombre de la variable de flujo mediante el atributo ref.

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <Rate ref="flow_variable">rate[pm|ps]</Rate>
</SpikeArrest>

Los valores de la tarifa válidos (definidos como valor de una variable o en el cuerpo del elemento) deben ajustarse al siguiente formato:

• intps (número de solicitudes por segundo, suavizado en intervalos de milisegundos)
• intpm (número de solicitudes por minuto, suavizado en intervalos de segundos)

El valor de int debe ser un número entero positivo distinto de cero.

Ejemplo 1

En el siguiente ejemplo, se establece la tarifa en cinco solicitudes por segundo:

<SpikeArrest name="SA-Static-5ps">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

La política suaviza la tasa a una solicitud permitida cada 200 milisegundos (1000/5).

Ejemplo 2

En el siguiente ejemplo, se establece la frecuencia en 12 solicitudes por minuto:

<SpikeArrest name="SA-Static-12pm">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Esta política de ejemplo suaviza la frecuencia a una solicitud permitida cada cinco segundos (60/12).

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

Atributo	Descripción	Presencia	Predeterminado
ref	Identifica una variable de flujo que especifica la tarifa. Puede ser cualquier variable de flujo, como un parámetro de consulta HTTP, un encabezado o el contenido del cuerpo de un mensaje, o un valor, como un KVM. Para obtener más información, consulta la referencia de variables de flujo. También puedes usar variables personalizadas con la política de JavaScript o la política AssignMessage. Si defines tanto ref como el cuerpo de este elemento, se aplicará el valor de ref y tendrá prioridad cuando se defina la variable de flujo en la solicitud. (Lo contrario ocurre cuando la variable identificada en ref no se define en la solicitud). Por ejemplo: <Rate ref="request.header.custom_rate">1pm</Rate> En este ejemplo, si el cliente no envía un encabezado custom_rate, la frecuencia del proxy de la API es de 1 solicitud por minuto para todos los clientes. Si el cliente envía un encabezado custom_rate, el límite de frecuencia será de 10 solicitudes por segundo para todos los clientes del proxy hasta que se envíe una solicitud sin el encabezado custom_rate. Puede usar <Identifier> para agrupar solicitudes y aplicar tarifas personalizadas a diferentes tipos de clientes. Si especifica un valor para ref, pero no define la tarifa en el cuerpo del elemento <Rate> y el cliente no transmite ningún valor, la política SpikeArrest genera un error.	Opcional	n/a

<UseEffectiveCount>

Este elemento te permite elegir entre distintos algoritmos de supresión de picos asignando el valor true o false, como se explica a continuación:

true

Si se le asigna el valor true, SpikeArrest se distribuye en una región. Esto significa que los recuentos de solicitudes se sincronizan entre los procesadores de mensajes (MPs) de una región. Además, se emplea un algoritmo de limitación de frecuencia de "ventana deslizante". Este algoritmo proporciona un comportamiento coherente del límite de frecuencia y no "suaviza" el número de solicitudes entrantes que se pueden enviar al backend. Si se envía una ráfaga de solicitudes en un intervalo de tiempo breve, se permiten siempre que no superen el límite de frecuencia configurado, tal como se define en el elemento <Rate>. Por ejemplo:

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request.header.weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

false (valor predeterminado)

Nota: Aunque el valor predeterminado es false, las organizaciones de Apigee deben asignar el valor true a este elemento.

El suavizado de la frecuencia no se admite en las organizaciones de Apigee.

Si se define como false (el valor predeterminado), la política SpikeArrest usa un algoritmo de "cubo de tokens" que suaviza los picos de tráfico dividiendo el límite de frecuencia que especifiques en intervalos más pequeños. Un inconveniente de este enfoque es que se pueden denegar varias solicitudes legítimas que se reciban en un breve intervalo de tiempo.

Por ejemplo, supongamos que introduces una frecuencia de 30 pm (30 solicitudes por minuto). Durante las pruebas, puede que pienses que puedes enviar 30 solicitudes en 1 segundo, siempre que se envíen en un minuto. Sin embargo, no es así como la política aplica el ajuste. Si lo piensas, 30 solicitudes en un periodo de 1 segundo podrían considerarse un minipico en algunos entornos.

• Las tarifas por minuto se suavizan para que se permitan solicitudes completas en intervalos de segundos.
  

  Por ejemplo, 30pm se suaviza de la siguiente manera:
  60 segundos (1 minuto) / 30pm = intervalos de 2 segundos, o 1 solicitud permitida cada 2 segundos. Si se envía una segunda solicitud en un plazo de 2 segundos, se producirá un error. Además, si se envía una solicitud más, se producirá un error.

• Las tarifas por segundo se suavizan para obtener el número total de solicitudes permitidas en intervalos de milisegundos.

  Por ejemplo, 10ps se suaviza de la siguiente manera:
  1000 milisegundos (1 segundo) / 10ps = intervalos de 100 milisegundos, o 1 solicitud permitida cada 100 milisegundos. Si se envía una segunda solicitud en un plazo de 100 ms, se producirá un error. Además, se producirá un error si se envía una undécima solicitud en un segundo.

Nota: En el suavizado de la frecuencia, el número de solicitudes siempre es un número entero mayor que cero. El suavizado nunca implica calcular fracciones de solicitudes.

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

En la siguiente tabla se describen los atributos del elemento <UseEffectiveCount>:

Atributo	Descripción	Predeterminado	Presencia
ref	Identifica la variable que contiene el valor de <UseEffectiveCount>. Puede ser cualquier variable de flujo, como un parámetro de consulta HTTP, un encabezado o el contenido del cuerpo de un mensaje. Para obtener más información, consulta la referencia de variables de flujo. También puedes definir variables personalizadas con la política JavaScript o la política AssignMessage.	n/a	Opcional

Variables de flujo

Cuando se ejecuta una política de SpikeArrest, se rellena la siguiente variable de flujo:

Variable	Tipo	Permiso	Descripción
ratelimit.policy_name.failed	Booleano	Solo lectura	Indica si la política ha fallado (true o false).

Para obtener más información, consulta la referencia de variables de flujo.

Referencia de errores

En esta sección se describen los códigos de error y los mensajes de error que se devuelven, así como las variables de error que define Apigee cuando esta política activa un error. Es importante que conozcas esta información si vas a desarrollar reglas de errores para gestionarlos. Para obtener más información, consulta Qué debes saber sobre los errores de las políticas y Cómo gestionar los errores.

Errores de tiempo de ejecución

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

Nota: ¿Necesitas ayuda para resolver un error? En la columna Solución, haz clic en para obtener información detallada sobre cómo solucionar el problema.

Código de fallo	Estado de HTTP	Causa	Solucionar
policies.ratelimit.FailedToResolveSpikeArrestRate	500	Este error se produce si la referencia a la variable que contiene el ajuste de la tarifa del elemento <Rate> no se puede resolver en un valor de la política SpikeArrest. Este elemento es obligatorio y se usa para especificar la tasa de supresión de picos en forma de intpm o intps.
policies.ratelimit.InvalidMessageWeight	500	Este error se produce si el valor especificado para el elemento <MessageWeight> a través de una variable de flujo no es válido (un valor no entero).
policies.ratelimit.SpikeArrestViolation	429	Se ha superado el límite de frecuencia.

Errores de implementación

Estos errores pueden producirse al implementar un proxy que contenga esta política.

Nota: ¿Necesitas ayuda para resolver un error? Haz clic en en la columna Solución para obtener información detallada sobre cómo solucionar el problema.

Nombre del error	Causa	Solucionar
InvalidAllowedRate	Si la tasa de detención de picos especificada en el elemento <Rate> de la política SpikeArrest no es un número entero o si la tasa no tiene ps o pm como sufijo, se producirá un error al implementar el proxy de API.

Variables de error

Estas variables se definen cuando se produce un error de tiempo de ejecución. Para obtener más información, consulta el artículo Información sobre los errores de las políticas.

Variables	Dónde	Ejemplo
fault.name="fault_name"	fault_name es el nombre del error, tal como se indica en la tabla Errores de tiempo de ejecución de arriba. El nombre del error es la última parte del código de error.	fault.name Matches "SpikeArrestViolation"
ratelimit.policy_name.failed	policy_name es el nombre de la política especificado por el usuario que ha provocado el error.	ratelimit.SA-SpikeArrestPolicy.failed = true

Ejemplo de respuesta de error

A continuación se muestra un ejemplo de respuesta de error:

Nota: Para gestionar los errores, la práctica recomendada es detectar la parte errorcode de la respuesta de error. No te fíes del texto de la faultstring, ya que podría cambiar.

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.SpikeArrestViolation"
      },
      "faultstring":"Spike arrest violation. Allowed rate : 10ps"
   }
}

Regla de error de ejemplo

A continuación se muestra un ejemplo de regla de error para gestionar un error SpikeArrestViolation:

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

El código de estado HTTP actual para superar un límite de frecuencia definido por una política de cuota o SpikeArrest es 429 (Demasiadas solicitudes).

Esquemas

Cada tipo de política se define mediante un esquema XML (.xsd). Puedes consultar los esquemas de políticas en GitHub.

Temas relacionados

• Política de cuotas: política de cuotas para limitar el tráfico de clientes individuales.
• Límite de frecuencia para ver una descripción general de la limitación de frecuencia
• Comparación de las políticas de cuota y SpikeArrest