I gestori di Cloud Tasks possono essere eseguiti su qualsiasi endpoint HTTP con un indirizzo IP esterno, ad esempio GKE, Compute Engine o anche un server web on-premise. Le tue attività possono essere eseguite su uno di questi servizi in modo affidabile e configurabile.
Questa pagina mostra come creare ed eseguire programmaticamente attività target HTTP di base e inserirle nelle code Cloud Tasks.
Per le attività con target HTTP (a differenza dei target App Engine espliciti, meno comuni), esistono due modi per creare attività:
Metodo
BufferTask
: utilizza questo metodo se la coda è configurata per mettere in coda le attività prima di 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à nella coda hanno configurazioni di routing diverse. In questo caso, specifichi 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à inviando una richiesta HTTP. Il metodo
che utilizzi si chiama 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 instradamento durante la creazione di un'attività in questo modo, devi utilizzare l'instradamento a livello di coda (in caso contrario l'attività non avrà informazioni di instradamento). Se la coda non utilizza già il routing a livello di coda, consulta Configurare il routing a livello di coda per le attività HTTP.
Chiama il metodo BufferTask
Gli esempi riportati di seguito mostrano come creare un'attività inviando una richiesta POST
HTTP all'endpoint buffer
dell'API Cloud Tasks.
curl
Il seguente snippet di codice mostra un esempio di creazione di attività con 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 richiesta, ad esempioGET
oPOST
.PROJECT_ID
: l'ID del tuo Google Cloud progetto. Puoi ottenere questo valore eseguendo il seguente comando nel terminale:gcloud config get-value project
LOCATION
: la posizione della coda.QUEUE_ID
: l'ID della coda.
Python
Creazione di attività avanzata (metodo CreateTask
)
Questa sezione illustra la creazione di un'attività mediante la costruzione dell'oggetto task. Utilizzi il metodo CreateTask
.
Quando crei un'attività utilizzando il metodo CreateTask
, crei e definisci esplicitamente l'oggetto attività. Devi specificare il servizio e l'handler che elaborano
la task.
Se vuoi, puoi passare al gestore i dati specifici dell'attività. Puoi anche perfezionare la configurazione dell'attività, ad esempio pianificare un momento futuro in cui deve essere eseguita o limitare il numero di volte in cui vuoi che venga riprovato se non va a buon fine (consulta Configurazione avanzata).
Gli esempi riportati di seguito chiamano il metodo CreateTask
per creare un'attività utilizzando le librerie client Cloud Tasks.
C#
Vai
Java
Prendi nota del file pom.xml
:
Node.js
Prendi nota del file package.json
:
PHP
Prendi nota del file composer.json
:
Python
Prendi nota del file requirements.txt
:
Ruby
Configurazione degli account di servizio per l'autenticazione dei gestori target HTTP
Cloud Tasks può chiamare gestori target HTTP che richiedono l'autenticazione se disponi di un service account con le credenziali appropriate per accedere al gestore.
Se hai un account di servizio attuale che vuoi utilizzare, puoi farlo. Basta assegnare i ruoli appropriati. Queste istruzioni riguardano la creazione di un nuovo account di servizio specificamente per questa funzione. L'account di servizio esistente o nuovo utilizzato per l'autenticazione di Cloud Tasks deve trovarsi nello stesso progetto delle code 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 dell'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 Cloud Tasks Enqueuer. 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 gestore fa parte di Google Cloud, concedi all'account di servizio il ruolo associato all'accesso al servizio in cui è in esecuzione il gestore. Ogni servizio al suo interno Google Cloud richiede un ruolo diverso. Ad esempio, per accedere a un gestore su Cloud Run, concedi il ruolo Invoker di Cloud Run. Puoi utilizzare l'account di servizio appena creato o qualsiasi altro account di servizio nel progetto.
Fai clic su Fine per completare la creazione dell'account di servizio.
Cloud Tasks stesso deve avere un proprio 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 autenticarsi con il gestore target. L'account di servizio Cloud Tasks a cui è stato concesso questo ruolo viene creato automaticamente quando attivi l'API Cloud Tasks, a meno che non l'abbia attivato prima del 19 marzo 2019, nel qual caso devi aggiungere il ruolo manualmente.
Utilizzo di attività target HTTP con token di autenticazione
Per l'autenticazione tra Cloud Tasks e un gestore di target HTTP che richiede questa autenticazione, Cloud Tasks crea un token intestazione. Questo token si basa sulle credenziali nell'account di servizio Cloud Tasks Enqueuer
, identificato dal relativo indirizzo email. Il service account utilizzato per l'autenticazione deve far parte dello stesso progetto in cui risiede la coda Cloud Tasks. La richiesta, con il token di intestazione, viene inviata dalla coda all'handler tramite HTTPS. Puoi utilizzare un
token ID
o un token di accesso.
In genere, i token ID devono essere utilizzati per qualsiasi gestore in esecuzione su Google Cloud, ad esempio nelle funzioni Cloud Run o in Cloud Run. L'eccezione principale riguarda le API di Google ospitate su *.googleapis.com
: queste API richiedono un token di accesso.
Puoi configurare l'autenticazione a livello di coda o di attività. Per configurare l'autenticazione a livello di coda, consulta Creare code Cloud Tasks. Se l'autenticazione è configurata a livello di coda, questa configurazione ha la precedenza sulla 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 riportati di seguito utilizzano le credenziali predefinite dell'applicazione per l'autenticazione quando si utilizza il metodo BufferTask
per creare un'attività.
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 richiesta, ad esempioGET
oPOST
.PROJECT_ID
: l'ID del tuo Google Cloud progetto. Per farlo, esegui il seguente 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 ottenere questo valore eseguendo il seguente comando nel terminale:gcloud auth application-default login
gcloud auth application-default print-access-token
Python
Nel seguente esempio di codice, fornisci il valore del token di autenticazione.
Metodo CreateTask
Gli esempi riportati di seguito utilizzano il metodo CreateTask
con le librerie client Cloud Tasks per creare un'attività che include anche la creazione di un token 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 durante la creazione della richiesta.
Vai
Java
Prendi nota del file pom.xml
:
Node.js
Prendi nota del file package.json
:
Python
Prendi nota del file requirements.txt
:
Fornire i tuoi gestori delle attività target HTTP
I gestori delle attività di destinazione HTTP sono molto simili ai gestori delle attività App Engine, con le seguenti eccezioni:
- Timeout: per tutti i gestori delle attività target HTTP, il timeout predefinito è di 10 minuti, con un massimo di 30 minuti.
- Logica di autenticazione: se scrivi il tuo codice nel servizio di destinazione per convalidare il token, devi utilizzare un token ID. Per ulteriori informazioni su cosa comporta, consulta OpenID Connect, in particolare la pagina Convalida di un token ID.
Intestazioni: una richiesta di destinazione HTTP ha intestazioni impostate dalla coda, che contengono informazioni specifiche della task che il gestore può utilizzare. Sono simili, ma non identiche, alle intestazioni impostate sulle richieste di attività App Engine. Queste intestazioni forniscono solo informazioni. Non devono essere utilizzate come fonti di identità.
Se queste intestazioni erano presenti in una richiesta di un utente esterno alla tua app, vengono sostituite da quelle interne. L'unica eccezione riguarda le richieste degli amministratori dell'applicazione che hanno eseguito l'accesso e che sono autorizzati a impostare le intestazioni a scopo di test.
Le richieste target 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. Si tratta del valore my-task-id
nel nome completo dell'attività, ad esempio task_name =projects/my-project-id/locations/my-location/queues/my-queue-id/tasks/my-task-id
.X-CloudTasks-TaskRetryCount
Il numero di volte in cui è stato eseguito un nuovo tentativo 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 dall'handler. Poiché Cloud Tasks elimina l'attività dopo aver ricevuto una risposta positiva, tutte le risposte precedenti dell'handler sono state errori. Questo numero non include gli errori dovuti a codici di errore 5XX. X-CloudTasks-TaskETA
L'ora pianificata dell'attività, specificata in secondi dal 1° gennaio 1970. Inoltre, le richieste di 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 riprovare a eseguire l'attività.
Aggiunta manuale del ruolo Agente di servizio Cloud Tasks all'account di servizio Cloud Tasks
Questo passaggio è necessario solo se hai attivato l'API Cloud Tasks prima del 19 marzo 2019.
Console
- Trova il numero del progetto nella Google Cloud pagina Impostazioni progetto.
- 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 seguente formato:
service-PROJECT_NUMBER@gcp-sa-cloudtasks.iam.gserviceaccount.com
Sostituisci PROJECT_NUMBER con il numero del tuo Google Cloud progetto.
Nella sezione Assegna i ruoli, cerca e seleziona Agente del servizio Cloud Tasks.
Fai clic su Salva.
gcloud
Trova il numero del 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 quanto segue:
PROJECT_ID
: il tuo Google Cloud ID progetto.PROJECT_NUMBER
: il Google Cloud numero del progetto.
Configurazione avanzata
Esistono diversi attributi che puoi configurare nell'attività. Per un elenco completo, consulta la definizione della risorsa dell'attività.
Esempi di attributi che puoi personalizzare:
- Nomi:se hai scelto di specificare un nome per l'attività, Cloud Tasks può utilizzarlo per garantire la deduplica delle attività, anche se l'elaborazione necessaria per questo può aumentare la latenza.
- Pianificazione:puoi pianificare un'attività per un momento successivo. Supportato solo per
CreateTask
(non supportato perBufferTask
) - Configurazione nuovi tentativi:configura il comportamento di nuovo tentativo per un'attività se non va a buon fine. Supportato solo per
CreateTask
(non supportato perBufferTask
)
Passaggi successivi
- Scopri di più sulle attività target HTTP nel riferimento all'API RPC.
- Scopri di più sulle attività target HTTP nel riferimento all'API REST.