Crea attività Cloud Tasks

Puoi utilizzare Cloud Tasks per creare elementi di lavoro asincroni chiamati attività. Questo documento mostra come creare attività target HTTP e attività App Engine.

Le attività di destinazione HTTP sono richieste inoltrate a un worker che si trova in un endpoint HTTP generico con un indirizzo IP esterno, ad esempio Cloud Run, Google Kubernetes Engine, Compute Engine o un server web on-premise.

Per i target App Engine, Cloud Tasks inoltra le richieste di attività a un gestore all'interno di App Engine. Tutte le code che hanno come target i gestori di App Engine devono avere un'app App Engine. I gestori devono essere eseguiti nella regione in cui viene eseguita l'app App Engine. Questa regione funge anche da parametro REGION per le richieste Cloud Tasks.

Puoi creare un'attività target HTTP nei seguenti modi:

  • Nella console Google Cloud
  • Utilizzando Google Cloud CLI nel terminale o in Cloud Shell
  • Inviando una richiesta diretta all'API Cloud Tasks

Per scoprire come aggiungere in modo programmatico un'attività target HTTP a una coda Cloud Tasks, consulta Crea attività target HTTP in modo programmatico.

Puoi creare un'attività App Engine nei seguenti modi:

  • Utilizzando Google Cloud CLI nel terminale o in Cloud Shell
  • Inviando una richiesta diretta all'API Cloud Tasks

Per scoprire come aggiungere in modo programmatico un'attività App Engine a una coda Cloud Tasks, consulta Creare attività App Engine in modo programmatico.

Prima di iniziare

Assicurati di aver già creato una coda di attività Cloud Tasks. Per maggiori informazioni, consulta Crea code Cloud Tasks.

Crea un'attività target HTTP

Quando crei un'attività, puoi specificarne il nome. Se il nome è identico a quello di un'attività esistente o di un'attività eliminata o completata di recente, la chiamata non andrà a buon fine. Se non specifichi un nome dell'attività, viene generato un ID attività univoco casuale.

Poiché è previsto un costo di ricerca aggiuntivo per identificare i nomi delle attività duplicati, le attività create con ID specificati dall'utente hanno una latenza notevolmente maggiore. È consigliabile utilizzare stringhe sottoposte ad hashing per l'ID attività o per il prefisso dell'ID attività. Per saperne di più, consulta la sezione Deduplicazione delle attività.

Console

  1. Nella console Google Cloud , vai alla pagina Cloud Tasks > Code.

    Vai a Code

  2. Fai clic sul nome della coda a cui vuoi aggiungere l'attività.

  3. Fai clic su Crea attività HTTP.

  4. (Facoltativo) Specifica il nome dell'attività.

  5. Per URL, specifica l'URL completo qualificato a cui verrà inviata la richiesta. Il percorso deve iniziare con http:// o https://, ad esempio https://www.example.com.

  6. (Facoltativo) Specifica il metodo HTTP da utilizzare per la richiesta. Il valore predefinito è POST.

  7. (Facoltativo) Per Corpo della richiesta, fornisci i dati del corpo HTTP da inviare al worker che elabora l'attività.

  8. (Facoltativo) Specifica una o più intestazioni della richiesta HTTP facendo clic su Aggiungi un'intestazione.

  9. Per Intestazione di autenticazione, seleziona una delle seguenti opzioni di autorizzazione per specificare come viene autenticata la richiesta inviata alla destinazione durante l'esecuzione dell'attività:

    • Nessuno: nessuna intestazione, per gli endpoint pubblici senza autorizzazione
    • Aggiungi token OAuth: in genere utilizzato per le API di Google ospitate su *.googleapis.com
    • Aggiungi token OIDC: utilizzato per Google Cloud e chiamate agli endpoint di terze parti, ad eccezione delle API di Google ospitate su *.googleapis.com

  10. Se applicabile, per Service account, fornisci l'email dell'account di servizio che verrà utilizzato per generare il token di autorizzazione incluso nella richiesta inviata alla destinazione durante l'esecuzione dell'attività. L'account di servizio deve trovarsi nello stesso progetto della coda. Il chiamante deve disporre dell'autorizzazione iam.serviceAccounts.actAs per il account di servizio.

  11. (Facoltativo) Se applicabile, specifica il segmento di pubblico per limitare i tipi di azioni o i destinatari del token di autorizzazione.

  12. Fai clic su Crea.

Il tuo compito dovrebbe essere elencato nella pagina Dettagli coda.

gcloud

Per creare un'attività di destinazione HTTP e aggiungerla a una coda esistente, utilizza il comando gcloud tasks create-http-task.

gcloud tasks create-http-task \
    --queue=QUEUE_ID \
    --url=URL \
    --location=REGION \
    --project=PROJECT_ID \
    --oidc-service-account-email=SERVICE_ACCOUNT_EMAIL

Sostituisci quanto segue:

  • QUEUE_ID: il nome della coda a cui aggiungere l'attività.

  • URL: l'URL completo a cui verrà inviata la richiesta. Il percorso deve iniziare con http:// o https://, ad esempio: https://www.example.com.

  • REGION: facoltativo. La regione in cui viene eseguito il deployment della coda, ad esempio us-central1.

  • PROJECT_ID: facoltativo. L'ID progetto del progettoGoogle Cloud in cui verrà creato il task.

  • SERVICE_ACCOUNT_EMAIL: facoltativo. L'email dell'account di servizio utilizzata per generare un token di autorizzazione incluso nella richiesta inviata alla destinazione durante l'esecuzione dell'attività. L'account di servizio deve trovarsi nello stesso progetto della coda. Il chiamante deve disporre dell'autorizzazione iam.serviceAccounts.actAs per il account di servizio.

    Per generare un token di accesso OAuth2 anziché un token OpenID Connect, sostituisci il flag --oidc-service-account-email con --oauth-service-account-email per specificare l'email del account di servizio.

Dopo aver creato l'attività, dovresti visualizzare un messaggio di conferma con il nome completo della risorsa dell'attività creata.

REST

Per creare un'attività di destinazione HTTP e aggiungerla a una coda esistente, utilizza il metodo projects.locations.queues.tasks.create.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: obbligatorio. L'ID progetto del progetto Google Cloud in cui verrà creato il task.
  • REGION: obbligatorio. La regione in cui viene eseguito il deployment della coda, ad esempio us-central1.
  • QUEUE_ID: obbligatorio. L'ID della coda a cui verrà aggiunta l'attività.
  • URL: obbligatorio. L'URL completo a cui verrà inviata la richiesta. Questa stringa deve iniziare con http:// o https://, ad esempio: https://www.example.com.
  • SERVICE_ACCOUNT_EMAIL: facoltativo. L'email del account di servizio utilizzata per generare un token di autorizzazione incluso nella richiesta inviata alla destinazione durante l'esecuzione dell'attività. L'account di servizio deve trovarsi nello stesso progetto della coda. Il chiamante deve disporre dell'autorizzazione iam.serviceAccounts.actAs per il account di servizio.

    Per generare un token di accesso OAuth2 anziché un token OpenID Connect, sostituisci il campo oidcToken con oauthToken per specificare l'email del account di servizio.

  • SCHEDULE_TIME: facoltativo. L'ora in cui è pianificata l'esecuzione del tentativo di esecuzione dell'attività, nel formato RFC 3339, ad esempio, 2026-10-02T15:01:23Z. Se l'ora non è impostata o è nel passato, Cloud Tasks la imposterà sull'ora attuale.

Corpo JSON della richiesta: 

{
  "task": {
    "httpRequest": {
      "url": "URL",
      "httpMethod": "POST",
      "oidcToken": {
        "serviceAccountEmail": "SERVICE_ACCOUNT_EMAIL"
      }
    },
    "scheduleTime": "SCHEDULE_TIME"
  }
}

Per inviare la richiesta, espandi una di queste opzioni:

In caso di esito positivo, il corpo della risposta contiene l'istanza appena creata della risorsa Task. 

{
  "name": "projects/PROJECT_ID/locations/REGION/queues/QUEUE_ID/tasks/TASK_ID",
  "httpRequest": {
    "url": "URL",
    "httpMethod": "POST",
    "headers": {
      "User-Agent": "Google-Cloud-Tasks"
    },
    "oidcToken": {
      "serviceAccountEmail": "SERVICE_ACCOUNT_EMAIL",
      "audience": "URL"
    }
  },
  "scheduleTime": "SCHEDULE_TIME",
  "createTime": "2026-04-30T19:11:50Z",
  "dispatchDeadline": "600s",
  "view": "BASIC"
}

Crea un'attività App Engine

Quando crei un'attività, puoi specificarne il nome. Se il nome è identico a quello di un'attività esistente o di un'attività eliminata o completata di recente, la chiamata non andrà a buon fine. Se non specifichi un nome dell'attività, viene generato un ID attività univoco casuale.

Poiché è previsto un costo di ricerca aggiuntivo per identificare i nomi delle attività duplicati, le attività create con ID specificati dall'utente hanno una latenza notevolmente maggiore. È consigliabile utilizzare stringhe sottoposte ad hashing per l'ID attività o per il prefisso dell'ID attività. Per saperne di più, consulta la sezione Deduplicazione delle attività.

gcloud

Per creare un'attività App Engine e aggiungerla a una coda esistente, utilizza il comando gcloud tasks create-app-engine-task.

gcloud tasks create-app-engine-task \
    --queue=QUEUE_ID \
    --relative-uri=RELATIVE_URI \
    --location=REGION \
    --project=PROJECT_ID \
    --routing=KEY:VALUE

Sostituisci quanto segue:

  • QUEUE_ID: il nome della coda a cui aggiungere l'attività.
  • RELATIVE_URI: l'URI relativo della richiesta. Il percorso deve iniziare con una barra (/). Se non specificato, viene utilizzato il percorso principale (/).
  • REGION: facoltativo. La regione in cui viene eseguito il deployment della coda. Se non specificato, viene utilizzata la posizione dell'app App Engine del progetto corrente.
  • PROJECT_ID: facoltativo. L'ID progetto del progettoGoogle Cloud in cui verrà creato il task.
  • KEY:VALUE: facoltativo. Il percorso da utilizzare per questa attività, dove KEY è almeno uno tra: service, version o instance. Le chiavi mancanti utilizzeranno il routing predefinito.

Dopo aver creato l'attività, dovresti visualizzare un messaggio di conferma con il nome completo della risorsa dell'attività creata.

REST

Per creare un'attività App Engine e aggiungerla a una coda esistente, utilizza il metodo projects.locations.queues.tasks.create.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: obbligatorio. L'ID progetto del progetto Google Cloud in cui verrà creato il task.
  • REGION: obbligatorio. La regione in cui viene eseguito il deployment della coda.
  • QUEUE_ID: obbligatorio. L'ID della coda a cui verrà aggiunta l'attività.
  • RELATIVE_URI: obbligatorio. L'URI relativo della richiesta. Il percorso deve iniziare con una barra (/). Se non specificato, viene utilizzato il percorso principale (/).
  • SERVICE: facoltativo. Il servizio App Engine che elaborerà l'attività. Per impostazione predefinita, l'attività viene inviata al servizio che è il servizio predefinito quando viene tentata l'attività.
  • VERSION: facoltativo. La versione di App Engine che elaborerà l'attività. Per impostazione predefinita, l'attività viene inviata alla versione predefinita quando viene tentata l'attività.
  • SCHEDULE_TIME: facoltativo. L'ora in cui è pianificata l'esecuzione del tentativo di esecuzione dell'attività, nel formato RFC 3339, ad esempio, 2026-10-02T15:01:23Z. Se l'ora non è impostata o è nel passato, Cloud Tasks la imposterà sull'ora attuale.

Corpo JSON della richiesta: 

{
  "task": {
    "appEngineHttpRequest": {
      "httpMethod": "POST",
      "relativeUri": "RELATIVE_URI",
      "appEngineRouting": {
        "service": "SERVICE",
        "version": "VERSION"
      }
    },
    "scheduleTime": "SCHEDULE_TIME"
  }
}

Per inviare la richiesta, espandi una di queste opzioni:

In caso di esito positivo, il corpo della risposta contiene l'istanza appena creata della risorsa Task. 

{
  "name": "projects/PROJECT_ID/locations/REGION/queues/QUEUE_ID/tasks/TASK_ID",
  "appEngineHttpRequest": {
    "httpMethod": "POST",
    "relativeUri": "RELATIVE_URI",
    "appEngineRouting": {
      "service": "SERVICE",
      "version": "VERSION",
      "host": "VERSION.SERVICE.PROJECT_ID.appspot.com"
    }
  },
  "scheduleTime": "SCHEDULE_TIME",
  "createTime": "2026-04-30T19:11:50Z",
  "dispatchDeadline": "600s",
  "view": "BASIC"
}

Creare un batch di attività

Puoi creare un batch di attività di destinazione e aggiungerlo a una coda esistente utilizzando il metodo projects.locations.queues.tasks.batchCreate per creare un elenco di richieste.

Tieni presente quanto segue:

  • Tutte le attività devono essere aggiunte alla stessa coda.

  • Esiste un limite al numero di attività che possono essere create in un singolo batch. Per saperne di più, consulta Quote e limiti.

  • Le richieste batch, che aggregano singole operazioni in un'unica richiesta, non sono atomiche perché è possibile che alcune delle operazioni contenute nel batch non vadano a buon fine, mentre altre sì.

  • Puoi anche eliminare un batch di attività. Per saperne di più, consulta la sezione Eliminare un batch di attività da una coda.

Attività HTTP

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: obbligatorio. L'ID progetto del progetto Google Cloud in cui verranno creati i task.
  • REGION: obbligatorio. La regione in cui viene eseguito il deployment della coda, ad esempio us-central1.
  • QUEUE_ID: obbligatorio. L'ID della coda a cui verranno aggiunte le attività.
  • URL: obbligatorio. L'URL completo a cui verrà inviata la richiesta. Questa stringa deve iniziare con http:// o https://, ad esempio: https://www.example.com.
  • SERVICE_ACCOUNT_EMAIL: facoltativo. L'email del account di servizio utilizzata per generare un token di autorizzazione incluso nella richiesta inviata alla destinazione durante l'esecuzione dell'attività. L'account di servizio deve trovarsi nello stesso progetto della coda. Il chiamante deve disporre dell'autorizzazione iam.serviceAccounts.actAs per il account di servizio.

    Per generare un token di accesso OAuth2 anziché un token OpenID Connect, sostituisci il campo oidcToken con oauthToken per specificare l'email del account di servizio.

Il corpo della richiesta contiene un elenco di richieste.

Corpo JSON della richiesta: 

{
  "requests": [
    {
      "task": {
        "httpRequest": {
          "url": "URL",
          "httpMethod": "POST",
          "oidcToken": {
            "serviceAccountEmail": "SERVICE_ACCOUNT_EMAIL"
          }
        },
        "scheduleTime": "SCHEDULE_TIME"
      }
    }
  ]
}

Per inviare la richiesta, espandi una di queste opzioni:

In caso di esito positivo, il corpo della risposta contiene un'istanza della risorsa Operation. 

{
  "name": "projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.tasks.v2beta3.BatchCreateTasksMetadata"
  },
  "done": false
}

Attività App Engine

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: obbligatorio. L'ID progetto del progetto Google Cloud in cui verrà creato il task.
  • REGION: obbligatorio. La regione in cui viene eseguito il deployment della coda.
  • QUEUE_ID: obbligatorio. L'ID della coda a cui verranno aggiunte le attività.
  • RELATIVE_URI: obbligatorio. L'URI relativo della richiesta. Il percorso deve iniziare con una barra (/). Se non specificato, viene utilizzato il percorso principale (/).
  • SERVICE: facoltativo. Il servizio App Engine che elaborerà l'attività. Per impostazione predefinita, l'attività viene inviata al servizio che è il servizio predefinito quando viene tentata l'attività.
  • VERSION: facoltativo. La versione di App Engine che elaborerà l'attività. Per impostazione predefinita, l'attività viene inviata alla versione predefinita quando viene tentata l'attività.
  • SCHEDULE_TIME: facoltativo. L'ora in cui è pianificata l'esecuzione del tentativo di esecuzione dell'attività, nel formato RFC 3339, ad esempio, 2026-10-02T15:01:23Z. Se l'ora non è impostata o è nel passato, Cloud Tasks la imposterà sull'ora attuale.

Il corpo della richiesta contiene un elenco di richieste.

Corpo JSON della richiesta: 

{
  "requests": [
    {
      "task": {
        "appEngineHttpRequest": {
          "httpMethod": "POST",
          "relativeUri": "RELATIVE_URI",
          "appEngineRouting": {
            "service": "SERVICE",
            "version": "VERSION"
          }
        },
        "scheduleTime": "SCHEDULE_TIME"
      }
    }
  ]
}

Per inviare la richiesta, espandi una di queste opzioni:

In caso di esito positivo, il corpo della risposta contiene un'istanza della risorsa Operation. 

{
  "name": "projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.tasks.v2beta3.BatchCreateTasksMetadata"
  },
  "done": false
}

Passaggi successivi