Accodare le funzioni con Cloud Tasks (1ª gen.)

Le funzioni della coda di attività sfruttano Google Cloud Tasks per aiutare la tua app a eseguire attività che richiedono molto tempo, risorse o larghezza di banda limitata in modo asincrono, al di fuori del flusso principale dell'applicazione.

Ad esempio, immagina di voler creare backup di un grande insieme di file immagine attualmente ospitati su un'API con un limite di frequenza. Per essere un consumatore responsabile di questa API, devi rispettare i limiti di frequenza. Inoltre, questo tipo di job a lunga esecuzione potrebbe essere vulnerabile a errori dovuti a timeout e limiti di memoria.

Per ridurre questa complessità, puoi scrivere una funzione di coda di attività che imposta le opzioni di base delle attività, come scheduleTime e dispatchDeadline, e poi passa la funzione a una coda in Cloud Tasks. L'ambiente Cloud Tasks è progettato specificamente per garantire un controllo efficace della congestione e dei criteri di ripetizione per questi tipi di operazioni.

L'SDK Firebase per Cloud Functions for Firebase v3.20.1 e versioni successive interagisce con Firebase Admin SDK v10.2.0 e versioni successive per supportare le funzioni della coda di attività.

L'utilizzo delle funzioni della coda di attività con Firebase può comportare addebiti per l'elaborazione di Cloud Tasks. Per saperne di più, consulta i prezzi di Cloud Tasks.

Crea funzioni di coda di attività

Per utilizzare le funzioni della coda di attività, segui questo flusso di lavoro:

  1. Scrivi una funzione di coda di attività utilizzando l'SDK Firebase per Cloud Functions.
  2. Testa la funzione attivandola con una richiesta HTTP.
  3. Esegui il deployment della funzione con l'interfaccia a riga di comando Firebase. Quando esegui il deployment della funzione della coda di attività per la prima volta, l'interfaccia a riga di comando creerà una coda di attività in Cloud Tasks con le opzioni (limitazione di frequenza e nuovo tentativo) specificate nel codice sorgente.
  4. Aggiungi attività alla coda di attività appena creata, passando i parametri per configurare una pianificazione di esecuzione, se necessario. Puoi farlo scrivendo il codice utilizzando Admin SDK ed eseguendo il deployment in Cloud Functions for Firebase.

Scrivi funzioni di coda di attività

Utilizza onDispatch per iniziare a scrivere funzioni di coda di attività. Una parte importante della scrittura di una funzione di coda di attività consiste nell'impostare la configurazione dei nuovi tentativi e della limitazione di frequenza per coda. Gli esempi di codice in questa pagina si basano su un'app che configura un servizio che esegue il backup di tutte le immagini della Astronomy Picture of the Day della NASA:

Configura le funzioni della coda di attività

Le funzioni della coda di attività sono dotate di un potente insieme di impostazioni di configurazione per controllare con precisione i limiti di frequenza e il comportamento dei nuovi tentativi di una coda di attività:

exports.backupApod = functions
    .runWith( {secrets: ["NASA_API_KEY"]})
    .tasks.taskQueue({
      retryConfig: {
        maxAttempts: 5,
        minBackoffSeconds: 60,
      },
      rateLimits: {
        maxConcurrentDispatches: 6,
      },
    }).onDispatch(async (data) => {
  • retryConfig.maxAttempts=5: ogni attività nella coda di attività viene ripetuta automaticamente fino a 5 volte. In questo modo, è possibile mitigare gli errori temporanei, come quelli di rete o l'interruzione temporanea di un servizio esterno dipendente.
  • retryConfig.minBackoffSeconds=60: ogni attività viene ritentata almeno 60 secondi dopo ogni tentativo. In questo modo, si crea un ampio margine tra un tentativo e l'altro, evitando di esaurire troppo rapidamente i 5 tentativi di ripetizione.
  • rateLimits.maxConcurrentDispatch=6: vengono inviate al massimo 6 attività alla volta. In questo modo, viene garantito un flusso costante di richieste alla funzione sottostante e si riduce il numero di istanze attive e di avvii a freddo.

Testa le funzioni della coda di attività

Nella maggior parte dei casi, l'emulatore Cloud Functions è il modo migliore per testare le funzioni della coda di attività. Consulta la documentazione di Emulator Suite per scoprire come strumentare la tua app per l'emulazione delle funzioni della coda di attività.

Inoltre, le funzioni della coda di attività vengono esposte come semplici funzioni HTTP in Firebase Local Emulator Suite. Puoi testare una funzione di attività emulata inviando una richiesta POST HTTP con un payload di dati JSON:

 # start the Firebase Emulators
 firebase emulators:start

 # trigger the emulated task queue function
 curl \
  -X POST                                            # An HTTP POST request...
  -H "content-type: application/json" \              # ... with a JSON body
  http://localhost:$PORT/$PROJECT_ID/$REGION/$NAME \ # ... to function url
  -d '{"data": { ... some data .... }}'              # ... with JSON encoded data

Esegui il deployment delle funzioni della coda di attività

Esegui il deployment della funzione della coda di attività utilizzando l'interfaccia a riga di comando di Firebase:

$ firebase deploy --only functions:backupApod

Quando esegui il deployment di una funzione della coda di attività per la prima volta, l'interfaccia a riga di comando crea una coda di attività in Cloud Tasks con le opzioni (limitazione di frequenza e nuovo tentativo) specificate nel codice sorgente.

Se si verificano errori di autorizzazione durante il deployment delle funzioni, assicurati che all'utente che esegue i comandi di deployment siano assegnati i ruoli IAM appropriati.

Inserisci in coda le funzioni della coda di attività

Le funzioni della coda di attività possono essere inserite in coda in Cloud Tasks da un ambiente server attendibile come Cloud Functions for Firebase utilizzando Firebase Admin SDK per Node.js. Se non hai mai utilizzato gli Admin SDK, consulta Aggiungi Firebase a un server per iniziare.

In un flusso tipico, Admin SDK crea una nuova attività, la mette in coda in Cloud Tasks e imposta la configurazione per l'attività:

exports.enqueueBackupTasks = functions.https.onRequest(
async (_request, response) => {
  const queue = getFunctions().taskQueue("backupApod");
  const enqueues = [];
  for (let i = 0; i <= 10; i += 1) {
    // Enqueue each task with i*60 seconds delay. Our task queue function
    // should process ~1 task/min.
    const scheduleDelaySeconds = i * 60 
    enqueues.push(
        queue.enqueue(
          { id: `task-${i}` },
          {
            scheduleDelaySeconds,
            dispatchDeadlineSeconds: 60 * 5 // 5 minutes
          },
        ),
    );
  }
  await Promise.all(enqueues);
  response.sendStatus(200);

});
  • scheduleDelaySeconds: il codice campione tenta di distribuire l'esecuzione delle attività associando un ritardo di N minuti all'N-esima attività. Ciò significa che viene attivata circa 1 attività al minuto. Tieni presente che puoi anche utilizzare scheduleTime se vuoi che Cloud Tasks attivi un'attività in un momento specifico.
  • dispatchDeadlineSeconds: tempo massimo di attesa di Cloud Tasks per il completamento di un'attività. Cloud Tasks riproverà l'attività seguendo la configurazione dei nuovi tentativi della coda o fino al raggiungimento di questa scadenza. Nell'esempio, la coda è configurata per riprovare l'attività fino a 5 volte, ma l'attività viene annullata automaticamente se l'intero processo (inclusi i tentativi di ripetizione) richiede più di 5 minuti.

Risoluzione dei problemi

Attiva il logging di Cloud Tasks

I log di Cloud Tasks contengono informazioni diagnostiche utili, come lo stato della richiesta associata a un'attività. Per impostazione predefinita, i log di Cloud Tasks sono disattivati a causa del volume elevato di log che possono potenzialmente generare nel tuo progetto. Ti consigliamo di attivare i log di debug durante lo sviluppo e il debug attivo delle funzioni della coda di attività. Consulta Attivazione del logging.

Autorizzazioni IAM

Potresti visualizzare errori PERMISSION DENIED quando metti in coda le attività o quando Cloud Tasks tenta di richiamare le funzioni della coda di attività. Assicurati che il tuo progetto abbia le seguenti associazioni IAM:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member=serviceAccount:${PROJECT_ID}@appspot.gserviceaccount.com \
  --role=roles/cloudtasks.enqueuer

  • L'identità utilizzata per accodare le attività in Cloud Tasks deve disporre dell'autorizzazione per utilizzare il service account associato a un'attività in Cloud Tasks.

    Nell'esempio, si tratta del service account predefinito di App Engine.

Consulta la documentazione di Google Cloud IAM per istruzioni su come aggiungere il service account predefinito App Engine come utente del service account predefinito App Engine.

gcloud functions add-iam-policy-binding $FUNCTION_NAME \
  --region=us-central1 \
  --member=serviceAccount:${PROJECT_ID}@appspot.gserviceaccount.com \
  --role=roles/cloudfunctions.invoker