Trigger di Google Cloud Firestore (1ª generazione)
Cloud Functions può gestire eventi in Cloud Firestore nello stesso progetto Google Cloud della funzione. Puoi leggere e/o aggiornare Cloud Firestore in risposta a questi eventi utilizzando le API e le librerie client di Firestore.
In un tipico ciclo di vita, una funzione di Cloud Firestore svolge le seguenti operazioni:
Attende le modifiche a un documento specifico.
Si attiva quando si verifica un evento e ne esegue le attività.
Riceve un oggetto dati con un'istantanea del documento interessato. Per gli eventi
write
oupdate
, l'oggetto dati contiene snapshot che rappresentano lo stato del documento prima e dopo l'evento di attivazione.
Tipi di evento
Cloud Firestore supporta gli eventi create
, update
, delete
e write
. L'evento write
include tutte le modifiche a un documento.
Tipo di evento | Trigger |
---|---|
providers/cloud.firestore/eventTypes/document.create (valore predefinito) |
Si attiva quando un documento viene scritto per la prima volta. |
providers/cloud.firestore/eventTypes/document.update |
Si attiva quando un documento esiste già e ha un valore modificato. |
providers/cloud.firestore/eventTypes/document.delete |
Si attiva quando viene eliminato un documento contenente dati. |
providers/cloud.firestore/eventTypes/document.write |
Si attiva quando un documento viene creato, aggiornato o eliminato. |
I caratteri jolly vengono scritti nei trigger utilizzando parentesi graffe, come segue:
"projects/YOUR_PROJECT_ID/databases/(default)/documents/collection/{document_wildcard}"
Specifica del percorso del documento
Per attivare la funzione, specifica un percorso del documento da ascoltare. Le funzioni rispondono solo alle modifiche ai documenti e non possono monitorare campi o raccolte specifici. Di seguito sono riportati alcuni esempi di percorsi di documenti validi:
users/marie
: attivatore valido. Monitora un singolo documento,/users/marie
.users/{username}
: attivatore 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. Fa riferimento alla sottoraccoltaaddresses
, non a un documento.users/{username}/addresses/home
: attivatore valido. Monitora il documento dell'indirizzo di casa per tutti gli utenti.users/{username}/addresses/{addressId}
: attivatore valido. Monitora tutti i documenti relativi agli indirizzi.
Utilizzo di caratteri jolly e parametri
Se non sai quale documento specifico vuoi monitorare, utilizza un {wildcard}
anziché l'ID del documento:
users/{username}
rimane in ascolto delle modifiche apportate a tutti i documenti dell'utente.
In questo esempio, quando un campo di un documento in users
viene modificato, corrisponde a un carattere jolly chiamato {username}
.
Se un documento in users
contiene sottoraccolte e un campo in una di queste sottoraccolte viene modificato, il carattere jolly {username}
non viene attivato.
Le corrispondenze con caratteri jolly vengono estratte dai percorsi dei documenti. Puoi definire tutti i caratteri jolly che vuoi per sostituire ID raccolta o documento espliciti.
Struttura dell'evento
Questo trigger richiama la tua funzione con un evento simile a quello mostrato di seguito:
{ "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
. Ciò è particolarmente utile se usi un linguaggio
digitato (come Go) per scrivere le funzioni.
Esempio di codice
La funzione Cloud Function di esempio riportata di seguito stampa i campi di un evento di attivazione di Cloud Firestore:
Node.js
Python
Go
Java
C#
Ruby
PHP
L'esempio seguente recupera il valore aggiunto dall'utente, converte la stringa in quella posizione in lettere maiuscole e sostituisce il valore con la stringa maiuscola:
Node.js
Python
Go
Java
C#
Ruby
PHP
Deployment della funzione
Il seguente comando gcloud
esegue il deployment di una funzione che viene attivata da eventi di scrittura sul documento /messages/{pushId}
:
gcloud functions deploy FUNCTION_NAME \ --entry-point ENTRY_POINT \ --runtime RUNTIME \ --trigger-event "providers/cloud.firestore/eventTypes/document.write" \ --trigger-resource "projects/YOUR_PROJECT_ID/databases/(default)/documents/messages/{pushId}"
Argomento | Descrizione |
---|---|
FUNCTION_NAME |
Il nome registrato della Cloud Function di cui stai eseguendo il deployment.
Può essere il nome di una funzione nel codice sorgente o una stringa arbitraria. Se FUNCTION_NAME è una stringa arbitraria, devi includere il flag --entry-point .
|
--entry-point ENTRY_POINT |
Il nome di una funzione o di una classe nel codice sorgente. Facoltativo, a meno che
tu non abbia utilizzato FUNCTION_NAME
per specificare la funzione
nel codice sorgente da eseguire durante il deployment. In questo caso, devi utilizzare --entry-point per fornire il nome della funzione eseguibile.
|
--runtime RUNTIME |
Il nome del runtime in uso. Per un elenco completo, consulta la documentazione di riferimento di gcloud .
|
--trigger-event NAME |
Il tipo di evento che verrà monitorato dalla funzione (uno tra
write , create , update o
delete ).
|
--trigger-resource NAME |
Il percorso completo del database in cui la funzione rimane in ascolto.
Deve essere conforme al seguente formato:
"projects/YOUR_PROJECT_ID/databases/(default)/documents/PATH"
Il testo {pushId} è un parametro carattere jolly descritto sopra
in Specifica del percorso del documento.
|
Limitazioni
Tieni presente le seguenti limitazioni per i trigger di Firestore per Cloud Functions:
- Cloud Functions (1ª generazione.) prerequisiti per un database "(predefinito)" esistente in modalità nativa di Firestore. Non supporta i database denominati Firestore o la modalità Datastore. Utilizza Cloud Functions (2ª generazione) per configurare gli eventi in questi casi.
- L'ordine non è garantito. Le modifiche rapide possono attivare chiamate di funzioni in modo imprevisto.
- Gli eventi vengono recapitati almeno una volta, ma un singolo evento potrebbe comportare più chiamate di funzioni. Evita di dipendere dalla meccanica "exactly-once" e scrivi funzioni idempotenti.
- Firestore in modalità Datastore richiede Cloud Functions (2nd gen). Cloud Functions (1ª generazione.) non supporta la modalità Datastore.
- Un trigger è associato a un singolo database. Non puoi creare un trigger corrispondente a più database.
- L'eliminazione di un database non elimina automaticamente i trigger per quel database. L'attivatore smette di pubblicare eventi, ma continua a esistere finché non lo elimini.
- Se un evento con corrispondenza supera la dimensione massima della richiesta, l'evento potrebbe non essere consegnato a Cloud Functions (1ª generazione).
- Gli eventi non recapitati a causa delle dimensioni della richiesta vengono registrati nei log della piattaforma e vengono conteggiati ai fini dell'utilizzo dei log per il progetto.
- Puoi trovare questi log in Esplora log con il messaggio "L'evento non può essere recapitato alla funzione Cloud Functions a causa del superamento del limite per la 1ª generazione..." con gravità
error
. Puoi trovare il nome della funzione sotto il campofunctionName
. Se il camporeceiveTimestamp
è ancora entro un'ora da adesso, puoi dedurre i contenuti effettivi dell'evento leggendo il documento in questione con un'istantanea prima e dopo il timestamp. - Per evitare questo ritmo, puoi:
- Migrazione a Cloud Functions (2nd gen) ed upgrade
- Ridimensiona il documento
- Elimina la funzione Cloud Functions in questione
- Puoi disattivare il logging stesso utilizzando le esclusioni, ma tieni presente che gli eventi offensivi non verranno comunque recapitati.