Política de SpikeArrest

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

Ícono de Spike Arrest de la IU de Edge

La política de Spike Arrest protege contra los aumentos 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.

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 aumento de aumento repentino a tu flujo en la IU de Edge:

<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>true</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 Si la estableces como "false", muestra un error cuando falla una política. Este es el comportamiento previsto para la mayoría de las políticas. Si su valor es "true", la ejecución del flujo continuará incluso después de que falle la política.
enabled true Opcional Si estableces la política como "true", la aplicarás. Si la estableces como "false", se desactivará la política. La política no se aplicará, incluso si permanece conectada a un flujo.
async   falso Funciones obsoletas Este atributo dejó de estar disponible.

Ejemplos

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

Ejemplo 1

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

<SpikeArrest name="Spike-Arrest-1">
  <Rate>5ps</Rate>
</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 en 12 por minuto:

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

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

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

En el siguiente ejemplo, se indica a Spike Arrest que busque un valor de entorno de ejecución establecido 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" />
</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'

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 la política de Spike Arrest se pueda aplicar según el cliente. Por ejemplo, puedes agrupar solicitudes por ID de desarrollador, en cuyo caso las solicitudes de cada desarrollador se tendrán en cuenta para su propia tasa de detección de aumentos repentinos 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 Ninguna

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 de aumento repentino por ID de desarrollador:

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

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

Atributo Descripción Predeterminada Presencia
ref Identifica la variable mediante la cual Spike Arrest 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 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.

<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 aumento de aumento repentino. 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 aumento repentino <Rate> es 10pm y una app envía solicitudes con un peso de 2, solo se permiten cinco mensajes por minuto de ese cliente, ya que cada solicitud cuenta como 2.

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Número entero
Elemento principal <SpikeArrest>
Elementos secundarios Ninguna

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" />
</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 Predeterminada
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 No disponible

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

Valor predeterminado N/A
¿Es obligatorio? Obligatorio
Tipo Número entero
Elemento principal <SpikeArrest>
Elementos secundarios Ninguna

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>
</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>
</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 Predeterminada
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 pasa un encabezado "custom_rate", la tarifa para el 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 es de 10 solicitudes por segundo para todos los clientes en el proxy, hasta que se envíe una solicitud sin el encabezado “custom_rate”.

Puedes usar <Identifier> a fin de agrupar las solicitudes y aplicar tarifas 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>

Distribuye los recuentos de aumento de aumento repentinos en los procesadores de mensajes (MP) cuando se usan grupos de ajuste de escala automático.

Sintaxis

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
</SpikeArrest>

Ejemplo 1

En el siguiente ejemplo, se configura <UseEffectiveCount> como verdadero:

<SpikeArrest name='Spike-Arrest-1'>
  <Rate>40ps</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

El elemento <UseEffectiveCount> es opcional. El valor predeterminado es false cuando se omite el elemento de tu política de Spike Arrest.

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

El efecto de <UseEffectiveCount> depende de su valor:

  • true: El límite de la tasa de aumento repentino de un miembro del Parlamento es el <Rate> dividido por la cantidad actual de MPS en el mismo grupo. El límite agregado es el valor de <Rate>. Cuando se agregan (o se quitan miembros) de forma dinámica, sus límites individuales de frecuencia de aumento aumentarán (o disminuirán), pero el límite agregado seguirá siendo el mismo.
  • false (valor predeterminado si se omite): El límite de tasa de aumento repentino de cada MP es simplemente el valor de su <Rate>. El límite agregado es la suma de las tarifas de todos los miembros del Parlamento. Cuando se agreguen (o se quiten) miembros, sus límites individuales de tasa de aumento seguirán siendo los mismos, pero el límite agregado aumentará (o disminuirá).

En la siguiente tabla, se muestra el efecto de <UseEffectiveCount> en el límite de frecuencia efectivo de cada MP:

Valor de <UseEffectiveCount>
false false false true true true
Cant. de miembros del Parlamento 8 4 2 8 4 2
Valor de <Rate> 10 10 10 40 40 40
Tasa efectiva por MP 10 10 10 5 10 20
Límite agregado 80 40 20 40* 40* 40*
* Igual que <Rate>.

En este ejemplo, observa que cuando la cantidad de MP se reduce de 4 a 2, y <UseEffectiveCount> es false, la tasa efectiva por MP se mantiene igual (en 10). Sin embargo, cuando <UseEffectiveCount> es true, la tasa efectiva por MP pasa de 10 a 20 cuando la cantidad de MP se reduce de 4 a 2.

Variables de flujo

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

Variable Tipo Permisos 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 y mensajes de error que se muestran, así como 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.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 de protección contra aumentos de tráfico. 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.

Nombre del error Causa Corregir
InvalidAllowedRate Si la tasa de protección contra aumentos de tráfico especificada en el elemento <Rate> de la política no es un número entero o si la tasa no tiene ps ni 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:

{  
   "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 fallas para controlar una falla 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 el límite de frecuencia establecido por una política de detección de aumentos repentinos o cuotas es 429 (Demasiadas solicitudes). Para cambiar el código de estado HTTP a 500 (Error interno del servidor), establece la propiedad features.isHTTPStatusTooManyRequestEnabled en false con la API Actualizar propiedades de la organización.

Por ejemplo:

curl -u email:password -X POST -H "Content-type:application/xml" http://api.enterprise.apigee.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