Prima di eseguire la migrazione alle librerie client di Cloud Tasks, 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. Ciò richiede il refactoring del codice dell'applicazione.
Con Cloud Tasks, accedi allo stesso servizio a cui accedi con l'API RPC delle code di attività. 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 console Google Cloud . Questa pagina fornisce esempi di utilizzo di gcloud CLI e della 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:
- Inserimento in coda delle attività nelle transazioni Datastore
- Utilizzo della libreria di attività differite anziché di un servizio worker
- Utilizzo delle attività nelle applicazioni multi-tenant
- Simulazione con il server di sviluppo locale
- Aggiunta di attività in modo asincrono
In alternativa, se esegui l'upgrade all'SDK più recente, 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
Consulta i prezzi di Cloud Tasks per stimare il costo mensile prima della migrazione.
Analogamente alle code di attività, l'invio di richieste alla tua app App Engine con un target push di Cloud Tasks è senza costi. Tuttavia, a differenza delle code di attività, Cloud Tasks addebita i costi per 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 senza costi.
Se esegui la migrazione eseguendo l'upgrade dell'SDK dei servizi App Engine e la tua applicazione inserisce in coda le attività transazionali all'interno delle transazioni Datastore, ogni attività in coda comporta 3 scritture, 2 letture e 1 eliminazione in Datastore oltre alla fatturazione standard dell'API Cloud Tasks.
Quote
Le richieste di Cloud Tasks vengono conteggiate anche ai fini delle quote delle richieste di App Engine.
Come le code di attività, Cloud Tasks ha quote specifiche per il servizio. La migrazione a Cloud Tasks probabilmente modificherà le tue quote.
Prima di iniziare
Se non l'hai ancora fatto, configura il tuo ambiente di sviluppo Python per utilizzare una versione di Python compatibile con Google Cloude installa gli strumenti di test per creare ambienti Python isolati.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 della coda
Una volta avviato il processo di migrazione a Cloud Tasks, la modifica del file queue.yaml può causare un comportamento imprevisto e non è consigliata. Per proteggere la configurazione della coda dalle modifiche apportate dal file queue.yaml, segui questi passaggi.
Configura gcloud CLI in modo da omettere il file
queue.yamlnei deployment futuri.Aggiungi il file
queue.yamla un file.gcloudignore. Per verificare se hai già un file.gcloudignore, puoi eseguire il comando seguente nel terminale dalla directory di primo livello della tua app. Questo comando restituirà il nome file se il file esiste.ls -a | grep .gcloudignore
Per scoprire di più sui file
.gcloudignore, consulta la documentazione di riferimento di.gcloudignore.Limita le autorizzazioni per il file
queue.yaml.Segui le best practice descritte nella nostra guida sulla protezione della configurazione delle code.
Scopri di più su Cloud Tasks e sul file
queue.yaml(facoltativo).Quando utilizzi l'API Cloud Tasks per gestire la configurazione della coda, il deployment di un file
queue.yamlsostituisce la configurazione impostata da Cloud Tasks, il che può causare un comportamento imprevisto. Per saperne di più, consulta Utilizzo della gestione delle code rispetto a 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 diversi casi d'uso.
Per sviluppare o testare la tua app localmente, ti consigliamo di utilizzare un account di servizio. Per istruzioni sulla configurazione di un service account e sulla sua connessione alla tua app, leggi Ottenere e fornire manualmente le credenziali dell'account di servizio.
Per eseguire il deployment della tua app su App Engine, non devi fornire una 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:
Aggiorna il file
app.yaml. Segui le istruzioni per la tua versione di Python:Python 2
Per le app Python 2, aggiungi le versioni più recenti delle librerie
grpcioesetuptools.Ecco un esempio di file
app.yaml:runtime: python27 threadsafe: yes api_version: 1 libraries: - name: grpcio version: latest - name: setuptools version: latestPython 3
Per le app Python 3, specifica l'elemento
runtimenel fileapp.yamlcon una versione di Python 3 supportata. Ad esempio:runtime: python310 # or another support versionIl runtime Python 3 installa automaticamente le librerie, quindi non è necessario specificare le librerie integrate del runtime Python 2 precedente. Se la tua app Python 3 utilizza altri servizi in bundle legacy durante la migrazione, puoi continuare a specificare le librerie integrate necessarie. In caso contrario, puoi eliminare le righe non necessarie nel file
app.yaml.Aggiorna il file
requirements.txt. Segui le istruzioni per la tua versione di Python:Python 2
Aggiungi le librerie client di Cloud per Cloud Tasks all'elenco delle dipendenze nel file
requirements.txt.google-cloud-tasksPoi esegui
pip install -t lib -r requirements.txtper aggiornare l'elenco delle librerie disponibili per la tua app.Python 3
Aggiungi le librerie client di Cloud per Cloud Tasks all'elenco delle dipendenze nel file
requirements.txt.google-cloud-tasksApp Engine installa automaticamente queste dipendenze durante il deployment dell'app nel runtime Python 3, quindi elimina la cartella
lib, se esiste.Per le app Python 2, se la tua app utilizza librerie integrate o copiate, devi specificare i relativi percorsi nel file
appengine_config.py, che si trova nella stessa cartella del fileapp.yaml:import pkg_resources from google.appengine.ext import vendor # Set PATH to your libraries folder. PATH = 'lib' # Add libraries installed in the PATH folder. vendor.add(PATH) # Add libraries to pkg_resources working set to find the distribution. pkg_resources.working_set.add_entry(PATH)Il file
appengine_config.pypresuppone che la directory di lavoro corrente sia quella in cui si trova la cartellalib. In alcuni casi, ad esempio i test unitari, la directory di lavoro corrente può essere diversa. Per evitare errori, puoi passare esplicitamente il percorso completo alla cartellalibutilizzando:import os path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'lib')
Importa la libreria client di Cloud Tasks in tutti i file che utilizzano le code in modalità push dall'API Task Queues:
from google.cloud import tasks
Dopo aver completato la migrazione completa di tutto il codice che crea o interagisce con le code in modalità push in Cloud Tasks, rimuovi le istruzioni che importano l'API Task Queues, ad esempio
from google.appengine.api import taskqueue.
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. Utilizza invece l'API Cloud Tasks. L'utilizzo di un file queue.yaml e dell'API Cloud Tasks non è consigliato, ma potrebbe essere una parte inevitabile della migrazione dalle code di attività a Cloud Tasks, a seconda dell'app. Leggi Utilizzo della gestione delle code rispetto a queue.yaml per scoprire le best practice.
Crea 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 parte LOCATION_ID del nome della coda corrisponde a una regione Google Cloud . La parte QUEUE_ID del nome della coda equivale al campo name della coda di attività. Il nome della coda viene generato durante la creazione della coda in base al progetto, alla regione e al QUEUE_ID specificati.
In generale, la località della coda (ovvero la regione) deve essere la stessa 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 una configurazione facoltativa della coda durante la creazione della coda, ma puoi anche farlo aggiornando la coda dopo la sua creazione.
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.
Riutilizza i nomi delle code
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à (ovvero nella stessa 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. Entrambi vengono creati nel progetto con ID progetto my-project-id nella località us-central1.
Questo è l'equivalente di Cloud Tasks della creazione di code in Code di attività.
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
libreria client
Per saperne di più, consulta la documentazione di riferimento di Cloud Tasks Creazione di una coda di attività di Cloud Tasks.
Imposta la frequenza di elaborazione della coda
La tabella seguente elenca i campi che differiscono tra le code di attività e Cloud Tasks.
| Campo Code di attività | Campo Cloud Tasks | Descrizione |
|---|---|---|
rate |
max_dispatches_per_second |
La frequenza massima di invio delle attività 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
Per le code di 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 archiviazione personalizzato |
Puoi impostare la frequenza di elaborazione della coda quando la crei o aggiornarla
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 è stato creato o configurato 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 in Cloud Tasks dell'impostazione della frequenza di elaborazione della coda nelle code di attività.
gcloud
gcloud tasks queues update queue-blue \ --max-dispatches-per-second=20 \ --max-concurrent-dispatches=10
libreria client
Per saperne di più, consulta Definisci i limiti di frequenza.
Disattivazione e ripresa delle code
Cloud Tasks utilizza il termine metti in pausa nello stesso modo in cui le code di attività utilizzano il termine disattiva. La messa in pausa di una coda interrompe l'esecuzione delle attività nella coda fino alla ripresa della coda. Tuttavia, puoi continuare ad aggiungere attività a una coda in pausa. Cloud Tasks utilizza il termine riprendi nello stesso modo di Code di attività.
L'esempio seguente mette in pausa una coda con ID coda queue1. Questo è l'equivalente in Cloud Tasks della disattivazione delle code in Code di attività.
gcloud
gcloud tasks queues pause queue1
libreria client
Per saperne di più, consulta la documentazione di riferimento di Cloud Tasks Metti in pausa le code.
Elimina code
Una volta eliminata una coda, devi attendere 7 giorni prima di crearne una con lo stesso nome. Se non puoi attendere 7 giorni, valuta la possibilità di eliminare definitivamente tutte le attività da una coda e riconfigurare la coda.
L'esempio seguente elimina la coda con ID coda queue1. Questo è l'equivalente in Cloud Tasks dell'eliminazione delle code in Code di attività.
gcloud
gcloud tasks queues delete queue1
libreria client
Per saperne di più, consulta la documentazione di riferimento di Cloud Tasks Eliminazione delle code.
Creare e gestire attività
Questa sezione descrive come creare e gestire le attività utilizzando l'API Cloud Tasks.
Creare attività
La tabella seguente elenca i campi che differiscono tra le code di attività e Cloud Tasks.
| Campo Code di attività | Campo 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à 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 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 vengono impostati, vengono utilizzati il servizio, la versione e l'istanza predefiniti. |
L'esempio seguente crea un'attività che indirizza a un servizio App Engine denominato worker con il gestore /update_counter. Questo è l'equivalente di Cloud Tasks per la creazione di attività nelle code di attività.
gcloud
gcloud tasks create-app-engine-task \ --queue=default \ --method=POST \ --relative-uri=/update_counter \ --routing=service:worker \ --body-content=10
libreria client
Per saperne di più, consulta la documentazione di riferimento di Cloud Tasks Creazione di attività App Engine.
Specifica il servizio e il routing di destinazione
La specifica del servizio, della versione e dell'istanza App Engine di destinazione per le attività App Engine è facoltativa. Per impostazione predefinita, le attività di 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 per specificare un servizio, una versione o un'istanza App Engine diversi per l'attività.
Per instradare 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 sulla coda.
Per saperne di più, consulta la documentazione di riferimento di Cloud Tasks Configura il routing.
Passa i 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 o nel corpo della richiesta utilizzando i metodi HTTP POST o PUT.
Cloud Tasks utilizza il termine corpo nello stesso modo in cui le code di attività utilizzano 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 in Cloud Tasks del passaggio dei dati al gestore nelle code di attività.
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'}"
libreria client
Specifica il nome dell'attività
La specifica del nome dell'attività è facoltativa. Se non specifichi il nome dell'attività, Cloud Tasks lo crea 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à equivale al campo name dell'attività delle code di attività.
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 in Code di attività.
Per le attività nelle code create utilizzando le code di attività (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 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 per l'assegnazione di nomi alle attività nelle code di attività.
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
libreria client
Con la libreria client, devi specificare il nome completo dell'attività se vuoi specificare TASK_ID. Il progetto e la località devono corrispondere al progetto e alla località della coda a cui viene aggiunta l'attività.
Riprova le attività non riuscite
Puoi impostare la configurazione dei nuovi tentativi delle attività sulle code durante la creazione della coda o aggiornando la coda. La tabella seguente elenca il campo coda di 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 |
Utilizza parametri di ripetizione specifici per l'attività
I parametri di ripetizione specifici per le attività configurati nelle code di attività funzionano in Cloud Tasks, ma non puoi modificarli o impostarli per nuove attività. Per modificare i parametri di ripetizione per un'attività con parametri di ripetizione specifici, ricrea l'attività con una coda di Cloud Tasks che abbia i parametri di ripetizione desiderati.
L'esempio seguente mostra vari scenari di nuovi tentativi:
- In
fooqueue, i tentativi di esecuzione delle attività vengono ripetuti 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 va a buon fine definitivamente. - In
barqueue, App Engine tenta di riprovare le attività, aumentando l'intervallo in modo lineare tra ogni nuovo tentativo fino a raggiungere il backoff massimo e riprovando a tempo indeterminato all'intervallo massimo (quindi gli intervalli tra le richieste sono 10 s, 20 s, 30 s, …, 190 s, 200 s, 200 s, …). - In
bazqueue, l'intervallo tra i tentativi inizia a 10 secondi, poi raddoppia tre volte, quindi aumenta in modo lineare e infine i tentativi vengono ripetuti a tempo indeterminato all'intervallo massimo (quindi gli intervalli tra le richieste sono 10 s, 20 s, 40 s, 80 s, 160 s, 240 s, 300 s, 300 s…).
Questo è l'equivalente in Cloud Tasks della ripetizione dei tentativi di esecuzione delle attività in 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 la documentazione di riferimento di Cloud Tasks Imposta i parametri di ripetizione.
Elimina le 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 1 ora se l'attività si trovava in una coda creata utilizzando Cloud Tasks.
L'esempio seguente elimina l'attività con ID foo dalla coda con ID queue1. Questo è l'equivalente in Cloud Tasks dell'eliminazione delle attività nelle code di attività.
gcloud
Il progetto e la località dell'attività vengono dedotti dal progetto predefinito di gcloud CLI.
gcloud tasks delete foo --queue=queue1
libreria client
Per saperne di più, consulta la documentazione di riferimento di Cloud Tasks Eliminazione di un'attività da una coda.
Elimina definitivamente le attività
L'esempio seguente elimina definitivamente tutte le attività dalla coda con ID coda queue1. Questo è l'equivalente in Cloud Tasks dell'eliminazione definitiva delle attività in Code di attività.
gcloud
Il progetto e la località della coda vengono dedotti dal progetto predefinito di gcloud CLI.
gcloud tasks queues purge queue1
libreria client
Per saperne di più, consulta la sezione Eliminazione di tutte le attività da una coda del riferimento di Cloud Tasks.
Passaggi successivi
- Documentazione di Cloud Tasks
- Libreria client di Cloud Tasks
- Panoramica del riferimento REST di Cloud Tasks
- Panoramica del riferimento RPC di Cloud Tasks
- Per un tutorial, consulta il codelab Esegui la migrazione dalle code di attività di App Engine alle code in modalità push di Cloud Tasks.