Utilizzare Queue Management o code.yaml

Questa pagina spiega le differenze tra l'utilizzo dell'API Cloud Tasks per gestire le code e l'uso del caricamento di un file Cloud Tasks queue.yaml o queue.xml per eseguire gli stessi scopi. Inoltre, illustra alcune delle insidie dei meccanismi di combinazione e come affrontare i problemi comuni.

Nota: la maggior parte delle app standard di App Engine utilizza queue.yaml per configurare le code nel servizio Coda di attività di App Engine. Per le app Java viene invece utilizzato il file queue.xml. Tutto quello che è scritto in questa pagina su queue.yaml si applica anche ai file queue.xml, ma per brevità questo documento usa spesso queue.yaml per rappresentare entrambi i file.

Introduzione

L'API Cloud Tasks fornisce un'interfaccia indipendente da App Engine al servizio Queue dell'attività di App Engine. Grazie a questa interfaccia, consente di gestire le code, anche tramite la console o il comandogcloud. Le code create dall'API Cloud Tasks sono accessibili dall'SDK di App Engine e viceversa. Per mantenere la compatibilità, è possibile utilizzare il file di configurazione utilizzato dall'SDK di App Engine, queue.yaml, anche per creare e configurare code da utilizzare tramite l'API Cloud Tasks. Tuttavia, l'unione della configurazione tramite file con la configurazione tramite l'API Cloud Tasks può avere conseguenze impreviste.

Problemi di combinazione tra queue.yaml e i metodi di gestione della coda di Cloud Tasks

Per il servizio sottostante, i file queue.yaml sono definitivi. Il caricamento di un queue.yaml che omette le code esistenti nel tuo progetto, indipendentemente da come sono state create, fa sì che tali code vengano disattivate o messe in pausa. Pertanto, se utilizzi l'API Cloud Tasks per chiamare CreateQueue o UpdateQueue e poi carichi un file queue.yaml che lo omette, le code create nelle chiamate Cloud Tasks vengono disabilitate.

Considera il seguente scenario:

1. Chiama CreateQueue per creare una coda denominata "cloud-tasks-queue".

2. Carica un file queue.yaml con i seguenti contenuti:

   queue:
   - name: queue-yaml-queue
   

Qual è lo stato attuale delle code in questo progetto? La coda denominata "cloud-tasks-queue" e tutte le altre code esistenti in precedenza si trovano nello stato DISABLED, mentre la coda denominata "queue-yaml-queue" è in stato RUNNING.

Nota: la coda di default è un'eccezione. Non viene mai disabilitata da App Engine. Per ulteriori dettagli, consulta Cloud Tasks e la coda default di App Engine.

Questo comportamento potrebbe essere sorprendente se crei code nell'API Cloud Tasks. Le seguenti istruzioni spiegano come ripristinare una coda disattivata.

Allo stesso modo, se una coda è disabilitata nell'API Cloud Tasks, ma in seguito viene visualizzata in un file queue.yaml caricato, la coda viene ripresa.

Se una coda viene eliminata con il metodo DeleteQueue e in un secondo momento viene visualizzata in un file queue.yaml, il caricamento di queue.yaml potrebbe non riuscire perché i nomi delle code non possono essere riutilizzati per diversi giorni dopo l'eliminazione.

Best practice

Attenzione: è vivamente consigliato utilizzare il metodo di file di configurazione o l'API Cloud Tasks per configurare le code, ma non entrambi.

Se non hai mai utilizzato Cloud Tasks o App Engine, utilizza l'API Cloud Tasks in modo esclusivo per gestire le code ed evitare del tutto l'utilizzo di queue.yaml e queue.xml. I metodi di gestione della coda di Cloud Tasks consentono agli utenti di scegliere con maggiore facilità quando creano, aggiornano ed eliminano le code.

Se, tuttavia, sei un utente queue.yaml o queue.xml esistente, ti consigliamo di passare ai metodi di gestione della coda solo se hai compreso le eventuali commissioni legate al mix di queue.yaml con i metodi di gestione delle code di Cloud Tasks.

Per facilitare l'uso di un solo metodo di configurazione, considera la possibilità di utilizzare gruppi e autorizzazioni per controllare l'accesso alle attività di gestione delle code. Per le istruzioni, vedi Configurazione della coda sicura.

Debug

Puoi esaminare i log di controllo dell'attività di amministrazione del progetto per recuperare la cronologia delle modifiche alla configurazione della coda, incluse le creazioni, gli aggiornamenti e le eliminazioni delle code:

    gcloud logging read \
      'protoPayload.methodName=
       (com.google.appengine.legacy.queue_created OR
        com.google.appengine.legacy.queue_updated OR
        google.cloud.tasks.v2.CloudTasks.CreateQueue OR
        google.cloud.tasks.v2.CloudTasks.UpdateQueue OR
        google.cloud.tasks.v2.CloudTasks.DeleteQueue)'

Ad esempio, se una coda esistente è disattivata da un caricamento queue.yaml, nel log di controllo viene visualizzato un messaggio "'[QUEUE_NAME]'" il metodo com.google.appengine.legacy.queue_updated verrà visualizzato nel log di controllo.

Come ripristinare una coda disattivata tramite un caricamento queue.yaml

Se misti queue.yaml con i metodi di gestione della coda di Cloud Tasks, il caricamento di un file queue.yaml potrebbe disattivare accidentalmente una coda creata tramite l'API Cloud Tasks.

Per riprendere la coda, puoi chiamare ResumeQueue in coda o aggiungerla a queue.yaml ed eseguire il caricamento. Tieni presente che se hai precedentemente impostato un'elaborazione personalizzata rate nella configurazione queue.yaml della coda, ResumeQueue reimposta la coda sul valore predefinito di rate. Ciò si riflette nel campo maxDispatchesPerSecond della risposta a ResumeQueue.

Avviso: il ripristino di molte code con QPS elevato contemporaneamente può causare un sovraccarico del target. Se ripristini code con QPS elevato, segui il pattern 500/50/5 descritto in Gestisci i rischi di scalabilità.

Quote

Se utilizzi queue.yaml per creare le tue code, per impostazione predefinita puoi crearne al massimo 100. Le code create tramite l'API Cloud Tasks hanno un massimo predefinito di 1000 code. Come in altri casi, la combinazione di metodi API di queue.yaml e Cloud Tasks può produrre risultati imprevisti. Supponi ad esempio di creare alcune code utilizzando queue.yaml e di ottenere un aumento della quota, ad esempio 2000. Se in seguito utilizzi il metodo dell'API Cloud Tasks per creare altre code, non noterai errori di quota. Per risolvere il problema, invia una richiesta utilizzando la scheda Modifica quote della pagina Quote di Google Cloud Console.

Ulteriori informazioni sui metodi di gestione delle code di Cloud Tasks

Configurazione della coda e ritardo all'avvio della coda

Le modifiche alla configurazione della coda possono richiedere diversi minuti per diventare effettive. Ad esempio, dopo aver chiamato CreateQueue o UpdateQueue, potrebbero passare diversi minuti prima di poter chiamare CreateTask in quella coda.

Cloud Tasks e la coda di default App Engine

La coda di App Engine denominata "default" riceve un trattamento speciale nell'SDK di App Engine e nell'API Cloud Tasks.

Se la coda default non esiste già, viene creata nelle seguenti situazioni:

1. La prima volta che un'attività viene aggiunta alla coda default utilizzando l'SDK App Engine,
2. Quando viene caricato un file queue.yaml che specifica una coda default.
3. Quando CreateQueue o UpdateQueue vengono chiamati per creare la coda default.

Per mantenere la compatibilità con App Engine, Cloud Tasks applica le seguenti restrizioni:

1. Se viene creata una coda denominata "default", deve essere una coda che utilizza le attività di App Engine.
2. Una volta creati, gli utenti non possono eliminare la coda default.

Nell'API Cloud Tasks, la coda default si applica anche a quanto segue:

1. L'API Cloud Tasks non crea automaticamente la coda default o altre code.
2. Proprio come qualsiasi altra coda, chiamare GetQueue sulla coda default restituisce un errore non trovato se la chiamata viene effettuata prima della creazione della coda.
3. Allo stesso modo, la coda default non viene visualizzata nell'output di ListQueues prima della sua creazione.
4. La configurazione della coda default può essere modificata con la chiamata UpdateQueue.

Passaggi successivi

• Consulta i metodi disponibili nell'API RPC Cloud Tasks nei documenti di riferimento.
• Consulta i metodi disponibili nell'API REST Cloud Tasks nei documenti di riferimento.
• Leggi informazioni su queue.yaml e queue.xml.