Configura el enrutamiento, los límites y los reintentos de la cola

Cloud Tasks te permite administrar la ejecución de tareas definiendo el enrutamiento, los límites de frecuencia de envío y el comportamiento de reintentos a nivel de la cola. Puedes establecer estos parámetros de configuración cuando crees una cola o actualices una existente.

Tanto gcloud tasks queues create como gcloud tasks queues update usan las mismas marcas para establecer los parámetros de la cola, mientras que gcloud tasks queues update también admite marcas --clear-* para restablecer los parámetros a sus valores predeterminados.

Configurar la autenticación a nivel de la cola anula la autenticación a nivel de la tarea. Para obtener más información, consulta Usa tareas de destino HTTP con tokens de autenticación.

Configura el enrutamiento a nivel de la cola

La configuración del enrutamiento a nivel de la cola anula el enrutamiento establecido a nivel de la tarea. Esto es útil si deseas usar Cloud Tasks como un búfer frente a tu servicio de destino o si necesitas cambiar el enrutamiento de todas las tareas de una cola.

El enrutamiento a nivel de la cola se aplica a lo siguiente:

• Tareas que están en la cola
• Tareas que se agregan a la cola después de que se haya configurado el enrutamiento a nivel de la cola

Limitaciones

El enrutamiento a nivel de la cola no es compatible con las claves de encriptación administradas por el cliente (CMEK) de Cloud Key Management Service (Cloud KMS). Si la CMEK está habilitada, no puedes hacer lo siguiente:

• Crea tareas en una cola que tenga enrutamiento a nivel de cola
• Aplica el enrutamiento a nivel de la cola

Configura el enrutamiento a nivel de la cola para las tareas HTTP

Puedes configurar una cola para anular el enrutamiento a nivel de la tarea cuando creas o actualizas la cola. Para configurar el enrutamiento a nivel de la cola, establece el parámetro uriOverride de la cola en tu ruta preferida. De forma predeterminada (uriOverrideEnforceMode configurado como ALWAYS), el enrutamiento a nivel de la cola anula el enrutamiento a nivel de la tarea. También puedes establecer uriOverrideEnforceMode en IF_NOT_EXISTS para que el enrutamiento a nivel de la cola se aplique solo cuando una tarea no especifique sus propios componentes de URI.

Si aplicas el enrutamiento a nivel de la cola como una actualización de una cola existente, pausa la cola antes de aplicar los cambios y espera un minuto después de aplicarlos para reanudarla.

1. Pausa la cola ejecutando el siguiente comando:

   gcloud tasks queues pause QUEUE_ID \
       --location=LOCATION

   Reemplaza lo siguiente:

   • QUEUE_ID: Es el ID de tu cola.
   • LOCATION: Es la ubicación de tu cola.

2. Actualiza o quita el enrutamiento a nivel de la cola.

   • Para actualizar el enrutamiento a nivel de la cola, establece el parámetro uriOverride en tu ruta actualizada (o pasa la marca --http-uri-override a gcloud tasks queues update).

   • Para quitar el enrutamiento a nivel de la cola, sigue estos pasos:

     • Google Cloud CLI: Ejecuta gcloud tasks queues update con la marca --clear-http-uri-override:

     gcloud tasks queues update QUEUE_ID \
         --location=LOCATION \
         --clear-http-uri-override

     • API de REST: Envía una solicitud patch para la fila con un objeto JSON vacío ({}) y el parámetro de consulta updateMask establecido en httpTarget.uriOverride (o httpTarget para borrar todos los parámetros de configuración de destino HTTP a nivel de la fila).

     • API de RPC: Envía un UpdateQueueRequest para el Queue con queue.name especificado, http_target.uri_override sin configurar y el parámetro update_mask establecido en http_target.uri_override (o http_target para borrar toda la configuración de destino HTTP a nivel de la cola).

   En el siguiente ejemplo, se usa la API de REST para actualizar el host al que se enrutan las tareas:

   curl -X PATCH -d @- -i \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     "https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID?updateMask=httpTarget.uriOverride" << EOF
   {
     "httpTarget": {"uriOverride":{"host":"NEW_HOST"}}
   }
   EOF
   

   Reemplaza lo siguiente:

   • ACCESS_TOKEN: Es tu token de acceso. Para obtenerlo, ejecuta lo siguiente en la terminal:

     gcloud auth application-default login
     gcloud auth application-default print-access-token

   • PROJECT_ID: Es el ID de tu proyecto de Google Cloud . Para obtenerlo, ejecuta lo siguiente en tu terminal:

     gcloud config get-value project

   • LOCATION: Es la ubicación de tu cola.

   • NEW_HOST: Es el host nuevo al que deseas que se enrute tu cola.

3. Espera un minuto.

   La nueva configuración puede tardar hasta un minuto en aplicarse. Esperar para reanudar la cola ayuda a evitar que las tareas se envíen con la configuración anterior.

4. Reanuda la cola ejecutando el siguiente comando:

   gcloud tasks queues resume QUEUE_ID \
       --location=LOCATION

5. Ejecuta el siguiente comando para verificar que la cola se haya configurado de forma correcta:

   gcloud tasks queues describe QUEUE_ID \
       --location=LOCATION

   El resultado debería contener la anulación de enrutamiento de httpTarget que estableciste.

Configura el enrutamiento a nivel de la cola para las tareas de App Engine

Para configurar el enrutamiento a nivel de la cola para las tareas de App Engine, establece el parámetro appEngineRoutingOverride de la cola en el servicio y la versión de App Engine que prefieras.

1. Configura el enrutamiento a nivel de la cola y anula cualquier enrutamiento a nivel de la tarea:

   gcloud tasks queues update QUEUE_ID \
       --location=LOCATION \
       --routing-override=service:SERVICE,version:VERSION

   Reemplaza lo siguiente:

   • QUEUE_ID: Es el ID de la cola (su nombre corto).
   • LOCATION: Es la ubicación de la cola.
   • SERVICE: Es el servicio de trabajador de App Engine responsable de controlar las tareas.
   • VERSION: Es la versión de la app.

   Por ejemplo, si configuras un servicio de trabajador para que controle todas las tareas de una cola, puedes enrutar a ese servicio y a la versión predeterminada:

   gcloud tasks queues update QUEUE_ID \
       --location=LOCATION \
       --routing-override=service:SERVICE

2. Ejecuta el siguiente comando para verificar que la cola se haya configurado de forma correcta:

   gcloud tasks queues describe QUEUE_ID \
       --location=LOCATION

   El resultado debería ser similar al siguiente ejemplo:

   appEngineRoutingOverride:
     host: SERVICE.PROJECT_ID.appspot.com
     service: SERVICE
   name: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
   rateLimits:
     maxBurstSize: 100
     maxConcurrentDispatches: 1000
     maxDispatchesPerSecond: 500.0
   retryConfig:
     maxAttempts: 100
     maxBackoff: 3600s
     maxDoublings: 16
     minBackoff: 0.100s
   state: RUNNING

3. Para quitar el enrutamiento a nivel de la cola, ejecuta el siguiente comando:

   gcloud tasks queues update QUEUE_ID \
       --location=LOCATION \
       --clear-routing-override

   Cuando se quita el enrutamiento a nivel de la cola, se aplica el enrutamiento a nivel de la tarea a las tareas de la cola y a las tareas que se agreguen a la cola en el futuro.

Define límites de frecuencia

El límite de frecuencia determina la tasa máxima de estado estable en la que una cola activa puede enviar tareas, independientemente de si el envío es un primer intento de tarea o un reintento.

Nota: El parámetro de configuración maxDispatchesPerSecond define el límite de estado estable para una cola activa. Si una cola se crea recientemente, se reanuda después de pausarse, se recupera de las respuestas de error HTTP 429 o 5xx descendentes o está inactiva durante unos minutos sin envíos activos, ingresa a un estado inactivo o frío. Desde este estado, Cloud Tasks aumenta de forma gradual la tasa de envío aplicada de manera forzosa desde un valor de referencia bajo hasta maxDispatchesPerSecond, en lugar de alcanzar la capacidad máxima de inmediato. Para obtener más información sobre el aumento de actividad en frío o inactivo y la limitación del sistema, consulta Aumento de actividad inicial de la cola y Errores de retirada y tasas aplicadas de manera forzosa.

1. Ejecuta el siguiente comando para establecer la tasa máxima y la cantidad de tareas simultáneas que puede enviar una cola:

   gcloud tasks queues update QUEUE_ID \
       --location=LOCATION \
       --max-dispatches-per-second=DISPATCH_RATE \
       --max-concurrent-dispatches=MAX_CONCURRENT_DISPATCHES

   Reemplaza lo siguiente:

   • QUEUE_ID: Es el ID de la cola (su nombre corto).
   • LOCATION: Es la ubicación de la cola.
   • DISPATCH_RATE: Es la tasa de envío. Esta es la velocidad con la que se actualizan los tokens del bucket. En condiciones en las que hay un flujo de tareas relativamente constante, esto equivale a la velocidad con la que se envían las tareas.
   • MAX_CONCURRENT_DISPATCHES: la cantidad máxima de tareas en la cola que se pueden ejecutar a la vez.

   Por ejemplo, si creaste una cola sin establecer ningún parámetro, puedes actualizar la cantidad máxima de tareas simultáneas ejecutando el siguiente comando:

   gcloud tasks queues update QUEUE_ID \
       --location=LOCATION \
       --max-concurrent-dispatches=MAX_CONCURRENT_DISPATCHES

2. Ejecuta el siguiente comando para verificar que la cola se haya configurado de forma correcta:

   gcloud tasks queues describe QUEUE_ID \
       --location=LOCATION

   El resultado debería ser similar al siguiente ejemplo:

   name: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
   rateLimits:
     maxBurstSize: 100
     maxConcurrentDispatches: MAX_CONCURRENT_DISPATCHES
     maxDispatchesPerSecond: DISPATCH_RATE
   retryConfig:
     maxAttempts: 100
     maxBackoff: 3600s
     maxDoublings: 16
     minBackoff: 0.100s
   state: RUNNING

Métodos para definir las tasas de procesamiento de las colas

Puedes definir las tasas de procesamiento de las colas con la API de Cloud Tasks o subiendo un archivo queue.yaml. Ambos métodos dan como resultado colas que usan el mismo mecanismo subyacente.

Precaución: Aunque puedes usar cualquiera de los métodos para crear colas, usa un archivo queue.yaml o la API de Cloud Tasks para configurar tus colas, pero no ambos. Para obtener más información, consulta Usa la administración de colas o queue.yaml.

En ambos casos, la cola usa el algoritmo de bucket de tokens para controlar la tasa de ejecución de tareas. Cada cola con nombre tiene un bucket que contiene sus tokens.

Cada vez que la aplicación ejecuta una tarea, se quita un token del bucket. La cola sigue procesando tareas hasta que su bucket se queda sin tokens. El sistema vuelve a llenar el bucket con tokens nuevos de forma continua según la tasa de max_dispatches_per_second que especifiques para la cola. Si tu cola contiene tareas para procesar y el bucket de la cola contiene tokens, el sistema procesa de forma simultánea tantas tareas como tokens haya, hasta el valor de max_concurrent_dispatches que hayas establecido.

En una cola activa que ya está preparada, una carga desigual puede permitir que la cantidad de tokens en el bucket aumente de forma significativa, lo que puede generar ráfagas de procesamiento cuando llega una ráfaga de solicitudes. En este caso, una cola activa podría experimentar una tasa de envío real que supere temporalmente tu tasa de max_dispatches_per_second, lo que consumirá recursos del sistema y competirá con las solicitudes de entrega de los usuarios. Si usas colas para administrar las tasas de envío en función de los ANS relativamente lentos para los servicios downstream, estas ráfagas pueden generar errores, como HTTP 429 (Too Many Requests) o HTTP 503 (Service Unavailable). Sin embargo, si una cola se creó recientemente, se reanudó hace poco o estuvo inactiva durante varios minutos, ingresa a un estado inactivo o frío y aumenta de forma gradual hacia max_dispatches_per_second en lugar de generar ráfagas de inmediato. Para obtener más información sobre el aumento de la cola inactiva o en frío, consulta Aumento inicial de la cola.

• Cuando usas cualquier método de la API de Cloud Tasks, tienes dos campos para definir la frecuencia de envío de la cola:

  • max_dispatches_per_second
  • max_concurrent_dispatches

  El sistema calcula un tercer campo, max_burst_size, según el valor que establezcas para max_dispatches_per_second. Para obtener más información, consulta Mensajes de RateLimits.

• Cuando usas el método queue.yaml, puedes configurar los tres elementos:

  • max_concurrent_requests, que equivale a max_concurrent_dispatches
  • rate, que equivale a max_dispatches_per_second
  • bucket_size, que equivale a max_burst_size

En la mayoría de los casos, usar el método de la API de Cloud Tasks y permitir que el sistema establezca max_burst_size produce una tasa muy eficiente para administrar ráfagas de solicitudes. Sin embargo, en algunos casos, en especial cuando la tasa necesaria es relativamente lenta, puedes usar el método queue.yaml para establecer de forma manual bucket_size en un valor pequeño o establecer tu max_concurrent_dispatches en un valor pequeño con la API de Cloud Tasks, lo que puede darte más control.

Configura los parámetros de reintento

Si una tarea no se completa correctamente, Cloud Tasks vuelve a intentarla con una retirada exponencial según los parámetros que hayas establecido. Después de que una tarea se ejecuta correctamente, se quita de la cola. En todos los casos, también se aplica el límite de retención máxima de tareas.

De manera opcional, puedes especificar una configuración de reintentos a nivel de la tarea que anule la configuración de reintentos a nivel de la cola para la tarea. Para obtener más información, consulta Configura parámetros de reintento para una tarea.

Sugerencia: Para depurar tus parámetros de reintento, puedes registrar el código de estado de cada invocación de una tarea usando Cloud Logging con tus colas y configurando una proporción de muestreo de registros para especificar qué fracción de operaciones se escribirá en Logging.

1. Especifica la cantidad máxima de veces que se deben reintentar las tareas con errores en la cola, establece un límite de tiempo para los intentos de reintento y controla el intervalo entre los intentos ejecutando el siguiente comando:

   gcloud tasks queues update QUEUE_ID \
       --location=LOCATION \
       --max-attempts=MAX_ATTEMPTS \
       --max-retry-duration=MAX_RETRY_DURATION \
       --min-backoff=MIN_INTERVAL \
       --max-backoff=MAX_INTERVAL \
       --max-doublings=MAX_DOUBLINGS

   Reemplaza lo siguiente:

   • QUEUE_ID: Es el ID de la cola (su nombre corto).
   • LOCATION: Es la ubicación de la cola.
   • MAX_ATTEMPTS: Es la cantidad máxima de intentos para una tarea, incluido el primero. Para permitir reintentos ilimitados, establece este valor en -1. MAX_RETRY_DURATION se sigue aplicando incluso si se alcanza MAX_ATTEMPTS o se establece en -1.
   • MAX_RETRY_DURATION: Es la cantidad máxima de tiempo para reintentar una tarea con errores, medida desde el primer intento de la tarea. El valor debe ser una cadena que termine en "s", como 5s. Para especificar una duración ilimitada, establece este valor en 0s. MAX_ATTEMPTS se sigue aplicando incluso si se alcanza MAX_RETRY_DURATION o se establece en 0s.
   Nota: Si especificas intentos ilimitados (MAX_ATTEMPTS es -1) y una duración ilimitada (MAX_RETRY_DURATION es 0s), la tarea se reintenta hasta que alcanza el límite de retención máxima de tareas. De lo contrario, Cloud Tasks dejará de reintentar solo después de que se cumplan ambas condiciones o de que la tarea se complete correctamente. Cuando se haya intentado realizar la tarea MAX_ATTEMPTS veces y haya transcurrido el tiempo MAX_RETRY_DURATION, no se realizarán más intentos y se borrará la tarea.
   • MIN_INTERVAL: Es la cantidad mínima de tiempo que se debe esperar entre los intentos de reintento. El valor debe ser una cadena que termine en "s", como 5s.
   • MAX_INTERVAL: Es la cantidad máxima de tiempo que se debe esperar entre los intentos de reintento. El valor debe ser una cadena que termine en "s", como 5s.

   • MAX_DOUBLINGS: Es la cantidad máxima de veces que se duplica el intervalo entre los reintentos de tareas con errores antes de que el aumento se vuelva constante. El intervalo de reintento de una tarea comienza en MIN_INTERVAL, luego se duplica MAX_DOUBLINGS veces, luego aumenta de forma lineal y, por último, se reintenta en intervalos de MAX_INTERVAL hasta MAX_ATTEMPTS veces.

     Por ejemplo, si MIN_INTERVAL es 10s, MAX_INTERVAL es 300s y MAX_DOUBLINGS es 3, el intervalo de reintento se duplica 3 veces, aumenta de forma lineal en 2^3 * 10 s y, luego, se reintenta en intervalos de MAX_INTERVAL hasta que se haya intentado realizar la tarea MAX_ATTEMPTS veces: 10 s, 20 s, 40 s, 80 s, 160 s, 240 s, 300 s, 300 s, etcétera.

Para obtener más detalles sobre los parámetros, consulta la referencia del recurso RetryConfig.

1. Ejecuta el siguiente comando para verificar que la cola se haya configurado de forma correcta:

   gcloud tasks queues describe QUEUE_ID \
       --location=LOCATION

   El resultado debería contener los parámetros de retryConfig que estableciste:

   retryConfig:
     maxAttempts: MAX_ATTEMPTS
     maxBackoff: MAX_INTERVAL
     maxDoublings: MAX_DOUBLINGS
     maxRetryDuration: MAX_RETRY_DURATION
     minBackoff: MIN_INTERVAL

¿Qué sigue?

• Obtén información para crear tareas de destino HTTP.
• Obtén más información para crear tareas de App Engine.
• Obtén más información sobre la administración de colas en la referencia de la API de RPC.
• Obtén más información sobre la administración de colas en la referencia de la API de REST.