Riferimento queue.yaml

ID regione

REGION_ID è un codice abbreviato assegnato da Google in base all'area geografica selezionata al momento della creazione dell'app. Il codice non corrisponde a un paese o a una provincia, anche se alcuni ID regione possono sembrare simili ai codici paese e provincia di uso comune. Per le app create dopo febbraio 2020, REGION_ID.r è incluso negli URL di App Engine. Per le app esistenti create prima di questa data, l'ID regione è facoltativo nell'URL.

Scopri di più sugli ID regione.

Il file di configurazione queue.yaml viene utilizzato per creare e configurare quasi tutte le code di attività (push o pull) utilizzate dalla tua app. Tutte le app App Engine includono una coda in modalità push preconfigurata automaticamente denominata default. Anche se non crei la coda default personalmente, puoi aggiungere altre code o modificare la configurazione della coda default utilizzando il file queue.yaml.

Per le app Java, il file viene archiviato in qualsiasi punto della directory del codice sorgente.

Per configurare le code in modalità push, puoi utilizzare i metodi queue.yaml o Gestione code di Cloud Tasks, ma non entrambi contemporaneamente. La combinazione del metodo di caricamento queue.yaml con i metodi di gestione delle code può produrre risultati imprevisti e non è consigliata.

Per configurare le code in modalità pull, devi utilizzare il file queue.yaml.

Esempio

Di seguito è riportato un esempio di base che definisce una coda denominata e sostituisce la frequenza di elaborazione predefinita:

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

Di seguito è riportato un esempio più complesso di una configurazione queue.yaml che mostra la configurazione del numero di tentativi dell'attività e la modifica della velocità di elaborazione predefinita.

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

Sintassi

Il file queue.yaml è un file YAML la cui istruzione principale è queue. Questa istruzione contiene zero o più code denominate. Ogni definizione di coda può specificare i seguenti elementi:

Elemento Descrizione
<bucket-size> (code in modalità push)

Facoltativo. Una coda di attività utilizza l'algoritmo del bucket di token per controllare la frequenza di esecuzione delle attività. Ogni coda denominata ha un token bucket che contiene i token, fino al massimo specificato dal valore bucket_size. Ogni volta che l'applicazione esegue un'attività, un token viene rimosso dal bucket. L'elaborazione delle attività in coda continua finché il bucket della coda esaurisce i token. App Engine ricarica il bucket con nuovi token continuamente, in base alla tariffa specificata per la coda.

Le dimensioni del bucket limitano la velocità di elaborazione della coda quando molte attività sono in coda e la frequenza è elevata. Il valore massimo per la dimensione del bucket è 500. Ciò consente di avere una frequenza elevata, quindi l'elaborazione inizia poco dopo che un'attività viene accodata, ma limita l'utilizzo delle risorse quando molte attività sono accodate in un breve periodo di tempo.

Se non specifichi bucket_size per una coda, il valore predefinito è 5. Ti consigliamo di impostarlo su un valore maggiore perché la dimensione predefinita potrebbe essere troppo piccola per molti casi d'uso. Ad esempio, puoi determinare la dimensione del bucket in base alla frequenza di elaborazione.

Per maggiori informazioni su questo elemento, consulta la descrizione comparativa di max_burst_size

nel riferimento API Cloud Tasks.
<max-concurrent-requests> (code in modalità push)

Facoltativo. Imposta il numero massimo di attività che possono essere eseguite contemporaneamente dalla coda specificata. Il valore è un numero intero. Per impostazione predefinita, il limite è di 1000 attività per coda. Il limite massimo consigliato è di 5000 attività per coda. Tieni presente che le code possono aumentare lentamente quando vengono create la prima volta o se sono inattive per un po' di tempo.

La limitazione del numero di attività in parallelo offre un maggiore controllo sulla frequenza di esecuzione della coda e può impedire l'esecuzione di troppe attività contemporaneamente. Può anche impedire la contesa del datastore e rendere disponibili le risorse per altre code o elaborazioni online.

Per maggiori informazioni su questo elemento, consulta la descrizione comparativa di max_concurrent_dispatches nel riferimento dell'API Cloud Tasks.
<mode>

Facoltativo. Identifica la modalità coda. Il valore predefinito di questa impostazione è push, che identifica una coda come coda push. Se vuoi utilizzare le coe in modalità pull, imposta la modalità su pull.

<name>

Obbligatorio. Il nome della coda. Questo è il nome specificato quando chiami QueueFactory.getQueue().

Il nome della coda può contenere lettere maiuscole e minuscole, numeri e trattini. La lunghezza massima di un nome coda è di 100 caratteri.

Tutte le app hanno una coda in modalità push denominata predefinita. Questa coda ha una frequenza predefinita di cinque attività al secondo. Tieni presente che questa coda predefinita non viene visualizzata nella console Google Cloud fino alla prima volta che viene utilizzata o configurata. Puoi configurare la coda predefinita, inclusa la modifica della frequenza predefinita, definendo una coda denominata "default" nel file queue.yaml.

<rate> (code in modalità push)

Obbligatorio. Frequenza di elaborazione delle attività in questa coda. Il valore è un numero seguito da una barra e un'unità di tempo, dove l'unità è s per i secondi, m per i minuti, h per le ore o d per i giorni. Ad esempio, il valore 5/m indica che le attività verranno elaborate a una frequenza di 5 volte al minuto. Il valore massimo per rate è 500/s.

Se il numero è 0 (ad esempio 0/s), la coda è considerata "in pausa" e non viene elaborata alcuna attività.

Per maggiori informazioni su questo elemento, consulta la descrizione comparativa di max_dispatches_per_second nel riferimento dell'API Cloud Tasks.
<retry-parameters>

Facoltativo. Configura i nuovi tentativi per le attività non riuscite nelle code in modalità push. Questa aggiunta consente di specificare il numero massimo di volte in cui riprovare le attività non riuscite in una coda specifica. Puoi anche impostare un limite di tempo per i nuovi tentativi e controllare l'intervallo tra i tentativi.

I parametri per la ripetizione possono contenere i seguenti elementi secondari:

<task-retry-limit>
Il numero di nuovi tentativi. Ad esempio, se 0 è specificato e l'attività non è riuscita, non viene eseguito un nuovo tentativo. Se 1 è specificato e l'attività non è riuscita, l'attività viene ripetuta una volta. Se questo parametro non è specificato, l'attività viene riprovata a tempo indeterminato. Se task_retry_limit è specificato con task_age_limit, l'attività viene ripetuta fino al raggiungimento di entrambi i limiti.
<task-age-limit> (code in modalità push)
Il limite di tempo per riprovare un'attività non riuscita, misurato dalla data della prima esecuzione dell'attività. Il valore è un numero seguito da un'unità di tempo, dove l'unità è s per i secondi, m per i minuti, h per le ore o d per i giorni. Ad esempio, il valore 5d specifica un limite di cinque giorni dopo il primo tentativo di esecuzione dell'attività. Se questo parametro non viene specificato, l'attività viene riprovata a tempo indeterminato. Se specificato con task_retry_limit, App Engine riprova a eseguire l'attività fino a quando non vengono raggiunti entrambi i limiti.
<min-backoff-seconds> (code in modalità push)
Il numero minimo di secondi di attesa prima di riprovare un'attività non riuscita. Il valore predefinito è 0.1.
<max-backoff-seconds> (code in modalità push)
Il numero massimo di secondi da attendere prima di riprovare un'attività non riuscita. Il valore predefinito è 3600.
<max-doublings> (code in modalità push)
Il numero massimo di volte in cui l'intervallo tra i nuovi tentativi di attività non riuscite verrà raddoppiato prima che l'aumento diventi costante. La costante è: 2**max_doublings * min_backoff_seconds. Il valore predefinito è 16.
<target> (code in modalità push)

Facoltativo. Una stringa che nomina un servizio/versione, una versione di frontend o un backend su cui eseguire tutte le attività in coda in questa coda. Il valore predefinito è la stringa vuota.

La stringa viene anteposta al nome di dominio della tua app durante la creazione della richiesta HTTP per un'attività. Ad esempio, se il tuo ID app è my-app e imposti il target su my-version-dot-my-service, il nome host dell'URL verrà impostato su my-version-dot-my-service-dot-my-app.REGION_ID.r.appspot.com.

Se la destinazione non è specificata, le attività vengono richiamate nella stessa versione dell'applicazione in cui sono state accodate. Quindi, se hai accodato un'attività dalla versione predefinita dell'applicazione senza specificare una destinazione in coda, l'attività viene richiamata nella versione predefinita dell'applicazione. Tieni presente che se la versione predefinita dell'applicazione cambia tra il momento in cui l'attività viene accodata e il momento in cui viene eseguita, l'attività verrà eseguita nella nuova versione predefinita.

Se utilizzi servizi con un file di invio, la richiesta HTTP dell'attività potrebbe essere intercettata e reindirizzata a un altro servizio.

I seguenti elementi possono essere specificati per tutte le code all'interno di un'app:

Elemento Descrizione
<total-storage-limit>

Facoltativo. Una stringa che sostituisce il limite di archiviazione della quota predefinito disponibile per l'archiviazione della coda di attività (100 milioni). Ad esempio: 


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

Questa quota fa parte della quota di archiviazione totale dell'applicazione (inclusa la quota del datastore e dell'archivio BLOB).

Se non è specificato alcun suffisso, il numero specificato viene interpretato come byte. Sono supportati i seguenti suffissi:

  • B (byte)
  • K (kilobyte)
  • M (megabyte)
  • G (gigabyte)
  • T (terabyte)

Se <total-storage-limit> supera lo spazio di archiviazione totale su disco disponibile per un'applicazione, il limite viene limitato allo spazio di archiviazione disponibile.

Deployment del file di configurazione della coda

Il file queue.yaml può trovarsi ovunque nella directory del codice sorgente.

Per eseguire il deployment del file di configurazione della coda senza modificare in altro modo la versione attualmente pubblicata, utilizza uno dei seguenti comandi nella directory contenente il file della coda, a seconda dell'ambiente:

gcloud

gcloud app deploy queue.yaml

Maven

mvn appengine:deployQueue queue.yaml

Gradle

gradle appengineDeployQueue queue.yaml

IDE

Se utilizzi IntelliJ o Eclipse, puoi selezionare i singoli file di configurazione di cui eseguire il deployment utilizzando il modulo di deployment.

Eliminazione delle code

Per eliminare una coda:

  1. Rimuovi la definizione della coda dal file queue.yaml.

  2. Carica la modifica nel file queue.yaml.

    gcloud app deployQueue.yaml

  3. Elimina la coda nella console Google Cloud, selezionala e fai clic su Elimina coda:

    Vai alla pagina Code di attività

Se elimini una coda dalla console Google Cloud, devi attendere 7 giorni prima di ricreare con lo stesso nome.