Questa guida mostra esempi di funzioni attivate quando apporti modifiche a un documento all'interno di una raccolta specificata.
Prima di iniziare
Prima di eseguire il codice campione in questa guida, devi:
- Abilita le API e concedi i ruoli richiesti per il deployment delle funzioni
- Configura un database Firestore
Esempi
I seguenti esempi mostrano come scrivere funzioni che rispondono a un trigger Firestore.
Esempio 1: funzione Hello Firestore
Il seguente esempio stampa i campi di un evento Firestore di attivazione:
Node.js
Python
Go
Java
C#
Esegui il deployment della funzione Hello Firestore
Se non l'hai ancora fatto, configura il tuo database Firestore.
Fai clic sulla scheda relativa alle istruzioni per l'utilizzo dello strumento che preferisci.
Console
Quando utilizzi la console Google Cloud per creare una funzione, puoi anche aggiungere un trigger alla funzione. Per creare un trigger per la tua funzione:
Nella console Google Cloud , vai a Cloud Run:
Fai clic su Scrivi una funzione e inserisci i dettagli della funzione. Per saperne di più sulla configurazione delle funzioni durante il deployment, consulta Eseguire il deployment delle funzioni.
Nella sezione Attivatore, fai clic su Aggiungi attivatore.
Seleziona Trigger di Firestore.
Nel riquadro Trigger Eventarc, modifica i dettagli del trigger come segue:
Inserisci un nome per il trigger nel campo Nome trigger o utilizza il nome predefinito.
Seleziona un tipo di trigger dall'elenco per specificare uno dei seguenti tipi di trigger:
Origini Google per specificare i trigger per Pub/Sub, Cloud Storage, Firestore e altri fornitori di eventi Google.
Terze parti per l'integrazione con provider non Google che offrono un'origine Eventarc. Per saperne di più, vedi Eventi di terze parti in Eventarc.
Seleziona Firestore dall'elenco Provider di eventi per selezionare un prodotto che fornisca il tipo di evento per attivare la funzione. Per l'elenco dei fornitori di eventi, consulta Provider e destinazioni di eventi.
Seleziona type=google.cloud.firestore.document.v1.written dall'elenco Tipo di evento. La configurazione del trigger varia a seconda del tipo di evento supportato. Per saperne di più, vedi Tipi di eventi.
Nella sezione Filtri, seleziona un database, un'operazione e i valori degli attributi oppure utilizza le selezioni predefinite.
Se il campo Regione è attivato, seleziona una posizione per il trigger Eventarc. In generale, la località di un trigger Eventarc deve corrispondere a quella della risorsa che vuoi monitorare per gli eventi. Google Cloud 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.
Nel campo Service account, seleziona un account di servizio. I trigger Eventarc sono collegati agli account di servizio da utilizzare come identità quando viene richiamata la funzione. Il account di servizio del trigger Eventarc deve disporre dell'autorizzazione per richiamare la funzione. Per impostazione predefinita, Cloud Run utilizza l'account di servizio predefinito di Compute Engine.
(Facoltativo) Specifica il percorso dell'URL del servizio a cui inviare la richiesta in entrata. Questo è il percorso relativo nel servizio di destinazione a cui devono essere inviati gli eventi per il trigger. Ad esempio:
/
,/route
,route
eroute/subroute
.
Una volta compilati i campi obbligatori, fai clic su Salva attivatore.
gcloud
Quando crei una funzione utilizzando gcloud CLI, devi prima eseguirne il deployment e poi creare un trigger. Per creare un trigger per la tua funzione:
Esegui questo comando nella directory che contiene il codice campione per eseguire il deployment della funzione:
gcloud run deploy FUNCTION \ --source . \ --function FUNCTION_ENTRYPOINT \ --base-image BASE_IMAGE_ID \ --region REGION
Sostituisci:
FUNCTION con il nome della funzione che stai eseguendo il deployment. Puoi omettere completamente questo parametro, ma ti verrà chiesto il nome se lo ometti.
FUNCTION_ENTRYPOINT con l'entry point della tua funzione nel codice sorgente. Questo è il codice eseguito da Cloud Run quando viene eseguita la funzione. Il valore di questo flag deve essere un nome di funzione o un nome di classe completo che esiste nel codice sorgente.
BASE_IMAGE_ID con l'ambiente dell'immagine di base per la tua funzione. Per maggiori dettagli sulle immagini di base e sui pacchetti inclusi in ciascuna immagine, consulta Immagini di base dei runtime.
REGION con la Google Cloud regione in cui vuoi eseguire il deployment della funzione. Ad esempio:
europe-west1
.
Esegui questo comando per creare un trigger che filtri 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.written \ --event-filters=database='(default)' \ --event-data-content-type=application/protobuf \ --event-filters-path-pattern=document='users/{username}' \ --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com
Sostituisci:
TRIGGER_NAME con il nome dell'attivatore.
EVENTARC_TRIGGER_LOCATION con la località del trigger Eventarc. In generale, la località di un trigger Eventarc deve corrispondere a quella della risorsa Google Cloud che vuoi monitorare per gli eventi. Nella maggior parte degli scenari, devi anche eseguire il deployment della funzione nella stessa regione. Per saperne di più, consulta Località Eventarc.
FUNCTION con il nome della funzione che stai eseguendo il deployment.
REGION con la regione di Cloud Run della funzione.
PROJECT_NUMBER con il numero del tuo progetto Google Cloud . I trigger Eventarc sono collegati agli account di servizio da utilizzare come identità quando viene richiamata la funzione. Il account di servizio del trigger 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 dal trigger. Un evento che corrisponde a tutti ievent-filters
, i filtri attiva le chiamate alla tua funzione. Ogni attivatore deve avere un tipo di evento supportato. Non puoi modificare il tipo di filtro eventi dopo la creazione. Per modificare il tipo di filtro eventi, devi creare un nuovo trigger ed eliminare quello precedente. (Facoltativo) Puoi ripetere il flag--event-filters
con un filtro supportato nel formatoATTRIBUTE=VALUE
per aggiungere altri filtri.
Terraform
Per creare un trigger Eventarc per una funzione Cloud Run, consulta Creare un trigger utilizzando Terraform.
Utilizza gli altri campi così come sono:
--event-filters=type=google.cloud.firestore.document.v1.written
specifica che la funzione viene attivata quando un documento viene creato, aggiornato o eliminato, in base algoogle.cloud.firestore.document.v1.written
tipo di evento.--event-filters=database='(default)'
specifica il database Firebase. Per il nome del database predefinito, utilizza(default)
.--event-filters-path-pattern=document='users/{username}'
fornisce il pattern del percorso dei documenti da monitorare per rilevare le modifiche pertinenti. Questo pattern di percorso indica che tutti i documenti nella raccoltausers
devono essere monitorati. Per saperne di più, consulta Informazioni sui pattern di percorso.
Testare la funzione Hello Firestore
Per testare la funzione Hello Firestore, configura una raccolta denominata
users
nel tuo database Firestore:
Nella console Google Cloud , vai alla pagina dei database Firestore:
Fai clic su Avvia una raccolta.
Specifica
users
come ID raccolta.Per iniziare ad aggiungere il primo documento della raccolta, accetta l'ID documento generato automaticamente in Aggiungi il primo documento.
Aggiungi almeno un campo per il documento, specificando un nome e un valore. Ad esempio, in Nome campo, inserisci
username
e in Valore campo, inseriscirowan
.Quando hai terminato, fai clic su Salva.
Questa azione crea un nuovo documento, attivando così la funzione.
Per verificare che la funzione sia stata attivata, fai clic sul nome collegato della funzione nella console Google Cloud pagina Panoramica di Cloud Run per aprire la pagina Dettagli servizio.
Seleziona la scheda Log e cerca questa stringa:
Function triggered by change to: //firestore.googleapis.com/projects/your-project-id/databases/(default)'
Esempio 2: funzione Converti in maiuscolo
L'esempio seguente recupera il valore aggiunto dall'utente, converte la stringa in quella posizione in maiuscolo e sostituisce il valore con la stringa in maiuscolo:
Node.js
Utilizza protobufjs per decodificare i dati
dell'evento. Includi google.events.cloud.firestore.v1
data.proto
nella fonte.
Python
Go
Java
C#
Esegui il deployment della funzione Converti in maiuscolo
Se non l'hai ancora fatto, configura il tuo database Firestore.
Fai clic sulla scheda relativa alle istruzioni per l'utilizzo dello strumento che preferisci.
Console
Quando utilizzi la console Google Cloud per creare una funzione, puoi anche aggiungere un trigger alla funzione. Per creare un trigger per la tua funzione:
Nella console Google Cloud , vai a Cloud Run:
Fai clic su Scrivi una funzione e inserisci i dettagli della funzione. Per saperne di più sulla configurazione delle funzioni durante il deployment, consulta Eseguire il deployment delle funzioni.
Nella sezione Attivatore, fai clic su Aggiungi attivatore.
Seleziona Trigger di Firestore.
Nel riquadro Trigger Eventarc, modifica i dettagli del trigger come segue:
Inserisci un nome per il trigger nel campo Nome trigger o utilizza il nome predefinito.
Seleziona un tipo di trigger dall'elenco per specificare uno dei seguenti tipi di trigger:
Origini Google per specificare i trigger per Pub/Sub, Cloud Storage, Firestore e altri fornitori di eventi Google.
Terze parti per l'integrazione con provider non Google che offrono un'origine Eventarc. Per saperne di più, vedi Eventi di terze parti in Eventarc.
Seleziona Firestore dall'elenco Provider di eventi per selezionare un prodotto che fornisca il tipo di evento per attivare la funzione. Per l'elenco dei fornitori di eventi, consulta Provider e destinazioni di eventi.
Seleziona type=google.cloud.firestore.document.v1.written dall'elenco Tipo di evento. La configurazione del trigger varia a seconda del tipo di evento supportato. Per saperne di più, vedi Tipi di eventi.
Nella sezione Filtri, seleziona un database, un'operazione e i valori degli attributi oppure utilizza le selezioni predefinite.
Se il campo Regione è attivato, seleziona una posizione per il trigger Eventarc. In generale, la località di un trigger Eventarc deve corrispondere a quella della risorsa che vuoi monitorare per gli eventi. Google Cloud 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.
Nel campo Service account, seleziona un account di servizio. I trigger Eventarc sono collegati agli account di servizio da utilizzare come identità quando viene richiamata la funzione. Il account di servizio del trigger Eventarc deve disporre dell'autorizzazione per richiamare la funzione. Per impostazione predefinita, Cloud Run utilizza l'account di servizio predefinito di Compute Engine.
(Facoltativo) Specifica il percorso dell'URL del servizio a cui inviare la richiesta in entrata. Questo è il percorso relativo nel servizio di destinazione a cui devono essere inviati gli eventi per il trigger. Ad esempio:
/
,/route
,route
eroute/subroute
.
Una volta compilati i campi obbligatori, fai clic su Salva attivatore.
gcloud
Quando crei una funzione utilizzando gcloud CLI, devi prima eseguirne il deployment e poi creare un trigger. Per creare un trigger per la tua funzione:
Esegui questo comando nella directory che contiene il codice campione per eseguire il deployment della funzione:
gcloud run deploy FUNCTION \ --source . \ --function FUNCTION_ENTRYPOINT \ --base-image BASE_IMAGE_ID \ --region REGION
Sostituisci:
FUNCTION con il nome della funzione che stai eseguendo il deployment. Puoi omettere completamente questo parametro, ma ti verrà chiesto il nome se lo ometti.
FUNCTION_ENTRYPOINT con l'entry point della tua funzione nel codice sorgente. Questo è il codice eseguito da Cloud Run quando viene eseguita la funzione. Il valore di questo flag deve essere un nome di funzione o un nome di classe completo che esiste nel codice sorgente.
BASE_IMAGE_ID con l'ambiente dell'immagine di base per la tua funzione. Per maggiori dettagli sulle immagini di base e sui pacchetti inclusi in ciascuna immagine, consulta Immagini di base dei runtime.
REGION con la Google Cloud regione in cui vuoi eseguire il deployment della funzione. Ad esempio:
europe-west1
.
Esegui questo comando per creare un trigger che filtri 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.written \ --event-filters=database='(default)' \ --event-data-content-type=application/protobuf \ --event-filters-path-pattern=document='messages/{pushId}' \ --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com
Sostituisci:
TRIGGER_NAME con il nome dell'attivatore.
EVENTARC_TRIGGER_LOCATION con la località del trigger Eventarc. In generale, la località di un trigger Eventarc deve corrispondere a quella della risorsa Google Cloud che vuoi monitorare per gli eventi. Nella maggior parte degli scenari, devi anche eseguire il deployment della funzione nella stessa regione. Per saperne di più, consulta Località Eventarc.
FUNCTION con il nome della funzione che stai eseguendo il deployment.
REGION con la regione di Cloud Run della funzione.
PROJECT_NUMBER con il numero del tuo progetto Google Cloud . I trigger Eventarc sono collegati agli account di servizio da utilizzare come identità quando viene richiamata la funzione. Il account di servizio del trigger 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 dal trigger. Un evento che corrisponde a tutti ievent-filters
, i filtri attiva le chiamate alla tua funzione. Ogni attivatore deve avere un tipo di evento supportato. Non puoi modificare il tipo di filtro eventi dopo la creazione. Per modificare il tipo di filtro eventi, devi creare un nuovo trigger ed eliminare quello precedente. (Facoltativo) Puoi ripetere il flag--event-filters
con un filtro supportato nel formatoATTRIBUTE=VALUE
per aggiungere altri filtri.
Terraform
Per creare un trigger Eventarc per una funzione Cloud Run, consulta Creare un trigger utilizzando Terraform.
Utilizza gli altri campi così come sono:
--event-filters=type=google.cloud.firestore.document.v1.written
specifica che la funzione viene attivata quando un documento viene creato, aggiornato o eliminato, in base algoogle.cloud.firestore.document.v1.written
tipo di evento.--event-filters=database='(default)'
specifica il database Firestore. Per il nome del database predefinito, utilizza(default)
.--event-filters-path-pattern=document='messages/{pushId}'
fornisce il pattern del percorso dei documenti che devono essere monitorati per rilevare modifiche pertinenti. Questo pattern di percorso indica che tutti i documenti nella raccoltamessages
devono essere monitorati. Per saperne di più, consulta Informazioni sui pattern di percorso.
Testare la funzione Converti in maiuscolo
Per testare la funzione Converti in maiuscolo che hai appena implementato, configura
una raccolta denominata messages
nel tuo
database Firestore:
Nella console Google Cloud , vai alla pagina dei database Firestore:
Fai clic su Avvia una raccolta.
Specifica
messages
come ID raccolta.Per iniziare ad aggiungere il primo documento della raccolta, accetta l'ID documento generato automaticamente in Aggiungi il primo documento.
Per attivare la funzione di cui è stato eseguito il deployment, aggiungi un documento in cui il Nome campo è
original
e il Valore campo èminka
.Quando salvi il documento, puoi vedere la parola in minuscolo nel campo valore convertita in maiuscolo.
Se in seguito modifichi il valore del campo in modo che contenga lettere minuscole, la funzione viene attivata di nuovo e converte tutte le lettere minuscole in maiuscole.
Limitazioni per le funzioni
- L'ordinamento non è garantito. Le modifiche rapide possono attivare le chiamate di funzione in un ordine imprevisto.
- Gli eventi vengono inviati almeno una volta, ma un singolo evento può comportare più chiamate di funzione. Evita di fare affidamento sulla meccanica di esecuzione esattamente una volta e scrivi funzioni idempotenti.
- Un trigger è associato a un singolo database. Non puoi creare un trigger che corrisponda a più database.
- L'eliminazione di un database non comporta l'eliminazione automatica di eventuali trigger per quel database. Il trigger smette di generare eventi, ma continua a esistere finché non lo elimini.