Política de SpikeArrest

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

Consulta la documentación de Apigee Edge.

La política de SpikeArrest protege contra aumentos repentinos de tráfico con el elemento <Rate>. Este elemento regula la cantidad de solicitudes que procesa un proxy de API y se envía a un backend, lo que protege contra los retrasos de rendimiento y el tiempo de inactividad.

Esta 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 con cada tipo de entorno, consulta Tipos de políticas.

Diferencia entre SpikeArrest y la cuota

La política de cuotas configura la cantidad de mensajes de solicitud que una app cliente puede enviar a una API en el transcurso de una hora, día, semana o mes. La política de cuotas aplica límites de consumo a las apps cliente manteniendo un recuento distribuido que aumenta las solicitudes entrantes.

Usa la cuota para aplicar contratos comerciales o ANS con desarrolladores y socios, en lugar de hacerlo para la administración del tráfico operativo. Usa SpikeArrest para protegerte contra los aumentos repentinos en el tráfico de API. Consulta también Compara políticas de cuota y SpikeArrest.

Videos

En estos videos, se analizan casos de uso de esta política:

Por qué la necesitas

Compara políticas de cuotas

Elemento <SpikeArrest>

Define la política de Spike Arrest

Valor predeterminado	Consulta la pestaña Política predeterminada, a continuación
¿Es obligatorio?	Opcional
Tipo	Objeto complejo
Elemento principal	No disponible
Elementos secundarios	<Identifier> <MessageWeight> <Rate> (obligatorio) <UseEffectiveCount>

Sintaxis

El elemento <SpikeArrest> usa 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 muestra la configuración predeterminada cuando agregas una política de SpikeArrest a tu flujo en la IU:

<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	Predeterminada	(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. 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.
continueOnError	falso	Opcional	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. También consulta: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual
enabled	true	Opcional	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 conectada a un flujo.
async	falso	Obsoleta	Este atributo dejó de estar disponible.

Ejemplos

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

Ejemplo 1

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

<SpikeArrest name="Spike-Arrest-1">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

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

Ejemplo 2

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

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Esta política de muestra permite un máximo de 12 solicitudes por minuto a una velocidad de una solicitud por intervalo de 5 segundos (60/12). Si hay más de una solicitud en el intervalo de 5 segundos, se permiten estas solicitudes (sin suavizado) siempre que la cantidad de solicitudes sea menor que el límite de frecuencia configurado de 12 por minuto.

Ejemplo 3

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

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

Además, el elemento <MessageWeight> acepta un valor personalizado (el encabezado weight) que ajusta el peso del mensaje para apps o clientes específicos. Esto proporciona un control adicional sobre el límite para las entidades que se identifican con el elemento <Identifier>.

Ejemplo 4

El siguiente ejemplo le indica a SpikeArrest que busque un valor de entorno de ejecución configurado a través de la solicitud que se pasa como la variable de flujo request.header.runtime_rate:

<SpikeArrest name="Spike-Arrest-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'

Sugerencia: Registro de salida ¿Cómo puedo usar los productos de API para establecer límites de Spike Arrest? que explica cómo establecer la frecuencia de SpikeArrest con variables personalizadas configuradas en un producto de API.

Referencia del elemento secundario

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

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

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

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

El elemento <DisplayName> usa 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 se pueda aplicar la política de SpikeArrest según el cliente. Por ejemplo, puedes agrupar solicitudes por ID de desarrollador, en cuyo caso las solicitudes de cada desarrollador se contarán en su propia frecuencia de SpikeArrest y no todas las solicitudes al proxy.

Instala junto con el elemento <MessageWeight> para obtener un control más preciso sobre la regulación de solicitudes.

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

Valor predeterminado	n/a
¿Es obligatorio?	Opcional
Tipo	String
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	Presence
ref	Identifica la variable mediante la cual SpikeArrest agrupa las solicitudes entrantes. Puedes usar cualquier variable de flujo para indicar un cliente único, como los disponibles con la política VerifyAPIKey. También puedes usar variables personalizadas mediante la política de JavaScript o la Política de AssignMessage.	n/a	Obligatorio

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

<MessageWeight>

Especifica la ponderación definida para cada mensaje. El peso de los mensajes modifica el impacto de una solicitud única 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 contenido del cuerpo del mensaje. También puedes usar variables personalizadas mediante la política de JavaScript o la Política de AssignMessage.

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

Por ejemplo, si el SpikeArrest <Rate> es 10pm y una app envía solicitudes con una ponderación de 2, solo se permiten cinco mensajes por minuto, porque 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 (una solicitud permitida cada cinco segundos o 60/12):

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

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

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

Atributo	Descripción	Presence	Predeterminado
ref	Identifica la variable de flujo que contiene la ponderación del mensaje para el cliente específico. Puede ser cualquier variable de flujo, como un parámetro de búsqueda HTTP, un encabezado o contenido del cuerpo del mensaje. Para obtener más información, consulta Referencia de variables de flujo. También puedes usar variables personalizadas mediante la política de JavaScript o la Política de AssignMessage.	Obligatorio	N/A

<Rate>

Especifica la frecuencia a la que se deben limitar los aumentos repentinos de tráfico (o aumentos de actividad) mediante la configuración de la cantidad de solicitudes permitidas en intervalos por minuto o por segundo. También puedes usar este elemento junto con <Identifier> y <MessageWeight> a fin de limitar el tráfico en el entorno de ejecución con facilidad. Para ello, debes aceptar valores del cliente. Usa el elemento <UseEffectiveCount> para establecer el algoritmo de límite de frecuencia que usa la política.

Nota: Consulta la sección de SpikeArrest de la página Límites para conocer 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 tasas de una de las siguientes maneras:

• Una tasa estática que especificas como cuerpo del elemento <Rate>
• Un valor variable, que el cliente puede pasar. Identificar el nombre de la variable de flujo con 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 las tarifas válidas (definidas como valores de variables o en el cuerpo del elemento) deben cumplir con el siguiente formato:

• intps (cantidad de solicitudes por segundo, se suman en intervalos de milisegundos)
• intpm (cantidad de solicitudes por minuto, se suman en intervalos de segundos)

El valor de int debe ser un número entero positivo que no sea cero.

Ejemplo 1

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

<SpikeArrest name="Spike-Arrest-1">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

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

Ejemplo 2

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

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

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

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

Atributo	Descripción	Presence	Predeterminado
ref	Identifica una variable de flujo que especifica la frecuencia. Puede ser cualquier variable de flujo, como un parámetro de búsqueda HTTP, un encabezado o contenido del cuerpo del mensaje, o un valor, como una KVM. Para obtener más información, consulta Referencia de variables de flujo. También puedes usar variables personalizadas mediante la política de JavaScript o la Política de AssignMessage. Si defines ref y el cuerpo de este elemento, se aplicará el valor de ref y tendrá prioridad cuando la variable de flujo se establezca en la solicitud. (La inversa es verdadera cuando la variable identificada en ref no se establece en la solicitud). Por ejemplo: <Rate ref="request.header.custom_rate">1pm</Rate> En este ejemplo, si el cliente no transmite un encabezado custom_rate, la frecuencia del proxy de API es de 1 solicitud por minuto para todos los clientes. Si el cliente pasa un encabezado custom_rate, el límite de frecuencia se convierte en 10 solicitudes por segundo para todos los clientes del proxy, hasta que se envía una solicitud sin el encabezado custom_rate. Puedes usar <Identifier> para agrupar solicitudes a fin de aplicar frecuecias personalizadas para diferentes tipos de clientes. Si especificas un valor para ref, pero no estableces la velocidad en el cuerpo del elemento <Rate> y el cliente no pasa un valor, la política de Spike Arrest muestra un error.	Opcional	n/a

<UseEffectiveCount>

Este elemento te permite elegir entre algoritmos de protección contra aumentos de tráfico distintos mediante la configuración del valor en true o false, como se explica a continuación:

true

Si se configura como true, SpikeArrest se distribuye en una región. Eso significa que los recuentos de solicitudes se sincronizan entre los procesadores de mensajes (MP) de una región. Además, se emplea un algoritmo de límite de frecuencia de “ventana deslizante”. Este algoritmo proporciona un comportamiento de límite de frecuencia coherente y no “suaviza” la cantidad de solicitudes entrantes que se pueden enviar al backend. Si se envía un pico de actividad de solicitudes en un intervalo de tiempo corto, se permitirán siempre que no excedan el límite de frecuencia configurado, como se establece 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 (predeterminado)

Si se configura como false (la opción predeterminada), la política SpikeArrest usa un algoritmo de "bucket de tokens" que disminuye los aumentos de tráfico mediante la división del límite de frecuencia que especifiques en intervalos más pequeños. Una desventaja de este enfoque es que posiblemente se deniegan varias solicitudes legítimas que ingresen en un intervalo de tiempo corto.

Por ejemplo, supongamos que ingresa una frecuencia de 30 pm (30 solicitudes por minuto). En las pruebas, podrías pensar que podrías enviar 30 solicitudes en 1 segundo, siempre que estén dentro de un minuto. Pero esa no es la forma en que la política aplica la configuración. Si lo piensas, 30 solicitudes en un período de 1 segundo se podrían considerar un pequeño aumento en algunos entornos.

• Las tarifas por minuto se suman a las solicitudes completas permitidas en intervalos de segundos.
  

  Por ejemplo, 30 pm se mitigan de la siguiente manera:
  60 segundos (1 minuto) / 30 pm = intervalos de 2 segundos o 1 solicitud permitida cada 2 segundos. Una segunda solicitud dentro de 2 segundos fallará. Además, fallará la solicitud 31 en un minuto.

• Las tarifas por segundo se suman a las solicitudes completas permitidas en intervalos de milisegundos.

  Por ejemplo, 10 ps se suavizan de la siguiente manera:
  1,000 milisegundos (1 segundo) / 10 ms = 100 milisegundos o 1 solicitud permitida cada 100 milisegundos. Una segunda solicitud dentro de los 100 ms fallarán. Además, fallará la solicitud 11 en un segundo error.

Nota: En el suavizado de la frecuencia, la cantidad de solicitudes es siempre un número entero superior a cero. La mitigación 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	Presence
ref	Identifica la variable que contiene el valor de <UseEffectiveCount>. Puede ser cualquier variable de flujo, como un parámetro de búsqueda HTTP, un encabezado o contenido del cuerpo del mensaje. Para obtener más información, consulta Referencia de variables de flujo. También puedes usar variables personalizadas mediante la política de JavaScript o la Política de AssignMessage.	n/a	Opcional

Variables de flujo

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

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

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

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.

Sugerencia: ¿Necesitas ayuda para resolver un error? Haz clic en en la columna Corregir para obtener información detallada sobre la solución de problemas.

Código de falla	Estado de HTTP	Causa	Corregir
policies.ratelimit.FailedToResolveSpikeArrestRate	500	Este error se produce si la referencia a la variable que contiene la configuración de tarifa dentro del elemento <Rate> no se puede resolver en un valor dentro de la política SpikeArrest. Este elemento es obligatorio y se usa para especificar el índice de protección contra aumentos de tráfico en el formato 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 número no entero).
policies.ratelimit.SpikeArrestViolation	429	Se superó el límite de frecuencia.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Sugerencia: ¿Necesitas ayuda para resolver un error? Haz clic en en la columna Corregir para obtener información detallada sobre la solución de problemas.

Nombre del error	Causa	Corregir
InvalidAllowedRate	Si la tasa de interrupción de aumento de tráfico 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, la implementación del proxy de API falla.

Variables con fallas

Estas variables se configuran cuando se genera un error de entorno de ejecución. 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 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 "SpikeArrestViolation"
ratelimit.policy_name.failed	policy_name es el nombre especificado por el usuario de la política que generó la falla.	ratelimit.SA-SpikeArrestPolicy.failed = true

Ejemplo de respuesta de error

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

Nota: Para controlar errores, se recomienda capturar la parte errorcode de la respuesta de error. No dependas del texto en la faultstring, ya que podría cambiar.

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

Ejemplo de regla de falla

A continuación, se muestra un ejemplo de regla de falla para manejar una falla de 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 establecido por una política de cuota o SpikeArrest es 429 (muchas solicitudes). Para cambiar el código de estado HTTP a 500 (error interno del servidor), configura la propiedad features.isHTTPStatusTooManyRequestEnabled como false mediante la API Actualizar propiedades de la organización.

Nota: Cuando actualices las propiedades, debes pasar todas las propiedades existentes a la API, incluso si no se cambiaron. Si dejas propiedades fuera de la carga útil a la llamada a la API Actualizar las propiedades de la organización, las propiedades se quitan. Para obtener la lista actual de propiedades del entorno, usa la API de Obtener organización.

Si intentas configurar una propiedad, pero el valor de la propiedad actualizado no se muestra en la carga útil de la respuesta, significa que un usuario con la función sysadmin debe configurarlo. Comunícate con el equipo de asistencia de Apigee para cambiar un valor de propiedad que requiere la función sysadmin).

Por ejemplo:

curl -u email:password -X POST -H "Content-type:application/xml" http://apigee.googleapis.com/v1/organizations/myorg -d \
"<Organization type="trial" name="MyOrganization">
    <Properties>
        <Property name="features.isHTTPStatusTooManyRequestEnabled">true</Property>
        . . .
    </Properties>
</Organization>"

Esquemas

Un esquema XML (.xsd) define cada tipo de política. Como referencia, los esquemas de políticas están disponibles en GitHub.

Temas relacionados

• Política de cuotas: Política de cuotas, para limitar el tráfico en clientes individuales
• Límite de frecuencia para una descripción general sobre el límite de frecuencia
• Compara políticas de cuota y de SpikeArrest