Trigger di Google Cloud Firestore (1ª generazione.)
Cloud Functions può gestire gli eventi in Firestore nello stesso progetto Google Cloud come funzione. Puoi leggere o aggiornare Firestore in risposta a queste utilizzando API e librerie client di Firestore.
In un ciclo di vita tipico, una funzione Firestore esegue quanto segue:
Attende le modifiche a un determinato documento.
Si attiva quando si verifica un evento ed esegue le sue attività.
Riceve un oggetto dati con uno snapshot del documento interessato. Per
write
oupdate
eventi, l'oggetto dati contiene snapshot che rappresentano prima e dopo l'evento di attivazione.
Tipi di evento
Firestore supporta gli eventi create
, update
, delete
e write
. La
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 presenta un valore modificato. |
providers/cloud.firestore/eventTypes/document.delete |
Si attiva quando un documento con dati viene eliminato. |
providers/cloud.firestore/eventTypes/document.write |
Si attiva quando un documento viene creato, aggiornato o eliminato. |
I caratteri jolly sono scritti nei trigger utilizzando parentesi graffe, come segue:
"projects/YOUR_PROJECT_ID/databases/(default)/documents/collection/{document_wildcard}"
Specificare il percorso del documento
Per attivare la funzione, specifica un percorso del documento da ascoltare. Solo funzioni rispondere alle modifiche ai documenti e non può monitorare campi specifici collections (raccolte). 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 sono utilizzata per monitorare tutti i documenti nella raccolta.users/{username}/addresses
: attivatore non valido. Fa riferimento alla sottoraccoltaaddresses
, non un documento.users/{username}/addresses/home
: attivatore valido. Monitora l'indirizzo di casa per tutti gli utenti.users/{username}/addresses/{addressId}
: attivatore valido. Monitora tutti gli indirizzi documenti.
Utilizzo di caratteri jolly e parametri
Se non conosci il documento specifico che vuoi monitorare, usa un {wildcard}
anziché l'ID documento:
users/{username}
rimane in ascolto delle modifiche a tutti i documenti dell'utente.
In questo esempio, quando viene modificato un campo in qualsiasi documento in users
,
corrisponde a un carattere jolly denominato {username}
.
Se un documento in users
ha
sottoraccolte e una
in una delle sottoraccolte documenti vengono modificati, {username}
il carattere jolly non viene attivato.
Le corrispondenze con caratteri jolly vengono estratte dai percorsi dei documenti. Puoi definire quanti caratteri jolly vuoi sostituire la raccolta esplicita o ID documento.
Struttura 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
. Consulta la documentazione di Value
per i riferimenti al tipo. Ciò è particolarmente utile se utilizzi una lingua digitata
(come Go) per scrivere le tue funzioni.
Esempio di codice
La Cloud Function di esempio riportata di seguito stampa i campi di un oggetto Cloud Evento Firestore:
Node.js
Python
Vai
Java
C#
Ruby
PHP
L'esempio riportato di seguito recupera il valore aggiunto dall'utente, converte la stringa in la posizione in lettere maiuscole e sostituisce il valore con la stringa in maiuscolo:
Node.js
Python
Vai
Java
C#
Ruby
PHP
esegui il deployment della funzione
Il seguente comando gcloud
esegue il deployment di una funzione che viene attivata
scrivi eventi 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 esegui il deployment.
Può essere il nome di una funzione nel
del codice sorgente o una stringa arbitraria. Se FUNCTION_NAME è un
stringa arbitraria, devi includere
Flag --entry-point .
|
--entry-point ENTRY_POINT |
Il nome di una funzione o classe nel codice sorgente. Facoltativo, a meno che
non hai utilizzato FUNCTION_NAME
per specificare
nel codice sorgente da eseguire durante il deployment. In questo
devi utilizzare --entry-point per indicare il nome del
una funzione eseguibile.
|
--runtime RUNTIME |
Il nome del runtime che stai utilizzando. Per un elenco completo, vedi
Riferimento gcloud .
|
--trigger-event NAME |
Il tipo di evento che la funzione monitorerà (uno dei
write , create , update o
delete ).
|
--trigger-resource NAME |
Il percorso completo del database in cui la funzione rimane in ascolto.
Deve rispettare il seguente formato:
"projects/YOUR_PROJECT_ID/databases/(default)/documents/PATH"
Il testo {pushId} è un parametro del carattere jolly descritto sopra
in Specificare il percorso del documento.
|
Limitazioni
Tieni presente le seguenti limitazioni per i trigger Firestore per Cloud Functions:
- Cloud Functions (1ª generazione.) prepara un prerequisito "(predefinito)" esistente in modalità nativa Firestore. Non supportare i database denominati Firestore o la modalità Datastore. Utilizza Cloud Functions (2ª generazione) per configurare gli eventi in questi casi.
- L'ordine non è garantito. Modifiche rapide possono attivare chiamate di funzione in un ordine inaspettato.
- Gli eventi vengono pubblicati almeno una volta, ma un singolo evento può comportare più chiamate di funzione. Da evitare in base a la meccanica "exactly-once" e scrivere funzioni idempotenti:
- Firestore in modalità Datastore richiede Cloud Functions (2nd gen). Cloud Functions (1ª generazione) non supportare la modalità Datastore.
- Un trigger è associato a un singolo database. Non puoi creare un trigger che corrisponde a più database.
- L'eliminazione di un database non elimina automaticamente alcun trigger per quel database. La interrompe la pubblicazione degli eventi, ma continua a esistere finché non elimini l'attivatore.
- Se un evento con corrispondenza supera le dimensioni massime della richiesta, il valore
potrebbe non essere stato consegnato a Cloud Functions (1ª generazione.).
- Gli eventi non consegnati a causa delle dimensioni della richiesta vengono registrati nei log della piattaforma e verranno conteggiate ai fini dell'utilizzo dei log da parte del progetto.
- Puoi trovare questi log in Esplora log con il messaggio "L'evento non può recapitare a
Funzione Cloud Functions a causa del superamento del limite per le dimensioni di 1ª generazione..." di
error
gravità. Puoi trovare il nome della funzione sotto il campofunctionName
. Se Se il camporeceiveTimestamp
si trova ancora a meno di un'ora da adesso, puoi dedurre i contenuti dell'evento effettivo leggendo il documento in questione con una uno snapshot prima e dopo il timestamp. - Per evitare questa frequenza, puoi:
- Esegui la migrazione e l'upgrade a Cloud Functions (2nd gen)
- Ridimensiona il documento
- Elimina le funzioni Cloud Functions in questione
- Puoi disattivare il logging utilizzando le esclusioni ma tieni presente che gli eventi offensivi non verranno comunque pubblicati.