Configura il routing, i limiti e i nuovi tentativi della coda

Cloud Tasks ti consente di gestire l'esecuzione delle attività definendo il routing, i limiti di frequenza di invio e il comportamento dei nuovi tentativi a livello di coda. Puoi configurare queste impostazioni durante la creazione di una coda o l'aggiornamento di una coda esistente.

Sia gcloud tasks queues create sia gcloud tasks queues update utilizzano gli stessi flag per impostare i parametri della coda, mentre gcloud tasks queues update supporta anche i flag --clear-* per reimpostare i parametri sui valori predefiniti.

La configurazione dell'autenticazione a livello di coda esegue l'override dell'autenticazione a livello di attività. Per saperne di più, consulta Utilizza le attività target HTTP con i token di autenticazione.

Configura il routing a livello di coda

La configurazione del routing a livello di coda sostituisce il routing impostato a livello di attività. Questo è utile se vuoi utilizzare Cloud Tasks come buffer davanti al tuo servizio di destinazione o se devi modificare il routing per tutte le attività in una coda.

Il routing a livello di coda si applica a:

• Attività in coda
• Attività aggiunte alla coda dopo l'impostazione del routing a livello di coda

Limitazioni

Il routing a livello di coda non è compatibile con le chiavi di crittografia gestite dal cliente (CMEK) di Cloud Key Management Service (Cloud KMS). Se CMEK è abilitato, non puoi eseguire queste azioni:

• Crea attività in una coda con routing a livello di coda
• Applica il routing a livello di coda

Configura il routing a livello di coda per le attività HTTP

Puoi configurare una coda in modo che esegua l'override del routing a livello di attività durante la creazione o l'aggiornamento della coda. Per configurare il routing a livello di coda, imposta il parametro uriOverride della coda sulla route che preferisci. Per impostazione predefinita (uriOverrideEnforceMode impostato su ALWAYS), il routing a livello di coda esegue l'override del routing a livello di attività. Puoi anche impostare uriOverrideEnforceMode su IF_NOT_EXISTS in modo che il routing a livello di coda venga applicato solo quando un'attività non specifica i propri componenti URI.

Se applichi il routing a livello di coda come aggiornamento di una coda esistente, metti in pausa la coda prima di applicare le modifiche e attendi un minuto dopo l'applicazione delle modifiche per riprendere la coda.

1. Metti in pausa la coda eseguendo questo comando:

   gcloud tasks queues pause QUEUE_ID \
       --location=LOCATION

   Sostituisci quanto segue:

   • QUEUE_ID: l'ID della coda.
   • LOCATION: la località della coda.

2. Aggiorna o rimuovi il routing a livello di coda.

   • Per aggiornare il routing a livello di coda, imposta il parametro uriOverride sulla route aggiornata (o passa il flag --http-uri-override a gcloud tasks queues update).

   • Per rimuovere il routing a livello di coda:

     • Google Cloud CLI: esegui gcloud tasks queues update con il flag --clear-http-uri-override:

     gcloud tasks queues update QUEUE_ID \
         --location=LOCATION \
         --clear-http-uri-override

     • API REST: invia una richiesta patch per la coda con un oggetto JSON vuoto ({}) e il parametro di query updateMask impostato su httpTarget.uriOverride (o httpTarget per cancellare tutte le impostazioni del target HTTP a livello di coda).

     • API RPC: invia un UpdateQueueRequest per Queue con queue.name specificato, http_target.uri_override non impostato e il parametro update_mask impostato su http_target.uri_override (o http_target per cancellare tutte le impostazioni del target HTTP a livello di coda).

   L'esempio seguente utilizza l'API REST per aggiornare l'host a cui vengono indirizzate le attività:

   curl -X PATCH -d @- -i \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     "https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID?updateMask=httpTarget.uriOverride" << EOF
   {
     "httpTarget": {"uriOverride":{"host":"NEW_HOST"}}
   }
   EOF
   

   Sostituisci quanto segue:

   • 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

   • PROJECT_ID: l'ID del tuo progetto Google Cloud . Puoi ottenerlo eseguendo questo comando nel terminale:

     gcloud config get-value project

   • LOCATION: la località della coda.

   • NEW_HOST: il nuovo host a cui vuoi indirizzare la coda.

3. Attendi un minuto.

   L'applicazione della nuova configurazione può richiedere fino a un minuto. Attendere prima di riprendere la coda aiuta a evitare che le attività vengano inviate con la vecchia configurazione.

4. Riprendi la coda eseguendo questo comando:

   gcloud tasks queues resume QUEUE_ID \
       --location=LOCATION

5. Verifica che la coda sia stata configurata correttamente eseguendo questo comando:

   gcloud tasks queues describe QUEUE_ID \
       --location=LOCATION

   L'output dovrebbe contenere l'override del routing httpTarget che hai impostato.

Configura il routing a livello di coda per le attività di App Engine

Per configurare il routing a livello di coda per le attività di App Engine, imposta il parametro appEngineRoutingOverride della coda sul servizio e sulla versione di App Engine che preferisci.

1. Configura il routing a livello di coda ed esegui l'override di qualsiasi routing a livello di attività:

   gcloud tasks queues update QUEUE_ID \
       --location=LOCATION \
       --routing-override=service:SERVICE,version:VERSION

   Sostituisci quanto segue:

   • QUEUE_ID: l'ID della coda (il nome breve).
   • LOCATION: la località della coda.
   • SERVICE: il servizio worker di App Engine responsabile della gestione delle attività.
   • VERSION: la versione dell'app.

   Ad esempio, se configuri un servizio worker per gestire tutte le attività in una coda, puoi indirizzare il traffico a quel servizio e alla versione predefinita:

   gcloud tasks queues update QUEUE_ID \
       --location=LOCATION \
       --routing-override=service:SERVICE

2. Verifica che la coda sia stata configurata correttamente eseguendo questo comando:

   gcloud tasks queues describe QUEUE_ID \
       --location=LOCATION

   L'output dovrebbe essere simile al seguente:

   appEngineRoutingOverride:
     host: SERVICE.PROJECT_ID.appspot.com
     service: SERVICE
   name: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
   rateLimits:
     maxBurstSize: 100
     maxConcurrentDispatches: 1000
     maxDispatchesPerSecond: 500.0
   retryConfig:
     maxAttempts: 100
     maxBackoff: 3600s
     maxDoublings: 16
     minBackoff: 0.100s
   state: RUNNING

3. Per rimuovere il routing a livello di coda, esegui questo comando:

   gcloud tasks queues update QUEUE_ID \
       --location=LOCATION \
       --clear-routing-override

   Quando il routing a livello di coda viene rimosso, il routing a livello di attività viene applicato alle attività nella coda e alle attività aggiunte alla coda in futuro.

Definisci i limiti di frequenza

Il limite di frequenza determina la frequenza massima in stato stabile con cui le attività possono essere inviate da una coda attiva, indipendentemente dal fatto che l'invio sia un primo tentativo di attività o un nuovo tentativo.

Nota: l'impostazione maxDispatchesPerSecond definisce il limite massimo di stato stabile per una coda attiva. Se una coda è stata appena creata, ripresa dopo essere stata messa in pausa, si sta riprendendo da risposte di errore HTTP 429 o 5xx downstream o è inattiva anche solo per alcuni minuti senza invii attivi, entra in uno stato di inattività o di avvio a freddo. In questo stato, Cloud Tasks aumenta gradualmente la frequenza di invio applicata da un valore di riferimento basso verso maxDispatchesPerSecond, anziché raggiungere immediatamente la capacità massima. Per saperne di più sull'avvio graduale a freddo o inattivo e sulla limitazione del sistema, consulta Avvio graduale della coda iniziale ed Errori di backoff e frequenze applicate.

1. Imposta la frequenza massima e il numero di attività simultanee che possono essere inviate da una coda eseguendo questo comando:

   gcloud tasks queues update QUEUE_ID \
       --location=LOCATION \
       --max-dispatches-per-second=DISPATCH_RATE \
       --max-concurrent-dispatches=MAX_CONCURRENT_DISPATCHES

   Sostituisci quanto segue:

   • QUEUE_ID: l'ID della coda (il nome breve).
   • LOCATION: la località della coda.
   • DISPATCH_RATE: la frequenza di invio. Questa è la frequenza con cui i token nel bucket vengono aggiornati. In condizioni in cui esiste un flusso di attività relativamente costante, questo equivale alla frequenza di invio delle attività.
   • MAX_CONCURRENT_DISPATCHES: il numero massimo di attività nella coda che possono essere eseguite contemporaneamente.

   Ad esempio, se hai creato una coda senza impostare parametri, puoi aggiornare il numero massimo di attività in parallelo eseguendo questo comando:

   gcloud tasks queues update QUEUE_ID \
       --location=LOCATION \
       --max-concurrent-dispatches=MAX_CONCURRENT_DISPATCHES

2. Verifica che la coda sia stata configurata correttamente eseguendo questo comando:

   gcloud tasks queues describe QUEUE_ID \
       --location=LOCATION

   L'output dovrebbe essere simile al seguente:

   name: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
   rateLimits:
     maxBurstSize: 100
     maxConcurrentDispatches: MAX_CONCURRENT_DISPATCHES
     maxDispatchesPerSecond: DISPATCH_RATE
   retryConfig:
     maxAttempts: 100
     maxBackoff: 3600s
     maxDoublings: 16
     minBackoff: 0.100s
   state: RUNNING

Metodi per definire le frequenze di elaborazione delle code

Puoi definire le frequenze di elaborazione delle code utilizzando l'API Cloud Tasks o caricando un file queue.yaml. Entrambi i metodi generano code che utilizzano lo stesso meccanismo sottostante.

Attenzione: sebbene tu possa utilizzare entrambi i metodi per creare code, utilizza un file queue.yaml o l'API Cloud Tasks per configurare le code, ma non entrambi. Per saperne di più, consulta Utilizza Queue Management o queue.yaml.

In entrambi i casi, la coda utilizza l'algoritmo token bucket per controllare la frequenza di esecuzione delle attività. Ogni coda con nome ha un bucket che contiene i relativi token.

Ogni volta che l'applicazione esegue un'attività, un token viene rimosso dal bucket. La coda continua a elaborare le attività finché il bucket non esaurisce i token. Il sistema riempie continuamente il bucket con nuovi token in base alla frequenza max_dispatches_per_second specificata per la coda. Se la coda contiene attività da elaborare e il bucket della coda contiene token, il sistema elabora contemporaneamente un numero di attività pari al numero di token, fino al valore max_concurrent_dispatches impostato.

In una coda attiva già sottoposta a preriscaldamento, un carico non uniforme può consentire al numero di token nel bucket di crescere in modo significativo, il che può portare a picchi di elaborazione quando arriva un picco di richieste. In questo caso, una coda attiva potrebbe registrare una frequenza di invio effettiva che supera temporaneamente la frequenza max_dispatches_per_second, consumando risorse di sistema e competendo con le richieste di gestione degli utenti. Se utilizzi le code per gestire le frequenze di invio in base a SLA relativamente lenti per i servizi downstream, questi burst possono causare errori come HTTP 429 (Too Many Requests) o HTTP 503 (Service Unavailable). Tuttavia, se una coda è stata appena creata, ripresa di recente o è inattiva per diversi minuti, entra in uno stato di inattività o di attesa e aumenta gradualmente verso max_dispatches_per_second anziché eseguire il burst immediatamente. Per ulteriori informazioni sull'avvio graduale di una coda inattiva o non utilizzata, consulta Avvio graduale della coda iniziale.

• Quando utilizzi un metodo dell'API Cloud Tasks, hai a disposizione due campi per definire la frequenza di invio della coda:

  • max_dispatches_per_second
  • max_concurrent_dispatches

  Un terzo campo, max_burst_size, viene calcolato dal sistema in base al valore impostato per max_dispatches_per_second. Per saperne di più, consulta la sezione sui messaggi di RateLimits.

• Quando utilizzi il metodo queue.yaml, puoi impostare tutti e tre gli elementi:

  • max_concurrent_requests, che equivale a max_concurrent_dispatches
  • rate, che equivale a max_dispatches_per_second
  • bucket_size, che equivale a max_burst_size

Nella maggior parte dei casi, l'utilizzo del metodo dell'API Cloud Tasks e l'impostazione di max_burst_size da parte del sistema producono una frequenza molto efficiente per la gestione dei burst di richieste. In alcuni casi, tuttavia, in particolare quando la frequenza necessaria è relativamente bassa, puoi avere un maggiore controllo utilizzando il metodo queue.yaml per impostare manualmente bucket_size su un valore basso o impostando max_concurrent_dispatches su un valore basso utilizzando l'API Cloud Tasks.

Imposta i parametri di ripetizione

Se un'attività non viene completata correttamente, Cloud Tasks riprova l'attività con un backoff esponenziale in base ai parametri impostati. Dopo la corretta esecuzione di un'attività, questa viene rimossa dalla coda. In tutti i casi, si applica anche il limite di conservazione massima delle attività.

Facoltativamente, puoi specificare una configurazione dei nuovi tentativi a livello di attività che sostituisce la configurazione dei nuovi tentativi a livello di coda per l'attività. Per saperne di più, consulta Imposta i parametri di ripetizione per un'attività.

Suggerimento: per eseguire il debug dei parametri di ripetizione, puoi registrare il codice di stato per ogni chiamata di un'attività utilizzando Cloud Logging con le tue code e impostando un rapporto di campionamento dei log per specificare quale frazione di operazioni scrivere in Logging.

1. Specifica il numero massimo di nuovi tentativi per le attività non riuscite nella coda, imposta un limite di tempo per i nuovi tentativi e controlla l'intervallo tra i tentativi eseguendo questo comando:

   gcloud tasks queues update QUEUE_ID \
       --location=LOCATION \
       --max-attempts=MAX_ATTEMPTS \
       --max-retry-duration=MAX_RETRY_DURATION \
       --min-backoff=MIN_INTERVAL \
       --max-backoff=MAX_INTERVAL \
       --max-doublings=MAX_DOUBLINGS

   Sostituisci quanto segue:

   • QUEUE_ID: l'ID della coda (il nome breve).
   • LOCATION: la località della coda.
   • MAX_ATTEMPTS: il numero massimo di tentativi per un task, incluso il primo. Per consentire un numero illimitato di tentativi, imposta questo valore su -1. MAX_RETRY_DURATION si applica comunque anche se MAX_ATTEMPTS viene raggiunto o impostato su -1.
   • MAX_RETRY_DURATION: il tempo massimo per riprovare un'attività non riuscita, misurato dal primo tentativo di esecuzione dell'attività. Il valore deve essere una stringa che termina con "s", ad esempio 5s. Per specificare una durata illimitata, imposta questo valore su 0s. MAX_ATTEMPTS si applica anche se viene raggiunto MAX_RETRY_DURATION o se è impostato su 0s.
   Nota: se specifichi tentativi illimitati (MAX_ATTEMPTS è -1) e una durata illimitata (MAX_RETRY_DURATION è 0s), il tentativo di esecuzione dell'attività viene ripetuto fino a raggiungere il limite di conservazione massima delle attività. In caso contrario, Cloud Tasks interrompe i nuovi tentativi solo dopo che entrambe le condizioni sono state soddisfatte o l'attività è stata eseguita correttamente. Quando l'attività è stata tentata MAX_ATTEMPTS volte e il tempo MAX_RETRY_DURATION è trascorso, non vengono effettuati ulteriori tentativi e l'attività viene eliminata.
   • MIN_INTERVAL: il tempo minimo di attesa tra i tentativi di ripetizione. Il valore deve essere una stringa che termina con "s", ad esempio 5s.
   • MAX_INTERVAL: il tempo massimo di attesa tra i tentativi di ripetizione. Il valore deve essere una stringa che termina con "s", ad esempio 5s.

   • MAX_DOUBLINGS: il numero massimo di volte in cui l'intervallo tra i nuovi tentativi di attività non riusciti raddoppia prima che l'aumento diventi costante. L'intervallo tra i tentativi di un'attività inizia a MIN_INTERVAL, poi raddoppia MAX_DOUBLINGS volte, quindi aumenta in modo lineare e infine i tentativi vengono ripetuti a intervalli di MAX_INTERVAL fino a MAX_ATTEMPTS volte.

     Ad esempio, se MIN_INTERVAL è 10s, MAX_INTERVAL è 300s e MAX_DOUBLINGS è 3, l'intervallo tra i nuovi tentativi raddoppia 3 volte, aumenta in modo lineare di 2^3 * 10 s e poi riprova a intervalli di MAX_INTERVAL fino a quando l'attività non è stata tentata MAX_ATTEMPTS volte: 10 s, 20 s, 40 s, 80 s, 160 s, 240 s, 300 s, 300 s e così via.

Per ulteriori dettagli sui parametri, consulta il riferimento della risorsa RetryConfig.

1. Verifica che la coda sia stata configurata correttamente eseguendo questo comando:

   gcloud tasks queues describe QUEUE_ID \
       --location=LOCATION

   L'output dovrebbe contenere i parametri retryConfig che hai impostato:

   retryConfig:
     maxAttempts: MAX_ATTEMPTS
     maxBackoff: MAX_INTERVAL
     maxDoublings: MAX_DOUBLINGS
     maxRetryDuration: MAX_RETRY_DURATION
     minBackoff: MIN_INTERVAL

Passaggi successivi

• Scopri di più sulla creazione di attività target HTTP.
• Scopri di più sulla creazione di attività di App Engine.
• Scopri di più sulla gestione delle code nel Riferimento API RPC.
• Scopri di più sulla gestione delle code nel Riferimento API REST.