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. No todos los usuarios necesitan conocer los tipos de políticas y el 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	n/a
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>

This element has the following attributes that are common to all policies:

Attribute	Default	Required?	Description
name	N/A	Required	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError	false	Optional	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow
enabled	true	Optional	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async	false	Deprecated	This attribute is deprecated.

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	Ninguna

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	None

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	None

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	None

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

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

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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Fault code	HTTP status	Cause	Fix
policies.ratelimit.FailedToResolveSpikeArrestRate	500	This error occurs if the reference to the variable containing the rate setting within the <Rate> element cannot be resolved to a value within the SpikeArrest policy. This element is mandatory and used to specify the spike arrest rate in the form of intpm or intps.
policies.ratelimit.InvalidMessageWeight	500	This error occurs if the value specified for the <MessageWeight> element through a flow variable is invalid (a non-integer value).
policies.ratelimit.SpikeArrestViolation	429	The rate limit is exceeded.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Error name	Cause	Fix
InvalidAllowedRate	If the spike arrest rate specified in the <Rate> element of the SpikeArrest policy is not an integer or if the rate does not have ps or pm as a suffix, then the deployment of the API proxy fails.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "SpikeArrestViolation"
ratelimit.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	ratelimit.SA-SpikeArrestPolicy.failed = true

Example error response

Shown below is an example error response:

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

Example fault rule

Shown below is an example fault rule to handle a SpikeArrestViolation fault:

<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