Referencia queue.yaml

ID de región

REGION_ID es un código abreviado que Google asigna en función de la región que eliges cuando creas la app. El código no corresponde a un país ni a una provincia, aunque algunos ID de región puedan parecer similares a los códigos de país y provincia que se suelen usar. En el caso de las apps creadas después de febrero de 2020, REGION_ID.r se incluye en las URL de App Engine. En el caso de las apps existentes creadas antes de esta fecha, el ID de región es opcional en la URL.

Obtén más información acerca de los ID de región.

El archivo de configuración queue.yaml se usa para crear y configurar casi todas las listas de tareas en cola (push o pull) que usa la aplicación. Todas las apps de App Engine incluyen una lista de aplicaciones en cola preconfigurada llamada default. Aunque no crees la cola default, puedes agregar otras colas o cambiar la configuración de la cola default mediante el archivo queue.yaml.

Para las apps de Java, este archivo se almacena en cualquier lugar del directorio del código fuente.

Para configurar listas de aplicaciones en cola, puedes usar los métodos queue.yaml o de administración de colas de Cloud Tasks, pero no ambos al mismo tiempo. La combinación del método de carga queue.yaml con los métodos de administración de colas puede generar resultados inesperados y no se recomienda.

Para configurar las listas de extracción, debes usar el archivo queue.yaml.

Ejemplo

A continuación, se incluye un ejemplo básico que define una cola nombrada y anula la frecuencia de procesamiento predeterminada:

queue:
- name: my-push-queue
  rate: 1/s

El siguiente es un ejemplo complejo de una configuración de queue.yaml que demuestra cómo configurar la cantidad de intentos de tareas y cómo modificar la tasa de procesamiento predeterminada.

queue:
- name: fooqueue
  rate: 1/s
  retry_parameters:
    task_retry_limit: 7
    task_age_limit: 2d
- name: barqueue
  rate: 1/s
  retry_parameters:
    min_backoff_seconds: 10
    max_backoff_seconds: 200
    max_doublings: 0
- name: bazqueue
  rate: 1/s
  retry_parameters:
    min_backoff_seconds: 10
    max_backoff_seconds: 200
    max_doublings: 3

Sintaxis

El archivo queue.yaml es un archivo YAML cuya directiva raíz es queue. Esta directiva puede contener cero o más colas nombradas. Cada definición de cola puede especificar los siguientes elementos:

Elemento Descripción
<bucket-size> (lista de aplicaciones en cola)

Opcional. Una lista de tareas en cola utiliza el algoritmo de bucket de tokens para controlar la frecuencia de ejecución de la tarea. Cada cola nombrada tiene un bucket de tokens que contiene una cantidad de tokens equivalente al máximo especificado por el valor bucket_size. Cada vez que tu aplicación ejecuta una tarea, se quita un token del bucket. Continúas procesando las tareas en la cola hasta que el bucket de la cola se queda sin tokens. App Engine rellena el bucket con tokens nuevos de forma continua según la frecuencia que hayas especificado para la cola.

El tamaño del bucket limita la rapidez con la que se procesa la cola cuando existen muchas tareas en cola y la frecuencia es alta. El valor máximo para el tamaño del bucket es de 500. Esto te permite tener una frecuencia alta, por lo que el procesamiento comienza poco después de que se pone una tarea en cola; aun así, limita el uso de recursos cuando muchas tareas se ponen en cola en un período corto de tiempo.

Si no especificas el bucket_size para una cola, el valor predeterminado es de 5. Te recomendamos establecer un valor mayor porque el tamaño predeterminado podría ser demasiado pequeño para muchos casos prácticos. Por ejemplo, podrías determinar el tamaño de tu bucket según la tasa de procesamiento.

Para obtener más información sobre este elemento, consulta la descripción comparativa de max_burst_size

en la referencia de la API de Cloud Tasks.
<max-concurrent-requests> (lista de aplicaciones en cola)

Opcional. Establece la cantidad máxima de tareas que pueden ejecutarse de manera simultánea desde la cola especificada. El valor es un número entero. De manera predeterminada, el límite es de 1,000 tareas por cola. El límite superior recomendado es de 5,000 tareas por cola. Ten en cuenta que las colas pueden avanzar lentamente cuando se crean por primera vez o si han estado inactivas durante un tiempo.

La restricción de la cantidad de tareas simultáneas te brinda más control sobre la frecuencia de ejecución de la cola y puede evitar que se ejecuten demasiadas tareas a la vez. También puede evitar la contención del almacén de datos y hacer que los recursos estén disponibles para otras colas o el procesamiento en línea.

Para obtener más información sobre este elemento, consulta la descripción comparativa de max_concurrent_dispatches en la referencia de la API de Cloud Tasks.
<mode>

Opcional. Identifica el modo de la cola. El valor predeterminado de esta configuración es push, que identifica una cola como una lista de aplicaciones en cola. Si deseas usar listas de extracción, configura el modo como pull.

<name>

Obligatorio. El nombre de la cola. Este es el nombre que se especifica cuando se llama a QueueFactory.getQueue().

Un nombre de cola puede contener letras mayúsculas y minúsculas, números y guiones. La longitud máxima para un nombre de cola es de 100 caracteres.

Todas las apps tienen una lista de aplicaciones en cola con un nombre predeterminado. Esta cola tiene una frecuencia predeterminada de 5 tareas por segundo. Ten en cuenta que esta cola predeterminada no se muestra en la consola de Google Cloud hasta que se use o configure por primera vez. Puedes configurar la cola predeterminada, incluido el cambio de la tasa predeterminada, si defines una cola llamada "default" en el archivo queue.yaml.

<rate> (lista de aplicaciones en cola)

Obligatorio. Indica con qué frecuencia se procesan las tareas en esta cola. El valor es un número seguido de una barra y una unidad de tiempo, en la que la unidad es s para segundos, m para minutos, h para horas o d para días. Por ejemplo, el valor 5/m indica que las tareas se procesarán con una frecuencia de 5 veces por minuto. El valor máximo de rate es 500/s.

Si el número es 0 (como en 0/s), la cola se considera “pausada” y no se procesan tareas.

Para obtener más información sobre este elemento, consulta la descripción comparativa de max_dispatches_per_second en la referencia de la API de Cloud Tasks.
<retry-parameters>

Opcional. Configura los reintentos para las tareas con errores en las listas de aplicaciones en cola. Esta adición te permite especificar la cantidad máxima de veces que se reintentarán las tareas con errores en una cola específica. También puedes establecer un límite de tiempo para los reintentos y controlar el intervalo entre intentos.

Los parámetros de reintento pueden contener los siguientes subelementos:

<task-retry-limit>
La cantidad de reintentos. Por ejemplo, si se especifica 0 y la tarea falla, no se reintenta. Si se especifica 1 y la tarea falla, se reintenta una vez. Si no se especifica este parámetro, la tarea se reintenta indefinidamente. Si se especifica task_retry_limit con task_age_limit, se vuelve a intentar la tarea hasta que se alcancen ambos límites.
<task-age-limit> (lista de aplicaciones en cola)
El límite de tiempo para reintentar una tarea con errores, medido desde la primera ejecución de la tarea. El valor es un número seguido de una unidad de tiempo, en la que la unidad es s para segundos, m para minutos, h para horas o d para días. Por ejemplo, el valor 5d especifica un límite de cinco días después del primer intento de ejecución de la tarea. Si no se especifica este parámetro, la tarea se reintenta indefinidamente. Si se especifica con task_retry_limit, App Engine vuelve a intentar la tarea hasta que se alcancen ambos límites.
<min-backoff-seconds> (lista de aplicaciones en cola)
La cantidad mínima de segundos que se espera antes de reintentar una tarea después de que falla. El valor predeterminado es 0.1.
<max-backoff-seconds> (lista de aplicaciones en cola)
La cantidad máxima de segundos que se espera antes de reintentar una tarea después de que falla. El valor predeterminado es 3600.
<max-doublings> (lista de aplicaciones en cola)
La cantidad máxima de veces que se puede duplicar el intervalo entre reintentos de las tareas con errores antes de que el aumento se vuelva constante. La constante es: 2**max_doublings * min_backoff_seconds. El valor predeterminado es 16.
<target> (lista de aplicaciones en cola)

Opcional. Una string que da nombre a un servicio o una versión, de frontend o backend, donde se ejecutarán todas las tareas puestas en cola para esta cola. El valor predeterminado es una string vacía.

La string se agrega al nombre de dominio de tu aplicación cuando se compila la solicitud HTTP para una tarea. Por ejemplo, si el ID de tu app es my-app y configuraste el destino como my-version-dot-my-service, la URL del nombre de host se configurará como my-version-dot-my-service-dot-my-app.REGION_ID.r.appspot.com

Si no se especifica el destino, las tareas se invocan en la misma versión de la aplicación donde se pusieron en cola. Por lo tanto, si pusiste en cola una tarea desde la versión predeterminada de la aplicación sin especificar un destino en la cola, la tarea se invoca en la versión predeterminada de la aplicación. Ten en cuenta que si la versión predeterminada de la aplicación cambia entre el momento en que la tarea se pone en cola y el momento en que se ejecuta, la tarea se ejecutará en la versión predeterminada nueva.

Si utilizas servicios junto con un archivo de despacho, la solicitud HTTP de tu tarea podría ser interceptada y reenviada a otro servicio.

Los siguientes elementos pueden especificarse para todas las colas dentro de una app:

Elemento Descripción
<total-storage-limit>

Opcional. Una string que anula el límite de almacenamiento de cuota predeterminado disponible para el almacenamiento taskqueue (100 M). Por ejemplo: 

<queue-entries>
  <total-storage-limit>1.2G</total-storage-limit>
  <queue>
    <name>fooqueue</name>
  </queue>
</queue-entries>

Esta cuota es parte de la cuota de almacenamiento total de la aplicación (incluidas las cuotas del almacén de datos y de blobstore).

Si no se especifica ningún sufijo, el número que especificas se interpretará como bytes. Se admiten los siguientes sufijos:

  • B (bytes)
  • K (kilobytes)
  • M (megabytes)
  • G (gigabytes)
  • T (terabytes)

Si <total-storage-limit> supera el almacenamiento total del disco disponible para una aplicación, se restringe el límite al almacenamiento disponible.

Implementa el archivo de configuración de cola

El archivo queue.yaml puede residir en cualquier lugar de tu código fuente.

Para implementar el archivo de configuración de cola sin modificar la versión actual, usa uno de los siguientes comandos en el directorio que contiene el archivo de cola según el entorno:

gcloud

gcloud app deploy queue.yaml

Maven

mvn appengine:deployQueue queue.yaml

Gradle

gradle appengineDeployQueue queue.yaml

IDE

Si usas IntelliJ o Eclipse, debes usar el formulario de implementación para seleccionar los archivos de configuración individuales que se implementarán.

Borra colas

Para borrar una cola, haz lo siguiente:

  1. Quita la definición de la cola de tu archivo queue.yaml.

  2. Sube el cambio al archivo queue.yaml.

    gcloud app deploy queue.yaml

  3. Borra la cola en la consola de Google Cloud. Para ello, selecciona la cola y haz clic en Borrar cola:

    Ir a la página Listas de tareas en cola

Si borras una cola desde la consola de Google Cloud, debes esperar 7 días antes de volver a crear una con el mismo nombre.