Estendi con Cloud Functions (2nd gen)
Con Cloud Functions puoi eseguire il deployment di codice per gestire gli eventi attivati dalle modifiche del database Firestore. Ciò consente di aggiungere funzionalità lato server senza utilizzare i tuoi server.
Estendi Firestore con Cloud Functions (2nd gen)
Cloud Functions (2nd gen) supporta i seguenti attivatori di eventi Firestore per consentirti di creare gestori legati agli eventi Firestore:
Tipo di evento | Trigger |
---|---|
google.cloud.firestore.document.v1.created |
Si attiva quando un documento viene scritto per la prima volta. |
google.cloud.firestore.document.v1.updated |
Si attiva quando un documento esiste già e ha un valore modificato. |
google.cloud.firestore.document.v1.deleted |
Si attiva quando viene eliminato un documento. |
google.cloud.firestore.document.v1.written |
Si attiva quando vengono attivati created , updated o deleted . |
google.cloud.firestore.document.v1.created.withAuthContext |
Come created , ma aggiunge informazioni di autenticazione. |
google.cloud.firestore.document.v1.updated.withAuthContext |
Come updated , ma aggiunge informazioni di autenticazione. |
google.cloud.firestore.document.v1.deleted.withAuthContext |
Come deleted , ma aggiunge informazioni di autenticazione. |
google.cloud.firestore.document.v1.written.withAuthContext |
Come written , ma aggiunge informazioni di autenticazione. |
Gli eventi Firestore vengono attivati solo in caso di modifiche ai documenti. Un aggiornamento di un documento Firestore in cui i dati non sono stati modificati (scrittura no-op) non genera un evento di aggiornamento o scrittura. Non è possibile aggiungere eventi a campi specifici.
Includi il contesto di autenticazione nell'evento
Per includere ulteriori informazioni di autenticazione sull'evento, utilizza un attivatore di evento con l'estensione withAuthContext
. Questa estensione aggiunge ulteriori informazioni
sull'entità che ha attivato l'evento. Aggiunge gli attributi authtype
e authid
oltre alle informazioni restituite nell'evento di base. Consulta il riferimento authcontext
per ulteriori informazioni sui valori degli attributi.
Scrivi una funzione attivata da Firestore
Per scrivere una funzione che risponda agli eventi Firestore, preparati a specificare quanto segue durante il deployment:
- un tipo di evento di trigger
- un filtro di eventi di trigger per selezionare i documenti associati alla funzione
- il codice della funzione da eseguire
Filtri di eventi di trigger
Quando specifichi un filtro di eventi, puoi specificare una corrispondenza esatta del documento o un pattern del percorso. Utilizza un pattern del percorso per associare più documenti con caratteri jolly *
o **
.
Ad esempio, puoi rispondere alle modifiche apportate al seguente documento:
users/marie
Utilizza i caratteri jolly, *
o **
, per rispondere alle modifiche nei documenti
che corrispondono a un pattern. Il carattere jolly *
corrisponde a un singolo segmento, mentre il carattere jolly a più segmenti **
corrisponde a zero o più segmenti nel pattern.
Per le corrispondenze di un singolo segmento (*
), puoi anche utilizzare un gruppo di acquisizione denominato. Ad esempio, users/{userId}
.
Ad esempio:
Pattern | Descrizione |
---|---|
/users/* o /users/{userId} |
Corrisponde a tutti i documenti nella raccolta /users . Non corrisponde ai documenti in raccolte secondarie come /users/marie/messages/33e2IxYBD9enzS50SJ68 |
/users/** |
Corrisponde a tutti i documenti nella raccolta /users e nei documenti nelle sottoraccolte come /users/marie/messages/33e2IxYBD9enzS50SJ68 |
Per scoprire di più sui pattern di percorso, consulta Pattern di percorso Eventarc.
L'attivatore deve puntare sempre a un documento, anche se utilizzi un carattere jolly.
Ad esempio, users/{userId=*}/{messageCollectionId=*}
non è valido perché {messageCollectionId=*}
è una raccolta. Tuttavia, users/{userId=*}/{messageCollectionId}/{messageId=*}
è
valido perché {messageId=*}
punterà sempre a un documento.
Funzioni di esempio
L'esempio seguente mostra come ricevere eventi Firestore.
Per lavorare con i dati dei documenti coinvolti in un evento, guarda i campi value
e old_value
.
value
: un oggettoDocument
che contiene uno snapshot del documento post-operazione. Questo campo non viene compilato per gli eventi di eliminazione.old_value
: un oggettoDocument
che contiene uno snapshot di documento prima dell'operazione. Questo campo viene compilato solo per gli eventi di aggiornamento ed eliminazione.
Go
Per eseguire l'autenticazione in Firestore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per eseguire l'autenticazione in Firestore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione in Firestore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Usa protobufjs per decodificare i dati degli eventi. Includigoogle.events.cloud.firestore.v1
data.proto
nella sorgente.
Python
Per eseguire l'autenticazione in Firestore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
C#
Per eseguire l'autenticazione in Firestore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
I seguenti esempi convertono in lettere maiuscole le stringhe aggiunte al campo original
di un documento interessato e scrive il nuovo valore nello stesso documento:
Go
Per eseguire l'autenticazione in Firestore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per eseguire l'autenticazione in Firestore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione in Firestore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Usa protobufjs per decodificare i dati degli eventi. Includigoogle.events.cloud.firestore.v1
data.proto
nella sorgente.
Python
Per eseguire l'autenticazione in Firestore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
C#
Per eseguire l'autenticazione in Firestore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Includi le dipendenze proto nell'origine
Devi includere il file Firestore data.proto
nella directory di origine della funzione. Questo file importa i seguenti proto, che devi includere anche nella directory di origine:
Utilizza la stessa struttura di directory per le dipendenze. Ad esempio, posiziona
struct.proto
all'interno di google/protobuf
.
Questi file sono necessari per decodificare i dati sugli eventi. Se l'origine della funzione non include questi file, viene restituito un errore quando viene eseguita.
Attributi evento
Ogni evento include attributi dei dati che includono informazioni sull'evento, come l'ora in cui è stato attivato. Firestore aggiunge ulteriori dati sul database e sul documento interessato. Puoi accedere a questi attributi nel seguente modo:
Java
logger.info("Function triggered by event on: " + event.getSource()); logger.info("Event type: " + event.getType()); logger.info("Event time " + event.getTime()); logger.info("Event project: " + event.getExtension("project")); logger.info("Event location: " + event.getExtension("location")); logger.info("Database name: " + event.getExtension("database")); logger.info("Database document: " + event.getExtension("document")); // For withAuthContext events logger.info("Auth information: " + event.getExtension("authid")); logger.info("Auth information: " + event.getExtension("authtype"));
Node.js
console.log(`Function triggered by event on: ${cloudEvent.source}`); console.log(`Event type: ${cloudEvent.type}`); console.log(`Event time: ${cloudEvent.time}`); console.log(`Event project: ${cloudEvent.project}`); console.log(`Event location: ${cloudEvent.location}`); console.log(`Database name: ${cloudEvent.database}`); console.log(`Document name: ${cloudEvent.document}`); // For withAuthContext events console.log(`Auth information: ${cloudEvent.authid}`); console.log(`Auth information: ${cloudEvent.authtype}`);
Python
print(f"Function triggered by change to: {cloud_event['source']}") print(f"Event type: {cloud_event['type']}") print(f"Event time: {cloud_event['time']}") print(f"Event project: {cloud_event['project']}") print(f"Location: {cloud_event['location']}") print(f"Database name: {cloud_event['database']}") print(f"Document: {cloud_event['document']}") // For withAuthContext events print(f"Auth information: {cloud_event['authid']}") print(f"Auth information: {cloud_event['authtype']}")
Esegui il deployment di una funzione
Gli utenti che eseguono il deployment di Cloud Functions devono avere il ruolo IAM Sviluppatore Cloud Functions o un ruolo che includa le stesse autorizzazioni. Vedi anche Configurazione aggiuntiva per il deployment.
Puoi eseguire il deployment di una funzione utilizzando gcloud CLI o la console Google Cloud. L'esempio seguente illustra il deployment con gcloud CLI. Per maggiori dettagli sul deployment con la console Google Cloud, consulta Eseguire il deployment di Cloud Functions
gcloud
-
Nella console Google Cloud, attiva Cloud Shell.
Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.
Utilizza il comando
gcloud functions deploy
per eseguire il deployment di una funzione:gcloud functions deploy YOUR_FUNCTION_NAME \ --gen2 \ --region=FUNCTION_LOCATION \ --trigger-location=TRIGGER_LOCATION \ --runtime=YOUR_RUNTIME \ --source=YOUR_SOURCE_LOCATION \ --entry-point=YOUR_CODE_ENTRYPOINT \ --trigger-event-filters="type=EVENT_FILTER_TYPE" \ --trigger-event-filters="database=DATABASE" \ --trigger-event-filters-path-pattern="document=DOCUMENT" \
Il primo argomento,
YOUR_FUNCTION_NAME
, è un nome per la funzione di cui hai eseguito il deployment. Il nome della funzione deve iniziare con una lettera seguita da un massimo di 62 lettere, numeri, trattini o trattini bassi e deve terminare con una lettera o un numero.Il flag
--gen2
specifica che vuoi eseguire il deployment in Cloud Functions (2nd gen). Se questo flag viene omesso, viene eseguito il deployment in Cloud Functions (1ª generazione.).Il flag
--region
specifica la regione in cui eseguire il deployment della funzione.Per massimizzare la vicinanza, imposta una regione vicina al tuo database Firestore. Se il tuo database Firestore si trova in una località multiregionale, imposta su
us-central1
per i database innam5
e sueurope-west4
per i database ineur3
. Per le sedi di Firestore regionali, impostale sulla stessa regione.Il flag
--trigger-location
specifica la posizione dell'attivatore. Devi impostare questo flag sulla località del tuo database Firestore.Il flag
--runtime
specifica il runtime del linguaggio utilizzato dalla funzione. Cloud Functions supporta diversi runtime. Per ulteriori informazioni, consulta Runtime.Il flag
--source
specifica la posizione del codice sorgente della funzione. Per i dettagli, vedi quanto segue:Il flag
--entry-point
specifica il punto di ingresso alla funzione nel codice sorgente. Questo è il codice che verrà eseguito all'esecuzione della funzione. Il valore di questo flag deve essere un nome di funzione o un nome di classe completo presente nel codice sorgente. Per ulteriori informazioni, consulta Punto di ingresso della funzione.EVENT_FILTER_TYPE
: Firestore supporta i seguenti tipi di eventi.google.cloud.firestore.document.v1.created
: l'evento viene inviato quando viene scritto un documento per la prima volta.google.cloud.firestore.document.v1.updated
: l'evento viene inviato quando esiste già un documento e viene modificato un valore.google.cloud.firestore.document.v1.deleted
: l'evento viene inviato quando viene eliminato un documento.google.cloud.firestore.document.v1.written
: l'evento viene inviato quando un documento viene creato, aggiornato o eliminato.google.cloud.firestore.document.v1.created.withAuthContext
: l'evento viene inviato quando viene scritto un documento per la prima volta e l'evento include informazioni di autenticazione aggiuntivegoogle.cloud.firestore.document.v1.updated.withAuthContext
: l'evento viene inviato quando esiste già un documento e viene modificato un valore. Include informazioni di autenticazione aggiuntivegoogle.cloud.firestore.document.v1.deleted.withAuthContext
: l'evento viene inviato quando viene eliminato un documento. Include informazioni di autenticazione aggiuntivegoogle.cloud.firestore.document.v1.written.withAuthContext
: l'evento viene inviato quando un documento viene creato, aggiornato o eliminato ed evento. Include informazioni di autenticazione aggiuntive
DATABASE
: il database Firestore. Per il nome del database predefinito, utilizza(default)
.DOCUMENT
: il percorso del database che attiva gli eventi quando i dati vengono creati, aggiornati o eliminati. L'operatore può essere uno dei seguenti:- Uguale, ad esempio,
--trigger-event-filters=document='users/marie'
- Pattern del percorso, ad esempio
--trigger-event-filters-path-pattern=document='users/*'
. Per saperne di più, consulta Comprendere i pattern dei percorsi.
- Uguale, ad esempio,
Facoltativamente, puoi specificare ulteriori opzioni di configurazione, networking e sicurezza quando esegui il deployment di una funzione.
Per un riferimento completo sul comando deployment e sui relativi flag, consulta la documentazione di
gcloud functions deploy
.
Deployment di esempio
I seguenti esempi dimostrano i deployment con Google Cloud CLI.
Esegui il deployment di una funzione per un database nella regione us-west2
:
gcloud functions deploy gcfv2-trigger-firestore-node \
--gen2 \
--region=us-west2 \
--trigger-location=us-west2 \
--runtime=nodejs18 \
--source=gs://CLOUD_STORAGE_BUCKET/firestoreEventFunction.zip \
--entry-point=makeUpperCase \
--trigger-event-filters=type=google.cloud.firestore.document.v1.written \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern=document='messages/{pushId}'
Esegui il deployment di una funzione per un database nella località multiregionale nam5
:
gcloud functions deploy gcfv2-trigger-firestore-python \
--gen2 \
--region=us-central1 \
--trigger-location=nam5 \
--runtime=python311 \
--source=gs://CLOUD_STORAGE_BUCKET/firestoreEventFunction.zip \
--entry-point=make_upper_case \
--trigger-event-filters=type=google.cloud.firestore.document.v1.written.withAuthContext \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern=document='messages/{pushId}'
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.
Località Eventarc e Firestore
Eventarc non supporta più regioni per gli attivatori di eventi Firestore, ma puoi comunque creare trigger per i database Firestore in località multiregionali. Eventarc mappa le località a più regioni di Firestore nelle seguenti regioni Eventarc:
Firestore (più regioni) | Regione Eventarc |
---|---|
nam5 |
us-central1 |
eur3 |
europe-west4 |
Differenze tra Cloud Functions (2ª generazione. e 1ª generazione)
Cloud Functions (2nd gen) utilizza gli eventi Eventarc per tutti i runtime. In precedenza, Cloud Functions (1ª generazione.) utilizzava gli eventi Eventarc solo per alcuni runtime. Gli eventi Eventarc introducono le seguenti differenze rispetto a Cloud Functions (1ª generazione).
I trigger Firestore per Eventarc supportano destinazioni aggiuntive oltre a Cloud Functions. Puoi instradare
CloudEvents
a una serie di destinazioni inclusi, a titolo esemplificativo, Cloud Run, GKE e Workflows.I trigger di Firestore per Eventarc recuperano la definizione dell'attivatore all'inizio di un'operazione di scrittura del database e utilizzano questa definizione per decidere se Firestore deve emettere un evento. L'operazione di scrittura non prende in considerazione le eventuali modifiche alla definizione dell'attivatore che potrebbero verificarsi durante l'esecuzione.
Cloud Functions (1ª generazione.) recupera la definizione del trigger durante la valutazione della scrittura del database e le modifiche al trigger durante la valutazione possono influire sull'emissione o meno di un evento da parte di Firestore.
Per maggiori dettagli, consulta il confronto delle versioni di Cloud Functions.