Creare trigger con Firestore

Questa guida illustra le istruzioni per creare attivatori per i servizi e le funzioni Cloud Run dagli eventi Firestore.

Puoi configurare i servizi Cloud Run in modo che vengano attivati da eventi in un database Firestore. Quando viene attivato, il servizio legge e aggiorna un database Firestore in risposta a questi eventi tramite le API e le librerie client di Firestore.

In un ciclo di vita tipico, quando un servizio Cloud Run viene attivato da eventi Firestore, si verifica quanto segue:

  1. Il servizio attende modifiche a un determinato documento.

  2. Quando si verifica una modifica, il servizio viene attivato ed esegue le relative attività.

  3. Il servizio riceve un oggetto dati con uno snapshot del documento interessato. Per gli eventi write o update, l'oggetto dati contiene istantanee che rappresentano lo stato del documento prima e dopo l'evento di attivazione.

Tipi di evento

Firestore supporta gli eventi create, update, delete e write. L'evento write include tutte le modifiche a un documento.

Tipo di evento Trigger
google.cloud.firestore.document.v1.created (valore predefinito) Si attiva quando viene scritto per la prima volta in un documento.
google.cloud.firestore.document.v1.updated Viene attivato quando esiste già un documento e un valore è stato modificato.
google.cloud.firestore.document.v1.deleted Viene attivato quando viene eliminato un documento con dati.
google.cloud.firestore.document.v1.written Viene attivato quando un documento viene creato, aggiornato o eliminato.

I caratteri jolly vengono scritti negli attivatori utilizzando le parentesi graffe, ad esempio: projects/YOUR_PROJECT_ID/databases/(default)/documents/collection/{document_wildcard}

Specifica il percorso del documento

Per attivare il servizio, specifica un percorso del documento da ascoltare. Il percorso del documento deve trovarsi nello stesso progetto Google Cloud del servizio.

Ecco alcuni esempi di percorsi dei documenti validi:

  • users/marie: trigger valido. Monitora un singolo documento, /users/marie.

  • users/{username}: trigger valido. Monitora tutti i documenti dell'utente. I caratteri jolly vengono utilizzati per monitorare tutti i documenti della raccolta.

  • users/{username}/addresses: attivatore non valido. Si riferisce alla sottoraccoltaaddresses, non a un documento.

  • users/{username}/addresses/home: trigger valido. Monitora il documento dell'indirizzo di casa per tutti gli utenti.

  • users/{username}/addresses/{addressId}: trigger valido. Monitora tutti i documenti relativi all'indirizzo.

  • users/{user=**}: trigger valido. Monitora tutti i documenti utente e eventuali documenti nelle raccolte secondarie di ciascun documento utente, ad esempio /users/userID/address/home o /users/userID/phone/work.

Caratteri jolly e parametri

Se non conosci il documento specifico che vuoi monitorare, utilizza un {wildcard} instead of the document ID:

  • users/{username} rileva le modifiche a tutti i documenti degli utenti.

In questo esempio, quando un campo di qualsiasi documento in users viene modificato, corrisponde a un carattere jolly chiamato {username}.

Se un documento in users ha sottocollezioni e un campo in uno dei documenti di queste sottocollezioni viene modificato, il carattere jolly {username} non viene attivato. Se il tuo obiettivo è rispondere anche agli eventi nelle raccolte secondarie, utilizza il carattere jolly multisegmento {username=**}.

Le corrispondenze con caratteri jolly vengono estratte dai percorsi dei documenti. Puoi definire quanti simboli jolly vuoi per sostituire ID raccolta o documento espliciti. Puoi utilizzare fino a un carattere jolly multisegmento come {username=**}.

Strutture di eventi

Questo trigger invoca il servizio con un evento simile a: 

{
    "oldValue": { // Update and Delete operations only
        A Document object containing a pre-operation document snapshot
    },
    "updateMask": { // Update operations only
        A DocumentMask object that lists changed fields.
    },
    "value": {
        // A Document object containing a post-operation document snapshot
    }
}

Ogni oggetto Document contiene uno o più oggetti Value. Per i riferimenti ai tipi, consulta la documentazione di Value.

Prima di iniziare

  1. Assicurati di aver configurato un nuovo progetto per Cloud Run come descritto nella pagina di configurazione.

  2. Abilita le API Artifact Registry, Cloud Build, Cloud Run Admin, Eventarc, Firestore Cloud Logging e Pub/Sub:

    Abilita le API

Ruoli obbligatori

  1. Se sei il creator del progetto, ti viene concesso il ruolo di proprietario di base (roles/owner). Per impostazione predefinita, questo ruolo IAM include le autorizzazioni necessarie per l'accesso completo alla maggior parte delle risorse Google Cloud e puoi saltare questo passaggio.

    Se non sei il creator del progetto, le autorizzazioni richieste devono essere concesse al principale appropriato. Ad esempio, un'entità può essere un Account Google (per gli utenti finali) o un account di servizio (per le applicazioni e i carichi di lavoro di calcolo). Per ulteriori informazioni, consulta la pagina Ruoli e autorizzazioni relativa alla destinazione dell'evento.

    Tieni presente che per impostazione predefinita, le autorizzazioni di Cloud Build includono le autorizzazioni per caricare e scaricare gli elementi di Artifact Registry.

    Autorizzazioni obbligatorie

    Per ottenere le autorizzazioni necessarie per configurare gli attivatori Firestore, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

    Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

    Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

  2. Prendi nota dell'account di servizio predefinito di Compute Engine, poiché lo collegherai a un trigger Eventarc per rappresentare l'identità dell'trigger a fini di test. Questo account di servizio viene creato automaticamente dopo aver attivato o utilizzato un servizio Google Cloud che utilizza Compute Engine e con il seguente formato email:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Sostituisci PROJECT_NUMBER con il numero del tuo progetto Google Cloud. Puoi trovare il numero del progetto nella pagina Welcome della console Google Cloud o eseguendo il seguente comando:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

    Per gli ambienti di produzione, ti consigliamo vivamente di creare un nuovo account di servizio e di assegnargli uno o più ruoli IAM contenenti le autorizzazioni minime richieste e di seguire il principio del privilegio minimo.

  3. Per impostazione predefinita, i servizi Cloud Run sono richiamabili solo dai proprietari, dagli editor e dagli amministratori e dagli invocatori di progetti Cloud Run. Puoi controllare l'accesso in base al servizio. Tuttavia, per scopi di test, concedi il ruolo invocatore Cloud Run (run.invoker) nel progetto Google Cloud all'account di servizio Compute Engine. In questo modo, il ruolo viene concesso a tutti i servizi e i job Cloud Run di un progetto. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker

    Tieni presente che se crei un trigger per un servizio Cloud Run autenticato senza concedere il ruolo Invoker di Cloud Run, l'trigger viene creato correttamente ed è attivo. Tuttavia, l'attivatore non funzionerà come previsto e nei log verrà visualizzato un messaggio simile al seguente:

    The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
  4. Concedi il ruolo Riepilogatore eventi Eventarc (roles/eventarc.eventReceiver) sul progetto all'account di servizio predefinito di Compute Engine in modo che l'attivatore Eventarc possa ricevere eventi dai fornitori di eventi. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver
  5. Se hai attivato l'agente di servizio Cloud Pub/Sub il giorno 8 aprile 2021 o in una data precedente per supportare le richieste push Pub/Sub autenticate, concedi all'agente di servizio il ruolo Creatore token account di servizio (roles/iam.serviceAccountTokenCreator). In caso contrario, questo ruolo viene concesso per impostazione predefinita: 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

Configurare il database Firestore

Prima di eseguire il deployment del servizio, devi creare un database Firestore:

  1. Vai alla pagina Dati Firestore.

  2. Seleziona Crea database.

  3. Fai clic su Modalità nativa e poi seleziona Continua.

  4. Nel campo Assegna un nome al database, inserisci un ID database, ad esempio firestore-db.

  5. In Tipo di località, seleziona Regione e scegli la regione in cui deve risiedere il database. Questa scelta è definitiva.

  6. Lascia invariata la sezione Regole di protezione.

  7. Fai clic su Crea database.

Il modello dati di Firestore è costituito da raccolte che contengono documenti. Un documento contiene un insieme di coppie chiave-valore.

Creazione di trigger

A seconda del tipo di servizio di cui stai eseguendo il deployment, puoi:

Creare un attivatore per i servizi

Puoi specificare un trigger dopo aver eseguito il deployment di un servizio.

Fai clic sulla scheda per le istruzioni relative allo strumento che preferisci.

Console

  1. Esegui il deployment del servizio Cloud Run utilizzando container o da sorgente.

  2. Nella console Google Cloud, vai a Cloud Run:

    Vai a Cloud Run

  3. Nell'elenco dei servizi, fai clic su un servizio esistente.

  4. Nella pagina Dettagli servizio, vai alla scheda Trigger.

  5. Fai clic su Aggiungi attivatore e seleziona Attatore Firestore.

  6. Nel riquadro Trigger Eventarc, modifica i dettagli dell'attivatore come segue:

    1. Nel campo Nome attivatore, inserisci un nome per l'attivatore o utilizza il nome predefinito.

    2. Seleziona un Tipo di attivatore dall'elenco per specificare uno dei seguenti tipi di attivatore:

      • Origini Google per specificare gli trigger per Pub/Sub, Cloud Storage, Firestore e altri fornitori di eventi Google.

      • Di terze parti per l'integrazione con fornitori non Google che offrono un'origine Eventarc. Per ulteriori informazioni, consulta Eventi di terze parti in Eventarc.

    3. Seleziona Firestore dall'elenco Provider di eventi per selezionare un prodotto che fornisce il tipo di evento per attivare il servizio. Per l'elenco dei fornitori di eventi, consulta Fornitori e destinazioni di eventi.

    4. Seleziona type=google.cloud.firestore.document.v1.created dall'elenco Tipo di evento. La configurazione dell'attivatore varia a seconda del tipo di evento supportato. Per saperne di più, consulta Tipi di eventi.

    5. Nella sezione Filtri, seleziona un database, un'operazione e i valori degli attributi oppure utilizza le selezioni predefinite.

    6. Se il campo Regione è attivato, seleziona una località per l'attivatore Eventarc. In generale, la posizione di un trigger Eventarc deve corrispondere alla posizione della risorsa Google Cloud per la quale vuoi monitorare gli eventi. Nella maggior parte dei casi, devi anche eseguire il deployment del servizio nella stessa regione. Consulta la sezione Informazioni sulle località Eventarc per ulteriori dettagli sulle località dei trigger Eventarc.

    7. Nel campo Account di servizio, seleziona un account di servizio. Gli attivatori Eventarc sono collegati agli account di servizio da usare come identità quando viene invocato il servizio. L'account di servizio dell'attivatore Eventarc deve disporre dell'autorizzazione per richiamare il servizio. Per impostazione predefinita, Cloud Run utilizza l'account di servizio predefinito di Compute Engine.

    8. Se vuoi, specifica il percorso dell'URL del servizio a cui inviare la richiesta in arrivo. Si tratta del percorso relativo nel servizio di destinazione a cui devono essere inviati gli eventi per l'attivatore. Ad esempio: /, /route, route e route/subroute.

    9. Dopo aver compilato i campi obbligatori, fai clic su Salva trigger.

  7. Dopo aver creato l'attivatore, verificane l'integrità assicurandoti che sia presente un segno di spunta nella scheda Attivatori.

gcloud

  1. Esegui il deployment del servizio Cloud Run utilizzando container o da sorgente.

  2. Esegui il comando seguente per creare un attivatore che filtra gli eventi:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=SERVICE  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.firestore.document.v1.created" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Sostituisci:

    • TRIGGER_NAME con il nome dell'attivatore.

    • EVENTARC_TRIGGER_LOCATION con la posizione per l'trigger Eventarc. In generale, la posizione di un trigger Eventarc deve corrispondere alla posizione della risorsa Google Cloud che vuoi monitorare per rilevare gli eventi. Nella maggior parte dei casi, devi anche eseguire il deployment del servizio nella stessa regione. Per ulteriori informazioni, consulta Località Eventarc.

    • SERVICE con il nome del servizio che stai implementando.

    • REGION con la regione Cloud Run del servizio.

    • PROJECT_NUMBER con il numero del tuo progetto Google Cloud. Gli attivatori Eventarc sono collegati agli account di servizio da utilizzare come identità quando viene invocato il servizio. L'account di servizio dell'attivatore Eventarc deve disporre dell'autorizzazione per richiamare il servizio. Per impostazione predefinita, Cloud Run utilizza l'account di servizio Compute predefinito.

    • Il flag event-filters specifica i filtri eventi monitorati dall'attivatore. Un evento che corrisponde a tutti i filtri event-filters attiva le chiamate al tuo servizio. Ogni attivatore deve avere un tipo di evento supportato. Non puoi modificare il tipo di filtro evento dopo la creazione. Per modificare il tipo di filtro evento, devi creare un nuovo attivatore ed eliminare quello precedente. Se vuoi, puoi ripetere il flag --event-filters con un filtro supportato nel formato ATTRIBUTE=VALUE per aggiungere altri filtri.

Creare un trigger per le funzioni

Fai clic sulla scheda per le istruzioni relative allo strumento che preferisci.

Console

Quando utilizzi la console Google Cloud per creare una funzione, puoi anche aggiungere un trigger. Per creare un attivatore per la funzione:

  1. Nella console Google Cloud, vai a Cloud Run:

    Vai a Cloud Run

  2. Fai clic su Scrivi una funzione e inserisci i dettagli della funzione. Per ulteriori informazioni sulla configurazione delle funzioni durante il deployment, consulta Eseguire il deployment delle funzioni.

  3. Nella sezione Attivazione, fai clic su Aggiungi attivatore.

  4. Seleziona Trigger di Firestore.

  5. Nel riquadro Trigger Eventarc, modifica i dettagli dell'attivatore come segue:

    1. Inserisci un nome per l'attivatore nel campo Nome trigger o utilizza il nome predefinito.

    2. Seleziona un Tipo di attivatore dall'elenco per specificare uno dei seguenti tipi di attivatore:

      • Origini Google per specificare gli trigger per Pub/Sub, Cloud Storage, Firestore e altri fornitori di eventi Google.

      • Di terze parti per l'integrazione con fornitori non Google che offrono un'origine Eventarc. Per ulteriori informazioni, consulta Eventi di terze parti in Eventarc.

    3. Seleziona Firestore dall'elenco Provider di eventi per selezionare un prodotto che fornisce il tipo di evento per attivare la funzione. Per l'elenco dei fornitori di eventi, consulta Fornitori e destinazioni di eventi.

    4. Seleziona type=google.cloud.firestore.document.v1.created dall'elenco Tipo di evento. La configurazione dell'attivatore varia a seconda del tipo di evento supportato. Per saperne di più, consulta Tipi di eventi.

    5. Nella sezione Filtri, seleziona un database, un'operazione e i valori degli attributi oppure utilizza le selezioni predefinite.

    6. Se il campo Regione è attivato, seleziona una località per l'attivatore Eventarc. In generale, la posizione di un trigger Eventarc deve corrispondere alla posizione della risorsa Google Cloud per la quale vuoi monitorare gli eventi. Nella maggior parte degli scenari, devi anche eseguire il deployment della funzione nella stessa regione. Consulta la sezione Informazioni sulle località Eventarc per ulteriori dettagli sulle località dei trigger Eventarc.

    7. Nel campo Account di servizio, seleziona un account di servizio. Gli attivatori Eventarc sono collegati agli account di servizio da usare come identità quando viene invocata la funzione. L'account di servizio dell'attivatore Eventarc deve disporre dell'autorizzazione per richiamare la funzione. Per impostazione predefinita, Cloud Run utilizza l'account di servizio predefinito di Compute Engine.

    8. Se vuoi, specifica il percorso dell'URL del servizio a cui inviare la richiesta in arrivo. Si tratta del percorso relativo nel servizio di destinazione a cui devono essere inviati gli eventi per l'attivatore. Ad esempio: /, /route, route e route/subroute.

  6. Dopo aver compilato i campi obbligatori, fai clic su Salva trigger.

gcloud

Quando crei una funzione utilizzando gcloud CLI, devi prima eseguirne il deployment e poi creare un attivatore. Per creare un attivatore per la funzione:

  1. Esegui il seguente comando nella directory contenente il codice campione per eseguire il deployment della funzione:

    gcloud beta run deploy FUNCTION \
        --source . \
        --function FUNCTION_ENTRYPOINT \
        --base-image BASE_IMAGE_ID \
        --region REGION

    Sostituisci:

    • FUNCTION con il nome della funzione di cui stai eseguendo il deployment. Puoi omettere del tutto questo parametro, ma se lo fai ti verrà chiesto il nome.

    • FUNCTION_ENTRYPOINT con il punto di ingresso della funzione nel codice sorgente. Questo è il codice che Cloud Run esegue quando viene eseguita la funzione. Il valore di questo flag deve essere un nome di funzione o un nome di classe completamente qualificato esistente nel codice sorgente.

    • BASE_IMAGE_ID con l'ambiente dell'immagine di base per la funzione. Per ulteriori dettagli sulle immagini di base e sui pacchetti inclusi in ogni immagine, consulta Immagini di base dei runtime.

    • REGION con la regione Google Cloud in cui vuoi eseguire il deployment della funzione. Ad esempio: us-central1.

  2. Esegui il comando seguente per creare un attivatore che filtra gli eventi:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=FUNCTION  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.firestore.document.v1.created" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Sostituisci:

    • TRIGGER_NAME con il nome dell'attivatore.

    • EVENTARC_TRIGGER_LOCATION con la posizione per l'trigger Eventarc. In generale, la posizione di un trigger Eventarc deve corrispondere alla posizione della risorsa Google Cloud che vuoi monitorare per rilevare gli eventi. Nella maggior parte degli scenari, devi anche eseguire il deployment della funzione nella stessa regione. Per ulteriori informazioni, consulta Località Eventarc.

    • FUNCTION con il nome della funzione di cui stai eseguendo il deployment.

    • REGION con la regione Cloud Run della funzione.

    • PROJECT_NUMBER con il numero del tuo progetto Google Cloud. Gli attivatori Eventarc sono collegati agli account di servizio da utilizzare come identità quando viene invocata la funzione. L'account di servizio dell'attivatore Eventarc deve disporre dell'autorizzazione per richiamare la funzione. Per impostazione predefinita, Cloud Run utilizza l'account di servizio Compute predefinito.

    • Il flag event-filters specifica i filtri eventi monitorati dall'attivatore. Un evento che corrisponde a tutti i filtri event-filters attiva le chiamate alla funzione. Ogni attivatore deve avere un tipo di evento supportato. Non puoi modificare il tipo di filtro evento dopo la creazione. Per modificare il tipo di filtro evento, devi creare un nuovo attivatore ed eliminare quello precedente. Se vuoi, puoi ripetere il flag --event-filters con un filtro supportato nel formato ATTRIBUTE=VALUE per aggiungere altri filtri.

Passaggi successivi

  • Consulta gli esempi di funzioni attivate quando apporti modifiche a un documento all'interno di una raccolta specificata.