Migrazione delle code in modalità push a Cloud Tasks (Go)

Prima di eseguire l'upgrade alla versione più recente dell'SDK dei servizi App Engine, consulta la panoramica della migrazione.

Esegui l'upgrade alle librerie client di Cloud Tasks

Se preferisci abbandonare completamente i servizi in bundle legacy, puoi eseguire la migrazione del codice per utilizzare direttamente l'API Cloud Tasks. Per farlo, devi eseguire il refactoring del codice dell'applicazione.

Cloud Tasks ti consente di accedere allo stesso servizio a cui accedi con l'API RPC Task Queues. Ciò significa che non devi ricreare le code in modalità push e le attività push esistenti. Tuttavia, per utilizzare l'API Cloud Tasks, devi eseguire la migrazione del codice che crea o interagisce con le code in modalità push o le attività push.

Puoi creare e interagire con le code in modalità push e le attività push utilizzando le API REST e RPC di Cloud Tasks, la libreria client di Cloud Tasks , Google Cloud CLI e la Google Cloud console. Questa pagina fornisce esempi che utilizzano gcloud CLI e la libreria client di Cloud Tasks.

Funzionalità non disponibili in Cloud Tasks

Per la migrazione delle librerie client di 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 asincrona delle attività

In alternativa, se esegui l'upgrade all'SDK più recente, le funzionalità come le attività differite, gli spazi dei nomi e la simulazione locale sono supportate tramite il wrapper dell'SDK.

Prezzi e quote

La migrazione delle code in modalità push a Cloud Tasks potrebbe influire sui prezzi e sulle quote della tua app.

Prezzi

Prima di eseguire la migrazione, consulta i prezzi di Cloud Tasks per stimare il costo mensile.

Analogamente a Task Queues, l'invio di richieste alla tua app App Engine con una destinazione push di Cloud Tasks è senza costi. Tuttavia, a differenza di Task Queues, Cloud Tasks addebita le operazioni eseguite, come la creazione, l'eliminazione o la gestione delle attività. Ciò potrebbe comportare un costo mensile complessivo più elevato rispetto alla coda di attività di App Engine complementare.

Quote

Anche le richieste di Cloud Tasks vengono conteggiate ai fini delle quote delle richieste di App Engine.

Come Task Queues, Cloud Tasks ha quote specifiche del servizio. La migrazione a Cloud Tasks probabilmente modificherà le tue quote.

Prima di iniziare

Le sezioni seguenti illustrano i passaggi di configurazione prima di eseguire la migrazione delle code in modalità push a Cloud Tasks.

Esegui la migrazione delle code in modalità pull

Prima di iniziare, esegui la migrazione delle code in modalità pull prima di seguire le istruzioni riportate in questa guida per eseguire 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'utilizzo obbligatorio del file queue.yaml potrebbe causare un comportamento imprevisto con Cloud Tasks.

Proteggi la configurazione delle code

Una volta avviato il processo di migrazione a Cloud Tasks, la modifica del file queue.yaml può causare un comportamento imprevisto e non è consigliata. Proteggi la configurazione delle code dalle modifiche apportate dal file queue.yaml seguendo questi passaggi.

1. Configura gcloud CLI in modo che ometta il file queue.yaml nei deployment futuri.

   Aggiungi il file queue.yaml a un file .gcloudignore. Per verificare se hai già un file .gcloudignore, puoi eseguire il seguente comando nel terminale dalla directory di primo livello della tua app. Questo comando restituirà il nome del file se il file esiste.

   ls -a | grep .gcloudignore

   Per saperne di più sui file .gcloudignore, consulta la .gcloudignore documentazione di riferimento.

2. Limita le autorizzazioni per il file queue.yaml.

   Segui le best practice descritte nella nostra guida alla protezione della configurazione delle code.

3. Scopri di più su Cloud Tasks e sul 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, il che può causare un comportamento imprevisto. Per saperne di più, consulta Utilizzo della gestione delle code e queue.yaml.

Autentica la tua app nell'API Cloud Tasks

Devi autenticare la tua app nell'API Cloud Tasks. Questa sezione illustra l'autenticazione per due casi d'uso diversi.

Per sviluppare o testare l'app localmente, ti consigliamo di utilizzare un account di servizio. Per istruzioni sulla configurazione di un account di servizio e sul collegamento all'app, consulta Ottenere e fornire manualmente le credenziali dell'account di servizio.

Per eseguire il deployment dell'app su App Engine, non devi fornire alcuna nuova autenticazione. Le Credenziali predefinite dell'applicazione (ADC) deducono i dettagli di autenticazione per le app App Engine.

Importa le librerie client di Cloud

Per utilizzare la libreria client di Cloud Tasks con la tua app App Engine:

1. Scarica la dipendenza della libreria client di Cloud Tasks:

   go get cloud.google.com/go/cloudtasks/apiv2

2. Importa le dipendenze della libreria client di Cloud Tasks nei file responsabili della creazione e dell'accodamento delle attività:

   import (
     "context"
     "fmt"
   
     cloudtasks "cloud.google.com/go/cloudtasks/apiv2"
     taskspb "cloud.google.com/go/cloudtasks/apiv2/cloudtaskspb"
   )

Crea e gestisci le 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. Utilizzi invece l'API Cloud Tasks. L'utilizzo sia di un file a queue.yaml sia dell'API Cloud Tasks non è consigliato, ma potrebbe essere una parte inevitabile della migrazione da Task Queues a Cloud Tasks a seconda della tua app. Per scoprire le best practice, consulta Utilizzo della gestione delle code e queue.yaml.

Crea code

Leggi questa sezione se la tua app crea code a livello di programmazione 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 LOCATION_ID parte del nome della coda corrisponde a una Google Cloud regione. La parte QUEUE_ID del nome della coda è equivalente al campo name della coda di Task Queues. Il nome della coda viene generato durante la creazione della coda in base al progetto, alla regione e a QUEUE_ID che specifichi.

In generale, la località della coda (ovvero la regione) deve essere la stessa della regione della tua 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 la configurazione facoltativa della coda durante la creazione della coda, ma puoi anche farlo aggiornando la coda dopo la creazione.

Non devi ricreare le code esistenti. Esegui invece la migrazione del codice che interagisce con le code esistenti leggendo le parti pertinenti di questa guida.

Nota: il servizio Coda di attività di App Engine crea automaticamente una coda predefinita denominata default. Cloud Tasks non crea automaticamente questa coda.

Riutilizza i nomi delle code

Devi attendere 7 giorni dopo l'eliminazione di una coda per creare una coda con lo stesso ID coda nello stesso progetto e nella stessa località (ovvero regione).

L'esempio seguente crea due code utilizzando Cloud Tasks. La prima coda ha l'ID coda 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 l'ID progetto nella località us-central1. Questo è l'equivalente di Cloud Tasks della creazione di code in Task Queues.

gcloud

gcloud CLI deduce il progetto e la località 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

Per saperne di più, consulta la documentazione di riferimento di Cloud Tasks Creazione di una coda di Cloud Tasks.

Imposta la frequenza di elaborazione delle code

La tabella seguente elenca i campi che differiscono da Task Queues a Cloud Tasks.

Campo di Task Queues	Campo di 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 possono essere inviate dalla coda
bucket_size	max_burst_size	Cloud Tasks calcola una proprietà di sola lettura max_burst_size che limita la velocità di elaborazione delle attività nella coda in base al valore di max_dispatches_per_second. Questo campo consente alla coda di avere una frequenza elevata in modo che l'elaborazione inizi poco dopo l'accodamento di un'attività, ma limita comunque l'utilizzo delle risorse quando molte attività vengono accodate in un breve periodo di tempo. Per le code di App Engine create o aggiornate utilizzando un file, max_burst_size è inizialmente uguale a bucket_size. Tuttavia, se la coda viene successivamente passata a un update comando utilizzando qualsiasi interfaccia di Cloud Tasks, max_burst_size verrà reimpostato in base al valore di max_dispatches_per_second, indipendentemente dal fatto che max_dispatches_per_second venga aggiornato.
total_storage_limit	Ritirato in Cloud Tasks	Cloud Tasks non supporta l'impostazione di un limite di spazio di archiviazione personalizzato

Puoi impostare la frequenza di elaborazione delle code quando crei la coda o la aggiorni in un secondo momento. L'esempio seguente utilizza Cloud Tasks per impostare la frequenza di elaborazione su una coda denominata queue-blue già creata. Se queue-blue è stata creata o configurata utilizzando un file queue.yaml, l'esempio seguente reimposta max_burst_size in base al valore max_dispatches_per_second di 20. Questo è l'equivalente di Cloud Tasks di impostare la frequenza di elaborazione delle code rate in Task Queues.

gcloud

gcloud tasks queues update queue-blue \
    --max-dispatches-per-second=20 \
    --max-concurrent-dispatches=10

Per saperne di più, consulta Definire i limiti di frequenza.

Disattiva e riprendi le code

Cloud Tasks utilizza il termine pausa nello stesso modo in cui Task Queues utilizza il termine disattiva. La messa in pausa di una coda impedisce l'esecuzione delle attività nella coda fino a quando la coda non viene ripresa. Tuttavia, puoi continuare ad aggiungere attività a una coda in pausa. Cloud Tasks utilizza il termine riprendi nello stesso modo di Task Queues.

L'esempio seguente mette in pausa una coda con l'ID coda queue1. Questo è l'equivalente di Cloud Tasks della disattivazione delle code in Task Queues.

gcloud

gcloud tasks queues pause queue1

Per saperne di più, consulta la documentazione di riferimento di Cloud Tasks Mettere in pausa le code.

Elimina le code

Una volta eliminata una coda, devi attendere 7 giorni prima di creare una coda con lo stesso nome. Se non puoi attendere 7 giorni, valuta la possibilità di eliminare definitivamente tutte le attività da una coda e di riconfigurarla.

L'esempio seguente elimina la coda con l'ID coda queue1. Questo è l'equivalente di Cloud Tasks dell' eliminazione delle code in Task Queues.

gcloud

gcloud tasks queues delete queue1

Per saperne di più, consulta la documentazione di riferimento di Cloud Tasks Eliminare le code.

Crea e gestisci le attività

Questa sezione descrive come creare e gestire le attività utilizzando l'API Cloud Tasks.

Crea attività

La tabella seguente elenca i campi che differiscono da Task Queues a Cloud Tasks.

Campo di Task Queues	Campo di Cloud Tasks	Descrizione
N/D	app_engine_http_request	Crea una richiesta che ha come target un servizio App Engine. Queste attività sono chiamate attività App Engine.
method	http_method	Specifica il metodo di richiesta, ad esempio POST
url	relative_uri	Specifica il gestore delle attività. Tieni presente la differenza nell'ultima lettera: i per uniform resource identifier 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 impostati, vengono utilizzati il servizio, versione e l'istanza predefiniti.

L'esempio seguente crea un'attività che esegue il routing al gestore /update_counter nel servizio App Engine predefinito. Questo è l'equivalente di Cloud Tasks della creazione di attività in Task Queues.

gcloud

gcloud tasks create-app-engine-task \
    --queue=default \
    --method=POST \
    --relative-uri=/update_counter \
    --routing=service:worker \
    --body-content=10

Per saperne di più, consulta la documentazione di riferimento di Cloud Tasks Creare attività App Engine.

Specifica il servizio di destinazione e il routing

La specifica del servizio, della versione e dell'istanza di destinazione di App Engine per le attività App Engine è facoltativa. Per impostazione predefinita, le attività App Engine vengono indirizzate al servizio, alla versione e all'istanza predefiniti al momento del tentativo di esecuzione dell'attività.

Imposta la proprietà app_engine_routing dell'attività durante la creazione dell'attività per specificare un servizio, una versione o un'istanza di App Engine diversa 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 la documentazione di riferimento di Cloud Tasks Configurare il routing.

Passa i dati al gestore

Come per Task Queues, puoi passare i dati al gestore in due modi utilizzando Cloud Tasks. Puoi passare i dati come parametri di query nell'URI relativo oppure nel corpo della richiesta utilizzando i metodi HTTP POST o PUT.

Cloud Tasks utilizza il termine corpo nello stesso modo in cui Task Queues utilizza il termine payload. In Cloud Tasks, il tipo di contenuto del corpo predefinito è octet-stream anziché testo normale. Puoi impostare il tipo di contenuto del corpo specificandolo nell'intestazione.

L'esempio seguente passa una chiave al gestore /update_counter in due modi diversi. Questo è l'equivalente di Cloud Tasks del passaggio dei dati al gestore in Task Queues.

gcloud

gcloud tasks create-app-engine-task \
    --queue=default \
    --method=GET  \
    --relative-uri=/update_counter?key=blue \
    --routing=service:worker

gcloud tasks create-app-engine-task \
    --queue=default \
    --method=POST \
    --relative-uri=/update_counter \
    --routing=service:worker \
    --body-content="{'key': 'blue'}"

Specifica il nome dell'attività

La specifica del nome dell'attività è facoltativa. Se non specifichi il nome dell'attività, Cloud Tasks lo crea per te generando un ID attività e deducendo il progetto e la località (ovvero 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à è equivalente al campo name dell'attività di Task Queues.

Riutilizza i nomi delle attività

Devi attendere prima di riutilizzare il nome di un'attività. Il tempo di attesa prima di farlo varia a seconda che la coda che invia l'attività sia stata creata in Cloud Tasks o Task Queues.

Per le attività nelle code create utilizzando Task Queues (inclusa 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 1 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 della denominazione delle attività in Task Queues.

gcloud

gcloud CLI crea il nome dell'attività deducendo il progetto e la località dalla configurazione.

gcloud tasks create-app-engine-task first-try \
    --queue=default \
    --method=GET \
    --relative-uri=/url/path

Riprova le attività non riuscite

Puoi impostare la configurazione dei nuovi tentativi delle attività nelle code durante la creazione della coda o aggiornandola. La tabella seguente elenca il campo di Task Queues e il campo di Cloud Tasks corrispondente.

Campo di Task Queues	Campo di 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

Utilizza i parametri di nuovi tentativi specifici per l'attività

I parametri di nuovi tentativi specifici per l'attività configurati in Task Queues funzionano in Cloud Tasks, ma non puoi modificarli o impostarli per le nuove attività. Per modificare i parametri di nuovi tentativi per un'attività con parametri di nuovi tentativi specifici per l'attività, ricrea l'attività con una coda di Cloud Tasks che abbia i parametri di nuovi tentativi desiderati.

L'esempio seguente illustra vari scenari di nuovi tentativi:

• In fooqueue, le attività vengono ritentate fino a sette volte e per un massimo di due giorni dal primo tentativo di esecuzione. Una volta superati entrambi i limiti, l'operazione non riesce in modo permanente.
• In barqueue, App Engine tenta di ritentare le attività, aumentando linearmente l'intervallo tra ogni nuovo tentativo fino a raggiungere il backoff massimo e ritentando indefinitamente all'intervallo massimo (quindi gli intervalli tra le richieste sono 10 secondi, 20 secondi, 30 secondi, ..., 190 secondi, 200 secondi, 200 secondi, ...).
• In bazqueue, l'intervallo tra i tentativi inizia a 10 secondi, quindi raddoppia tre volte, poi aumenta linearmente e infine ritenta indefinitamente all'intervallo massimo (quindi gli intervalli tra le richieste sono 10 secondi, 20 secondi, 40 secondi, 80 secondi, 160 secondi, 240 secondi, 300 secondi, 300 secondi, ...).

Questo è l'equivalente di Cloud Tasks dei nuovi tentativi delle attività in Task Queues.

gcloud

Quando imposti le opzioni che specificano un numero di secondi, devi includere s dopo il numero intero (ad es. 200s anziché 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

Per saperne di più, consulta la documentazione di riferimento di Cloud Tasks Impostare i parametri di nuovi tentativi.

Elimina le attività da una coda

Quando elimini un'attività, devi attendere 9 giorni prima di creare un'attività con lo stesso nome se l'attività si trovava in una coda creata utilizzando un file queue.yaml o 1 ora se l'attività si trovava in una coda creata utilizzando Cloud Tasks.

L'esempio seguente elimina l'attività con l'ID attività foo dalla coda con l'ID coda queue1. Questo è l'equivalente di Cloud Tasks dell' eliminazione delle attività in Task Queues.

gcloud

Il progetto e la località dell'attività vengono dedotti dal progetto predefinito di gcloud CLI.

gcloud tasks delete foo --queue=queue1

Per saperne di più, consulta la documentazione di riferimento di Cloud Tasks Eliminare un'attività da una coda.

Elimina definitivamente le attività

L'esempio seguente elimina definitivamente tutte le attività dalla coda con l'ID coda queue1. Questo è l' equivalente di Cloud Tasks dell' eliminazione definitiva delle attività in Task Queues.

gcloud

Il progetto e la località della coda vengono dedotti dal progetto predefinito di gcloud CLI.

gcloud tasks queues purge queue1

Per saperne di più, consulta la documentazione di riferimento di Cloud Tasks Eliminare definitivamente tutte le attività da una coda.

Passaggi successivi

• Documentazione di Cloud Tasks
• Libreria client di Cloud Tasks
• Panoramica della documentazione di riferimento REST di Cloud Tasks
• Panoramica della documentazione di riferimento RPC di Cloud Tasks