Riferimento queue.yaml

ID regione

REGION_ID è un codice abbreviato assegnato da Google in base alla regione selezionata quando crei l'app. Il codice non corrisponde a un paese o a una provincia, anche se alcuni ID regione possono sembrare simili ai codici di paesi e province 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 tutti delle code di attività (push o pull) usati dalla tua app. Tutte le app App Engine sono dotate di una coda push preconfigurata automaticamente denominata default. Anche se creare la coda default autonomamente, puoi aggiungere altre code o modificare configurazione della coda default utilizzando il file queue.yaml.

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

Per configurare le code in modalità push, puoi utilizzare queue.yaml o i metodi di gestione delle code di Cloud Tasks, ma non entrambi contemporaneamente. Combinando Il metodo di caricamento queue.yaml con metodi di gestione delle code può produrre risposte impreviste risultati e non è consigliato.

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 ed esegue l'override della 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 dimostra come impostare il numero di tentativi di attività e modificare la frequenza 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 con istruzione principale queue. Questa direttiva contiene zero o più code denominate. Ogni definizione di coda può specificare i seguenti elementi:

Elemento Descrizione
<bucket-size> (code push)

Facoltativo. Una coda di attività utilizza l'algoritmo del bucket token per controllare la frequenza delle dell'esecuzione di un'attività. Ogni coda denominata ha un token bucket che contiene i token, fino al limite massimo specificato dal valore bucket_size. Ogni volta quando l'applicazione esegue un'attività, un token viene rimosso dal bucket. Continua a elaborare le attività nella coda finché il bucket della coda non esaurisce i token. App Engine ricarica il bucket con nuovi token in base alla frequenza specificata per la coda.

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

Se non specifichi bucket_size per una coda, il valore predefinito è 5. Ti consigliamo di impostare un valore più elevato perché la dimensione predefinita potrebbe essere troppo piccola per molti casi d'uso. Ad esempio, puoi determinare le dimensioni del bucket in base alla velocità di elaborazione.

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

nel riferimento dell'API Cloud Tasks.
<max-concurrent-requests> (code 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 è 1000 attività per coda. Il limite massimo consigliato è di 5000 attività per coda. Tieni presente che le code possono aumentare lentamente quando o se sono rimasti inattivi per un po'.

La limitazione del numero di attività simultanee offre un maggiore controllo la velocità di esecuzione della coda e il numero di attività potrebbe in esecuzione contemporaneamente. Inoltre, può evitare la contesa del datastore e mettere a disposizione le risorse per altre code o l'elaborazione online.

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

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

<name>

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

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

Tutte le app hanno una coda push denominata predefinita. Questa coda ha una frequenza preimpostata di 5 attività al secondo. Tieni presente che questa coda predefinita non viene visualizzata nella console Google Cloud fino al primo utilizzo o configurazione. Puoi configurare la coda predefinita, modificando la frequenza predefinita, definendo una coda denominata "default" nel tuo file queue.yaml.

<rate> (code push)

Obbligatorio. Frequenza di elaborazione delle attività in questa coda. Il valore è un numero seguito da una barra e 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 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 es. 0/s), la coda è considerata "in pausa" e non viene elaborata alcuna attività.

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

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

I parametri dei nuovi tentativi possono contenere i seguenti sottoelementi:

<task-retry-limit>
Il numero di nuovi tentativi. Ad esempio, se viene specificato 0 e l'attività non va a buon fine, non viene eseguito alcun nuovo tentativo. Se 1 viene specificato e l'attività non riesce, il e un nuovo tentativo dell'attività una volta. Se questo parametro non è specificato, l'attività viene riprovato a tempo indeterminato. Se task_retry_limit è specificato con task_age_limit, l'attività viene ritentata fino a quando vengono raggiunti i limiti.
<task-age-limit> (code push)
Il limite di tempo per ritentare un'attività non riuscita, misurato dal momento in cui è stata eseguita per la prima volta. Il valore è un numero seguito da un'unità di misura del 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 è specificato, l'attività viene ripetuta a tempo indeterminato. Se specificato con task_retry_limit, App Engine proverà di nuovo l'attività fino a quando vengono raggiunti entrambi i limiti.
<min-backoff-seconds> (code push)
Il numero minimo di secondi da attendere prima di riprovare un'attività dopo che è stata eseguita senza esito. Il valore predefinito è 0.1.
<max-backoff-seconds> (code push)
Il numero massimo di secondi di attesa prima di riprovare un'attività dopo che non è riuscita. Il valore predefinito è 3600.
<max-doublings> (code push)
Il numero massimo di volte in cui l'intervallo tra i tentativi di attività non riuscita verrà raddoppiato prima che l'aumento diventi costante. La costante è: 2**max_doublings * min_backoff_seconds. Il valore predefinito è 16.
<target> (code push)

Facoltativo. Una stringa che indica un servizio/una versione, una versione 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 compilazione della richiesta HTTP per un'attività. Ad esempio, se l'ID app è my-app e il target è impostato 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 sulla stessa versione dell'applicazione in cui erano in coda. Pertanto, se hai inserito in coda un compito dalla versione dell'applicazione predefinita senza specificare un target nella coda, il compito viene invocato nella versione dell'applicazione predefinita. Tieni presente che se la versione predefinita dell'applicazione cambia tra il momento in cui l'attività viene messa in coda e il momento in cui viene eseguita, l'attività verrà eseguita nella nuova versione predefinita.

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

Per tutte le code all'interno di un'app è possibile specificare i seguenti elementi:

Elemento Descrizione
<total-storage-limit>

Facoltativo. Una stringa che sostituisce il limite di spazio di archiviazione della quota predefinito disponibile per lo spazio di archiviazione della coda di attività (100 M). 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 spazio di archiviazione totale dell'applicazione (tra cui la quota di datastore e BLOB).

Se non viene 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 è limitato allo spazio di archiviazione disponibile.

Deployment del file di configurazione della coda

Il file queue.yaml può trovarsi in qualsiasi posizione della directory del codice sorgente.

Per eseguire il deployment del file di configurazione della coda senza alterare la versione attualmente pubblicata, utilizza uno dei seguenti comandi nella directory contenente il file della coda, a seconda del tuo ambiente:

gcloud

gcloud app deploy queue.yaml

Maven

mvn appengine:deployQueue queue.yaml

Gradle

gradle appengineDeployQueue queue.yaml

IDE

Se utilizzi IntelliJ o Eclipse, seleziona i singoli file di configurazione da eseguire il deployment utilizzando il modulo di deployment.

Eliminazione delle code in corso...

Per eliminare una coda:

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

  2. Carica la modifica nel file queue.yaml.

    gcloud app deploy baseline.yaml

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

    Vai alla pagina Code di lavoro

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