Questa pagina descrive come eseguire la migrazione del codice delle code in coda in modalità push dalle code di attività a Cloud Tasks. Cloud Tasks è ora il modo migliore per lavorare con le code in modalità push di App Engine.
Con Cloud Tasks, accedi allo stesso servizio a cui accedi con l'API RPC Task Queues. Ciò significa che non devi ricreare le code e le attività di push esistenti. Tuttavia, devi eseguire la migrazione del codice che crea o interagisce con code o attività push per utilizzare l'API Cloud Tasks.
Puoi creare e interagire con code in modalità push e attività di push utilizzando le API REST e RPC di Cloud Tasks, la libreria client di Cloud Tasks, Google Cloud CLI e la console Google Cloud. Questa pagina fornisce esempi che utilizzano gcloud CLI e la libreria client di Cloud Tasks.
In Cloud Tasks, tutte le code funzionano come code in modalità push. Nel resto di questa guida e nella documentazione di Cloud Tasks, il termine coda equivale al termine coda push. Analogamente, il termine attività equivale al termine attività push.
Funzionalità non disponibili in Cloud Tasks
Le seguenti funzionalità non sono disponibili in Cloud Tasks:
- Accodamento delle attività nelle transazioni Datastore
- Utilizzo della libreria delle attività differite anziché di un servizio worker
- Utilizzo delle attività nelle applicazioni multi-tenant
- Simulazione con il server di sviluppo locale
- Aggiunta delle attività in modo asincrono.
Prezzi e quote
La migrazione delle code in modalità push a Cloud Tasks potrebbe influire sui prezzi e sulle quote della tua app.
Prezzi
Cloud Tasks prevede pricing specifici. Come per le code di attività, l'invio di richieste all'app App Engine con un'attività può comportare costi.
Quote
Le quotas di Cloud Tasks sono diverse da quelle per le code di attività. Come per le code di attività, l'invio di richieste all'app App Engine da Cloud Tasks potrebbe influire sulle quote delle richieste di App Engine.
Prima della migrazione
Le sezioni seguenti discutono i passaggi di configurazione prima di eseguire la migrazione delle code in modalità push a Cloud Tasks.
Migrazione delle code in modalità pull
Prima di iniziare,
esegui la migrazione delle code in modalità pull
prima di seguire le istruzioni di questa guida
per la migrazione delle code in modalità push. La migrazione delle code in modalità pull dopo la migrazione delle code in modalità push non è consigliata perché l'uso richiesto del file queue.yaml
potrebbe causare comportamenti imprevisti con Cloud Tasks.
Protezione della configurazione della coda
Una volta avviato il processo di migrazione a Cloud Tasks, la modifica del file queue.yaml
può causare comportamenti imprevisti e non è consigliata. Proteggi la configurazione della coda dalle modifiche apportate dal file queue.yaml
con i passaggi seguenti.
Configura gcloud CLI in modo da omettere il file
queue.yaml
nei deployment futuri.Aggiungi il tuo file
queue.yaml
a un file.gcloudignore
. Per verificare se disponi già di un file.gcloudignore
, puoi eseguire il comando seguente nel terminale dalla directory di primo livello dell'applicazione. Questo comando restituirà il nome file se esiste.ls -a | grep .gcloudignore
Per scoprire di più sui file
.gcloudignore
, leggi il riferimento.gcloudignore
.Limita le autorizzazioni per il tuo file
queue.yaml
.Segui le best practice descritte nella nostra guida su come proteggere la configurazione delle code.
Scopri di più su Cloud Tasks e il file
queue.yaml
(facoltativo).Quando utilizzi l'API Cloud Tasks per gestire la configurazione delle code, il deployment di un file
queue.yaml
esegue l'override della configurazione impostata da Cloud Tasks, causando possibili comportamenti imprevisti. Per saperne di più, leggi Utilizzo della gestione delle code e della gestione di code.yaml.
Abilitazione dell'API Cloud Tasks
Per abilitare l'API Cloud Tasks, fai clic su Abilita nell'API Cloud Tasks nella libreria API. Se vedi un pulsante Gestisci anziché un pulsante Abilita, significa che hai precedentemente abilitato l'API Cloud Tasks per il tuo progetto e non devi farlo di nuovo.
Autenticazione dell'app nell'API Cloud Tasks
Devi autenticare la tua app nell'API Cloud Tasks. Questa sezione illustra l'autenticazione per due diversi casi d'uso.
Per sviluppare o testare la tua app localmente, ti consigliamo di utilizzare un account di servizio. Per istruzioni su come configurare un account di servizio e connetterlo all'app, consulta Ottenere e fornire manualmente le credenziali dell'account di servizio.
Per eseguire il deployment della tua app su App Engine, non devi fornire alcuna nuova autenticazione. Le credenziali predefinite dell'applicazione (ADC) deducono i dettagli di autenticazione per le app di App Engine.
Download di gcloud CLI
Scarica e installa gcloud CLI per utilizzare gcloud CLI con l'API Cloud Tasks se non l'hai già installata. Se gcloud CLI è già installato, esegui questo comando dal terminale.
gcloud components update
Importazione delle librerie client di Cloud
Per utilizzare la libreria client di Cloud Tasks con l'app App Engine:
Specifica la dipendenza della libreria client di Cloud Tasks nel file
pom.xml
:<dependency> <groupId>com.google.cloud</groupId> <artifactId>google-cloud-tasks</artifactId> <version>1.3.0</version> </dependency>
Importa le dipendenze della libreria client di Cloud Tasks nei file responsabili della creazione e dell'accodamento delle attività:
import com.google.cloud.tasks.v2.AppEngineHttpRequest; import com.google.cloud.tasks.v2.CloudTasksClient; import com.google.cloud.tasks.v2.HttpMethod; import com.google.cloud.tasks.v2.QueueName; import com.google.cloud.tasks.v2.Task;
Creazione e gestione delle code
Questa sezione descrive come creare e gestire le code utilizzando l'API Cloud Tasks.
Con Cloud Tasks, non utilizzi un file queue.yaml
per creare
o gestire le code. Utilizza invece l'API Cloud Tasks. Non è consigliabile utilizzare un file queue.yaml
e l'API Cloud Tasks, ma potrebbe essere una parte inevitabile della migrazione dalle code di attività a Cloud Tasks, a seconda dell'applicazione. Per informazioni sulle best practice, consulta Utilizzare la gestione delle code rispetto alla coda.yaml.
Creazione di code
Leggi questa sezione se la tua app crea code in modo programmatico o se vuoi creare code aggiuntive dalla riga di comando.
In Cloud Tasks, i nomi delle code hanno il formato
projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
. La porzione LOCATION_ID
del nome della coda corrisponde a una regione di Google Cloud. La parte QUEUE_ID
del nome della coda equivale al campo name
della coda delle code di attività. Il nome della coda viene generato durante la creazione della coda in base al progetto, alla regione e ai QUEUE_ID
specificati.
In generale, la posizione della coda (regione) deve corrispondere a quella dell'app. Le due eccezioni a questa regola riguardano le app che utilizzano la regione europe-west
e le app che utilizzano la regione us-central
. In Cloud Tasks,
queste regioni sono chiamate rispettivamente europe-west1
e us-central1
.
Puoi specificare una configurazione facoltativa della coda durante la creazione della coda, ma puoi anche farlo aggiornando la coda dopo averla creata.
Non è necessario ricreare le code esistenti. Esegui invece la migrazione del codice che interagisce con le code esistenti leggendo le parti pertinenti di questa guida.
Riutilizzo dei nomi di coda
Devi attendere 7 giorni dopo l'eliminazione di una coda per crearne una con lo stesso ID coda nello stesso progetto e nella stessa località (ad esempio, regione).
L'esempio seguente crea due code utilizzando Cloud Tasks. La prima coda ha l'ID queue-blue
ed è configurata per inviare tutte le attività alla versione v2
del servizio task-module
a una frequenza di 5/s
. La seconda
coda ha l'ID coda queue-red
e invia le attività a una frequenza di 1/s
. Entrambe vengono create nel progetto con ID progetto your-project-id
nella località us-central1
.
È l'equivalente di Cloud Tasks della creazione di code nelle code di attività.
gcloud
gcloud CLI deduce il progetto e la posizione dalla configurazione di gcloud CLI.
gcloud tasks queues create queue-blue \ --max-dispatches-per-second=5 \ --routing-override=service:task-module,version:v2
gcloud tasks queues create queue-red \ --max-dispatches-per-second=1
libreria client
Per saperne di più, consulta l'articolo di riferimento di Cloud Tasks sulla creazione di una coda di Cloud Tasks.
Impostare la frequenza di elaborazione della coda
La tabella seguente elenca i campi che differiscono dalle code di attività a Cloud Tasks.
Campo Code di attività | Campo Cloud Tasks | Descrizione |
---|---|---|
rate |
max_dispatches_per_second |
La frequenza massima con cui le attività vengono inviate dalla coda |
max_concurrent_requests |
max_concurrent_dispatches |
Il numero massimo di attività simultanee che è possibile inviare dalla coda |
bucket_size |
max_burst_size |
Cloud Tasks calcola una proprietà get-only
Per le code App Engine create o aggiornate utilizzando un
file |
total_storage_limit |
Deprecato in Cloud Tasks | Cloud Tasks non supporta l'impostazione di un limite di spazio di archiviazione personalizzato |
Puoi impostare la frequenza di elaborazione della coda quando crei la coda o la aggiorni in seguito. L'esempio seguente utilizza Cloud Tasks per impostare la frequenza di elaborazione su una coda denominata queue-blue
già creata. Se queue-blue
è stato creato o configurato utilizzando un file queue.yaml
, il seguente esempio viene reimpostatomax_burst_size
in base al valore max_dispatches_per_second
di 20
. Questo è l'equivalente di Cloud Tasks dell'impostazione della frequenza di elaborazione delle code nelle code di attività.
gcloud
gcloud tasks queues update queue-blue \ --max-dispatches-per-second=20 \ --max-concurrent-dispatches=10
libreria client
Per ulteriori informazioni, consulta Definire i limiti di frequenza.
Disabilitazione e ripristino delle code
Cloud Tasks utilizza il termine pause, così come il termine disable per le code di attività. Mettendo in pausa una coda, le attività in coda non verranno più eseguite finché la coda non riprende. Tuttavia, puoi continuare ad aggiungere attività a una coda in pausa. Cloud Tasks utilizza il termine riprendi come fa le code di attività.
L'esempio seguente mette in pausa una coda con ID coda
queueName
. Questo è l'equivalente di Cloud Tasks della disattivazione delle code nelle code di attività.
gcloud
gcloud tasks queues pause queueName
libreria client
Per saperne di più, consulta l'articolo di riferimento di Cloud Tasks Messa in pausa delle code.
Eliminazione delle code in corso...
Una volta eliminata una coda, devi attendere 7 giorni prima di creare una coda con lo stesso nome. Valuta la possibilità di eliminare tutte le attività da una coda e riconfigurare la coda se non puoi attendere 7 giorni.
Nell'esempio seguente viene eliminata la coda con ID coda
foo
. Questo è l'equivalente di Cloud Tasks dell'eliminazione delle code nelle code di attività.
gcloud
gcloud tasks queues delete foo
libreria client
Per saperne di più, consulta l'articolo di riferimento di Cloud Tasks sull'eliminazione delle code.
Creazione e gestione delle attività
Questa sezione descrive come creare e gestire le attività utilizzando l'API Cloud Tasks.
Creazione di attività
La tabella seguente elenca i campi che differiscono dalle code di attività a Cloud Tasks.
Campo Code di attività | Campo Cloud Tasks | Descrizione |
---|---|---|
NOVITÀ in Cloud Tasks | app_engine_http_request |
Crea una richiesta che ha come target un servizio App Engine. Queste attività sono chiamate attività di App Engine. |
method |
http_method |
Specifica il metodo di richiesta, ad esempio POST |
url |
relative_uri |
Specifica il gestore delle attività. Nota la differenza nella lettera finale:
i per Uniform Resource Locator anziché
l per Uniform Resource Locator |
target |
app_engine_routing |
Facoltativo. Specifica service , version e instance di App Engine per un'attività App Engine. Se non viene configurato, vengono utilizzati il servizio, la versione e l'istanza predefiniti. |
L'esempio seguente crea un'attività che instrada al gestore /worker
sul servizio App Engine
predefinito. Si tratta dell'equivalente di Cloud Tasks alla creazione di attività nelle code di attività.
gcloud
gcloud tasks create-app-engine-task --queue=default \ --method=POST --relative-uri=/worker?key=key
libreria client
Per saperne di più, consulta la documentazione di Cloud Tasks sulla creazione di attività App Engine.
Specificare il servizio e il routing di destinazione
La specifica del servizio, della versione e dell'istanza di destinazione di App Engine per le attività di App Engine è facoltativa. Per impostazione predefinita, le attività di App Engine vengono instradate al servizio, alla versione e all'istanza che sono le impostazioni predefinite al momento del tentativo dell'attività.
Imposta la proprietà app_engine_routing
dell'attività durante la creazione per specificare un servizio, una versione o un'istanza di App Engine differente per l'attività.
Per indirizzare tutte le attività di una determinata coda allo stesso servizio, alla stessa versione e alla stessa istanza di App Engine, puoi impostare la proprietà app_engine_routing_override
nella coda.
Per saperne di più, consulta l'articolo di riferimento di Cloud Tasks sulla configurazione del routing.
Trasferimento dei dati al gestore
Come per le code di attività, puoi passare i dati al gestore in due modi utilizzando Cloud Tasks. Puoi passare i dati come parametri di query nell'URI relativo oppure puoi passare i dati nel corpo della richiesta utilizzando i metodi HTTP POST o PUT.
Cloud Tasks utilizza il termine body nello stesso modo in cui Code di attività utilizza il termine body. In Cloud Tasks, il tipo di contenuto del corpo predefinito è un flusso ottetto anziché testo normale. Puoi impostare il tipo di contenuti del corpo specificandolo nell'intestazione.
L'esempio seguente passa una chiave al gestore
/worker
in due modi diversi. Questo è l'equivalente di Cloud Tasks del passaggio dei dati al gestore nelle code di attività.
console
gcloud tasks create-app-engine-task --queue=default --method=GET \ --relative-uri= /worker ?key=blue --routing=service:worker
gcloud tasks create-app-engine-task --queue=default --method=POST \ --relative-uri= /worker --routing=service:worker \ --body-content="{'key': 'blue'}"
libreria client
Attività di denominazione
Specificare il nome dell'attività è facoltativo. Se non specifichi il nome dell'attività, Cloud Tasks lo costruisce per te generando un ID attività e deducendo il progetto e la località (ad esempio, la regione) in base alla coda specificata durante la creazione dell'attività.
I nomi delle attività hanno il formato
projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID
. La parte TASK_ID
del nome dell'attività equivale al campo name
dell'attività Code di attività.
Riutilizzo dei nomi delle attività
Devi attendere prima di riutilizzare il nome di un'attività. La quantità di tempo che devi attendere prima di farlo varia a seconda che la coda che invia l'attività sia stata creata in Cloud Tasks o nelle code di attività.
Per le attività nelle code create utilizzando le code di attività (compresa la coda predefinita), devi attendere circa 9 giorni dopo l'eliminazione o l'esecuzione dell'attività originale. Per le attività nelle code create utilizzando Cloud Tasks, devi attendere circa un'ora dopo l'eliminazione o l'esecuzione dell'attività originale.
L'esempio seguente crea un'attività con TASK_ID
impostato su first-try
e la aggiunge alla coda predefinita. Questo è l'equivalente di Cloud Tasks delle attività di denominazione nelle code di attività.
gcloud
gcloud CLI crea il nome dell'attività deducendo il progetto e la posizione dalla tua configurazione.
gcloud tasks create-app-engine-task first-try --queue=default \ --method=GET --relative-uri= /worker
libreria client
Con la libreria client, devi specificare il nome completo dell'attività se vuoi indicare TASK_ID
. Il progetto e la località devono corrispondere al progetto e alla località della coda a cui viene aggiunta l'attività.
Nuovo tentativo di attività non riuscite
Puoi impostare la configurazione dei nuovi tentativi delle attività nelle code durante la creazione delle code o aggiornando la coda. La tabella seguente elenca il campo Code attività e il campo Cloud Tasks corrispondente.
Campo Code di attività | Campo Cloud Tasks |
---|---|
task_retry_limit |
max_attempts |
task_age_limit |
max_retry_duration |
min_backoff_seconds |
min_backoff |
max_backoff_seconds |
max_backoff |
max_doublings |
max_doublings |
Parametri dei nuovi tentativi specifici per l'attività
I parametri di ripetizione specifici per le attività che sono stati configurati nelle code di attività funzionano in Cloud Tasks, ma non puoi modificarli o impostarli su nuove attività. Per modificare i parametri dei nuovi tentativi per un'attività che ha parametri di ripetizione specifici dell'attività, ricrea l'attività con una coda di Cloud Tasks che abbia i parametri desiderati per i nuovi tentativi.
L'esempio seguente illustra vari scenari di nuovo tentativo:
- In
fooqueue
, vengono riprovati le attività per un massimo di sette volte e per un massimo di due giorni dal primo tentativo di esecuzione. Dopo il superamento di entrambi i limiti, l'errore interessa definitivamente. - In
barqueue
, App Engine tenta di riprovare le attività, aumentando l'intervallo in modo lineare tra un nuovo tentativo e l'altro fino a raggiungere il backoff massimo e riprovando all'intervallo massimo (quindi gli intervalli tra le richieste sono di 10, 20, 30 secondi, ..., 190, 200, 200 secondi e così via). - In
bazqueue
, l'intervallo tra i nuovi tentativi inizia da 10 secondi, poi raddoppia tre volte, quindi aumenta in modo lineare e infine riprova all'infinito nell'intervallo massimo (quindi gli intervalli tra le richieste sono 10, 20, 40, 80, 160, 240, 300, 300 secondi e così via).
Questo è l'equivalente di Cloud Tasks del ritentamento delle attività nelle code di attività.
gcloud
Quando imposti opzioni che specificano un numero di secondi, devi includere s
dopo il numero intero (ad es. 200s
non 200
).
gcloud tasks queues create fooqueue \ --max-attempts=7 \ --max-retry-duration=172800s #2*60*60*24 seconds in 2 days
gcloud tasks queues create barqueue \ --min-backoff=10s \ --max-backoff=200s \ --max-doublings=0
gcloud tasks queues create bazqueue \ --min-backoff=10s \ --max-backoff=300s \ --max-doublings=3
libreria client
Per saperne di più, consulta l'articolo di riferimento di Cloud Tasks Impostare i parametri per i nuovi tentativi.
Eliminazione di attività da una coda
Quando elimini un'attività, devi attendere 9 giorni prima di crearne una con lo stesso nome se l'attività si trovava in una coda creata utilizzando un file queue.yaml
o un'ora se l'attività si trovava in una coda creata con Cloud Tasks.
L'esempio seguente elimina l'attività con ID attività foo
dalla coda con
ID coda queue1
. È l'equivalente di Cloud Tasks
dell'eliminazione
delle attività
nelle code di attività.
gcloud
Il progetto e la località dell'attività vengono dedotti dal progetto predefinito gcloud CLI.
gcloud tasks delete foo --queue=queue1
libreria client
Per saperne di più, consulta l'articolo di riferimento di Cloud Tasks su Eliminazione di un'attività da una coda.
Eliminazione definitiva delle attività
L'esempio seguente elimina definitivamente tutte le attività dalla coda con ID coda
foo
. Questo è l'equivalente di Cloud Tasks dell'eliminazione definitiva delle attività nelle code di attività.
gcloud
Il progetto e la posizione della coda vengono dedotti dal progetto predefinito gcloud CLI.
gcloud tasks queues purge foo
libreria client
Per saperne di più, consulta la documentazione di Cloud Tasks sull'eliminazione definitiva di tutte le attività da una coda.
Esempio di Java 8 Cloud Tasks
L'esempio seguente è una configurazione di base per creare una coda e accodare un'attività con Cloud Tasks. Presuppone che lo sviluppatore abbia creato un file pom.xml
per specificare la dipendenza di Cloud Tasks, come descritto nella sezione Importazione della libreria client. Questo è l'equivalente di Cloud Tasks di un esempio di coda di attività Java 8 nelle code di attività.
Il file responsabile della creazione e dell'accodamento dell'attività crea un'attività e la aggiunge alla coda predefinita utilizzando la libreria client di Cloud Tasks:
Il file che definisce il worker gestisce l'attività:
Passaggi successivi
- Documentazione di Cloud Tasks
- Libreria client di Cloud Tasks
- Panoramica Riferimento REST di Cloud Tasks
- Panoramica di Riferimento RPC per Cloud Tasks