I gestori di Cloud Tasks possono essere eseguiti su qualsiasi endpoint HTTP con un indirizzo IP esterno, come GKE, Compute Engine o anche un server web on-premise. Le tue attività possono essere eseguite su uno qualsiasi di questi servizi in modo affidabile e configurabile.
Questa pagina mostra come creare in modo programmatico attività di destinazione HTTP di base e inserirle nelle code di Cloud Tasks.
Per le attività con destinazioni HTTP (anziché i target espliciti di App Engine, che sono meno comuni), esistono due modi per creare attività:
Metodo
BufferTask
: utilizza questo metodo se la coda è configurata per eseguire il buffer delle attività davanti a un servizio. La coda deve avere il routing a livello di coda. Per la maggior parte dei casi d'uso, questo è l'approccio migliore. Questo approccio utilizza il metodoBufferTask
.Metodo
CreateTask
: è più complesso. Devi creare esplicitamente un oggetto attività. Utilizza questo metodo se le attività in coda hanno configurazioni di routing diverse. In questo caso, devi specificare il routing a livello di attività e non puoi utilizzare il routing a livello di coda. Questo approccio utilizza il metodoCreateTask
.
Creazione di attività di base (metodo BufferTask
)
Questa sezione illustra la creazione di un'attività mediante l'invio di una richiesta HTTP. Il metodo
utilizzato è chiamato BufferTask
.
Limitazioni
Il metodo BufferTask
è soggetto alle seguenti limitazioni:
Librerie client: il metodo
BufferTask
non è supportato nelle librerie client.API RPC: il metodo
BufferTask
non è supportato nell'API RPC.Routing a livello di attività: questo metodo non supporta il routing a livello di attività. Poiché non è possibile aggiungere informazioni di routing in questo modo quando si crea un'attività, è necessario utilizzare il routing a livello di coda (in caso contrario l'attività non ha informazioni di routing). Se la coda non utilizza già il routing a livello di coda, vedi Configurare il routing a livello di coda per le attività HTTP.
Chiama il metodo BufferTask
I seguenti esempi mostrano come creare un'attività inviando una richiesta POST
HTTP all'endpoint buffer
dell'API Cloud Tasks.
Python
curl
Il seguente snippet di codice mostra un esempio di creazione di attività utilizzando il
metodo BufferTask
utilizzando curl
:
curl -X HTTP_METHOD\ "https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID/tasks:buffer" \
Sostituisci quanto segue:
HTTP_METHOD
: il metodo HTTP per la tua richiesta, ad esempioGET
oPOST
.PROJECT_ID
: l'ID del tuo progetto Google Cloud. Puoi ottenerlo eseguendo questo comando nel terminale:gcloud config get-value project
LOCATION
: la posizione della coda.QUEUE_ID
: l'ID della coda.
Creazione di attività avanzata (metodo CreateTask
)
Questa sezione illustra la creazione di un'attività costruendo l'oggetto dell'attività. Usi
il metodo CreateTask
.
Quando crei un'attività utilizzando il metodo CreateTask
, crei e definisci in modo esplicito l'oggetto attività. Devi specificare il servizio e il gestore
che elaborano l'attività.
Se vuoi, puoi passare dati specifici dell'attività al gestore. Puoi anche ottimizzare la configurazione per l'attività, ad esempio pianificare un'ora futura in cui eseguire l'attività o limitare il numero di volte in cui vuoi che l'attività venga ritentata in caso di esito negativo (consulta Configurazione avanzata).
Gli esempi seguenti chiamano il metodo CreateTask
per creare un'attività utilizzando le librerie client di Cloud Tasks.
C#
Python
Prendi nota del file requirements.txt
:
Java
Prendi nota del file pom.xml
:
PHP
Prendi nota del file composer.json
:
Go
Node.js
Prendi nota del file package.json
:
Ruby
Configurazione degli account di servizio per l'autenticazione dei gestori di destinazione HTTP
Cloud Tasks può chiamare gestori di destinazione HTTP che richiedono l'autenticazione se hai un account di servizio con le credenziali appropriate per accedere al gestore.
Se disponi di un account di servizio attuale che vuoi utilizzare, puoi farlo. Devi solo assegnare i ruoli appropriati. Queste istruzioni illustrano la creazione di un nuovo account di servizio specifico per questa funzione. L'account di servizio nuovo o esistente utilizzato per l'autenticazione di Cloud Tasks deve trovarsi nello stesso progetto delle code di Cloud Tasks.
Nella console Google Cloud, vai alla pagina Account di servizio.
Se necessario, seleziona il progetto appropriato.
Fai clic su Crea account di servizio.
Nella sezione Dettagli account di servizio, assegna un nome all'account. La console crea un nome account email correlato per l'account. In questo modo puoi fare riferimento all'account. Puoi anche aggiungere una descrizione dell'account. Fai clic su Crea e continua.
Nella sezione Concedi a questo account di servizio l'accesso al progetto, fai clic su Seleziona un ruolo. Cerca e seleziona In coda di Cloud Tasks. Questo ruolo concede all'account di servizio l'autorizzazione per aggiungere attività alla coda.
Fai clic su + Aggiungi un altro ruolo.
Fai clic su Seleziona un ruolo. Cerca e seleziona Utente account di servizio. Questo ruolo consente all'account di servizio di autorizzare la coda a creare token per suo conto utilizzando le credenziali dell'account di servizio.
Se il tuo gestore fa parte di Google Cloud, concedi all'account di servizio il ruolo associato all'accesso al servizio su cui è in esecuzione il gestore. Ogni servizio all'interno di Google Cloud richiede un ruolo diverso. Ad esempio, per accedere a un gestore su Cloud Run è necessario il ruolo Invoker di Cloud Run e così via. Puoi utilizzare l'account di servizio che hai appena creato o qualsiasi altro account di servizio nel tuo progetto.
Fai clic su Fine per completare la creazione dell'account di servizio.
Cloud Tasks deve disporre di un account di servizio a cui è stato concesso il ruolo Cloud Tasks Service Agent
. In questo modo può generare token di intestazione in base alle credenziali associate all'account di servizio Cloud Tasks per l'autenticazione con la destinazione del gestore. L'account di servizio Cloud Tasks a cui viene concesso questo ruolo viene creato automaticamente al momento dell'abilitazione dell'API Cloud Tasks, a meno che non sia stata abilitata prima del 19 marzo 2019. In questo caso, dovrai aggiungere il ruolo manualmente.
Utilizzo di attività di destinazione HTTP con token di autenticazione
Per eseguire l'autenticazione tra Cloud Tasks e un gestore di destinazione HTTP che richiede questa autenticazione, Cloud Tasks crea un token di intestazione. Questo token si basa sulle credenziali nell'account di servizio Cloud Tasks Enqueuer
, identificato in base all'indirizzo email. L'account di servizio utilizzato per l'autenticazione deve far parte dello stesso progetto in cui si trova la coda di Cloud Tasks. La richiesta, con il token di intestazione, viene inviata dalla coda al gestore tramite HTTPS. Puoi utilizzare un token ID o un token di accesso.
I token ID in genere devono essere utilizzati per qualsiasi gestore in esecuzione su Google Cloud, ad esempio su Cloud Functions o Cloud Run. L'eccezione principale sono
le API di Google ospitate su *.googleapis.com
: queste API prevedono un token di accesso.
Puoi configurare l'autenticazione a livello di coda o di attività. Per configurare l'autenticazione a livello di coda, vedi Creare code di Cloud Tasks. Se l'autenticazione è configurata a livello di coda, questa configurazione sostituisce la configurazione a livello di attività. Per configurare l'autenticazione a livello di attività, specifica un token ID (OIDC) o un token di accesso (OAuth) nell'attività stessa.
Metodo BufferTask
Gli esempi seguenti utilizzano le credenziali predefinite dell'applicazione per l'autenticazione quando si utilizza il metodo BufferTask
per creare un'attività.
Python
Nel seguente esempio di codice, fornisci il valore del token di autenticazione.
curl
curl -X HTTP_METHOD\ "https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID/tasks:buffer" \ -H "Authorization: Bearer ACCESS_TOKEN"
Sostituisci quanto segue:
HTTP_METHOD
: il metodo HTTP per la tua richiesta, ad esempioGET
oPOST
.PROJECT_ID
: l'ID del tuo progetto Google Cloud. Puoi ottenerlo eseguendo questo comando nel terminale:gcloud config get-value project
LOCATION
: la posizione della coda.QUEUE_ID
: l'ID della coda.ACCESS_TOKEN
: il tuo token di accesso. Puoi ottenerlo eseguendo questo comando nel terminale:gcloud auth application-default login
gcloud auth application-default print-access-token
Metodo CreateTask
I seguenti esempi utilizzano il metodo CreateTask
con le librerie client di Cloud Tasks per creare un'attività che include anche la creazione di un token di intestazione. Negli esempi vengono utilizzati token ID.
Per utilizzare un token di accesso, sostituisci il parametro OIDC con il parametro OAuth appropriato per la lingua nella creazione della richiesta.
Python
Prendi nota del file requirements.txt
:
Java
Prendi nota del file pom.xml
:
Go
Node.js
Prendi nota del file package.json
:
Fornire i tuoi gestori di attività di destinazione HTTP
I gestori di attività target HTTP sono molto simili ai gestori di attività App Engine, con le seguenti eccezioni:
- Timeout: per tutti i gestori di attività di destinazione HTTP il timeout predefinito è 10 minuti, con un massimo di 30 minuti.
- Logica di autenticazione: se stai scrivendo il tuo codice nel servizio di destinazione per convalidare il token, devi utilizzare un token ID. Per ulteriori informazioni sulle implicazioni, consulta OpenID Connect, in particolare Convalida di un token ID.
Intestazioni: una richiesta di destinazione HTTP ha intestazioni impostate dalla coda, che contengono informazioni specifiche dell'attività che il gestore può utilizzare. Sono simili, ma non identiche, alle intestazioni impostate nelle richieste di attività di App Engine. Queste intestazioni forniscono solo informazioni. Non devono essere utilizzati come fonti di identità.
Se queste intestazioni erano presenti nella richiesta di un utente esterno alla tua app, vengono sostituite da quelle interne. L'unica eccezione riguarda le richieste da parte di amministratori dell'applicazione che hanno eseguito l'accesso, a cui è consentito impostare intestazioni a scopo di test.
Le richieste di destinazione HTTP contengono sempre le seguenti intestazioni:
Titolo Descrizione X-CloudTasks-QueueName
Il nome della coda. X-CloudTasks-TaskName
Il nome "breve" dell'attività o, se non è stato specificato alcun nome al momento della creazione, un ID univoco generato dal sistema. Questo è il valore my-task-id
nel nome dell'attività completa, ad esempio nome_attività =projects/my-project-id/locations/my-location/queues/my-queue-id/tasks/my-task-id
.X-CloudTasks-TaskRetryCount
Il numero di nuovi tentativi per questa attività. Per il primo tentativo, questo valore è 0
. Questo numero include i tentativi in cui l'attività non è riuscita a causa di codici di errore 5XX e non ha mai raggiunto la fase di esecuzione.X-CloudTasks-TaskExecutionCount
Il numero totale di volte in cui l'attività ha ricevuto una risposta dal gestore. Poiché Cloud Tasks elimina l'attività dopo aver ricevuto una risposta positiva, tutte le risposte precedenti del gestore sono risultate errori. Questo numero non include errori dovuti a codici di errore 5XX. X-CloudTasks-TaskETA
L'ora di pianificazione dell'attività, specificata in secondi dal 1° gennaio 1970. Inoltre, le richieste da Cloud Tasks potrebbero contenere le seguenti intestazioni:
Titolo Descrizione X-CloudTasks-TaskPreviousResponse
Il codice di risposta HTTP del tentativo precedente. X-CloudTasks-TaskRetryReason
Il motivo per cui hai eseguito di nuovo l'attività.
Aggiunta manuale del ruolo di Agente di servizio Cloud Tasks all'account di servizio Cloud Tasks
Questa operazione è necessaria solo se hai abilitato l'API Cloud Tasks prima del 19 marzo 2019.
Utilizzo della console
- Trova il numero del progetto nella pagina Impostazioni progetto di Google Cloud.
- Copia il numero.
- Apri la pagina della Console di amministrazione IAM.
- Fai clic su Concedi accesso. Si apre la schermata Concedi l'accesso.
Nella sezione Aggiungi entità, aggiungi un indirizzo email nel formato:
service-PROJECT_NUMBER@gcp-sa-cloudtasks.iam.gserviceaccount.com
Sostituisci PROJECT_NUMBER con il numero del tuo progetto qui sopra.
Nella sezione Assegna ruoli, cerca e seleziona Agente di servizio Cloud Tasks.
Fai clic su Salva.
Utilizzo di gcloud
Trova il numero del tuo progetto:
gcloud projects describe PROJECT_ID --format='table(projectNumber)'
Sostituisci PROJECT_ID con l'ID progetto.
Copia il numero.
Concedi all'account di servizio Cloud Tasks il ruolo
Cloud Tasks Service Agent
utilizzando il numero di progetto che hai copiato:gcloud projects add-iam-policy-binding PROJECT_ID --member serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudtasks.iam.gserviceaccount.com --role roles/cloudtasks.serviceAgent
Sostituisci PROJECT_ID con il tuo ID progetto e PROJECT_NUMBER con il numero del tuo progetto in alto.
Configurazione avanzata
Nell'attività puoi configurare una serie di attributi. Per un elenco completo, consulta la definizione delle risorse dell'attività.
Esempi di attributi che puoi personalizzare:
- Denominazione: se scegli di specificare un nome per l'attività, Cloud Tasks può utilizzare questo nome per garantire la deduplicazione delle attività, sebbene l'elaborazione necessaria a tal fine possa aumentare la latenza.
- Programmazione:puoi programmare un'attività in un momento futuro. Supportata solo per
CreateTask
(non supportata perBufferTask
) - Configurazione dei nuovi tentativi: configura il comportamento dei nuovi tentativi per un'attività se l'attività non riesce. Supportata solo per
CreateTask
(non supportata perBufferTask
)
Passaggi successivi
- Scopri di più sulle attività di destinazione HTTP, consulta il riferimento dell'API RPC.
- Scopri di più sulle attività di destinazione HTTP nel riferimento dell'API REST.