Estendi con le funzioni di Cloud Run (2ª generazione)
Con le funzioni Cloud Run, puoi eseguire il deployment del codice per gestire gli eventi attivati da modifiche nel database Firestore. Ciò ti consente di aggiungere funzionalità lato server senza utilizzare i tuoi server.
Estendi Firestore con le funzioni di Cloud Run (2ª generazione)
Le funzioni Cloud Run (2ª generazione) supportano il seguente evento Firestore che ti consentono 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 |
Viene attivato quando esiste già un documento e un valore è stato modificato. |
google.cloud.firestore.document.v1.deleted |
Si attiva quando un documento viene eliminato. |
google.cloud.firestore.document.v1.written |
Si attiva quando vengono attivati created , updated o deleted . |
google.cloud.firestore.document.v1.created.withAuthContext |
Uguale a created , ma con l'aggiunta delle informazioni di autenticazione. |
google.cloud.firestore.document.v1.updated.withAuthContext |
Come updated , ma aggiunge le informazioni di autenticazione. |
google.cloud.firestore.document.v1.deleted.withAuthContext |
Uguale a deleted , ma con l'aggiunta delle informazioni di autenticazione. |
google.cloud.firestore.document.v1.written.withAuthContext |
Uguale a written , ma con l'aggiunta delle informazioni di autenticazione. |
Solo trigger di eventi Firestore sulle modifiche ai documenti. Un aggiornamento a un documento Firestore in cui i dati non è modificato (una scrittura autonoma) non genera un evento di aggiornamento o scrittura. È impossibile aggiungere eventi a campi specifici.
Includi il contesto di autenticazione nell'evento
Per includere ulteriori informazioni di autenticazione sull'evento, utilizza un attivatore
dell'evento con l'estensione withAuthContext
. Questa estensione aggiunge altre
e informazioni sull'entità che ha attivato l'evento. Aggiunge
Attributi authtype
e authid
oltre alle informazioni restituite in
l'evento di base. Consulta le
authcontext
Riferimento 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 trigger
- un filtro di eventi di trigger per selezionare i documenti associati alla funzione
- il codice della funzione da eseguire
Filtri degli eventi di trigger
Quando specifichi un filtro eventi, puoi indicare un documento esatto
una corrispondenza o un pattern del percorso. Utilizza un pattern del percorso per associare più documenti a
caratteri jolly, *
o **
.
Ad esempio, puoi rispondere alle modifiche al seguente documento:
users/marie
Utilizza i caratteri jolly, *
o **
, per rispondere alle modifiche nei documenti
che corrispondono a uno schema. Un carattere jolly *
corrisponde a un singolo segmento e
un carattere jolly a più segmenti **
corrisponde a zero o più segmenti nel pattern.
Per le corrispondenze di singoli segmenti (*
), 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 ai documenti in sottoraccolte come /users/marie/messages/33e2IxYBD9enzS50SJ68 |
Per scoprire di più sui pattern di percorso, consulta Pattern di percorso Eventarc.
L'attivatore deve sempre puntare a un documento, anche se usi un carattere jolly.
Ad esempio, users/{userId=*}/{messageCollectionId=*}
non è valido perché {messageCollectionId=*}
è una raccolta. Tuttavia, users/{userId=*}/{messageCollectionId}/{messageId=*}
è
valida perché {messageId=*}
rimanderà 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, consulta i value
e
old_value
campi.
value
: un oggettoDocument
contenente un'istantanea documento post-operazione. Questo campo non viene compilato per gli eventi di eliminazione.old_value
: un oggettoDocument
che contiene un documento di pre-operazione senza dover creare uno snapshot. Questo campo viene compilato solo per gli eventi di aggiornamento ed eliminazione.
Go
Per eseguire l'autenticazione su Firestore, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per eseguire l'autenticazione su Firestore, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione su Firestore, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Utilizza protobufjs per decodificare i dati sugli eventi. Includi l'elementogoogle.events.cloud.firestore.v1
data.proto
nella fonte.
Python
Per eseguire l'autenticazione su Firestore, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
C#
Per eseguire l'autenticazione su Firestore, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Gli esempi seguenti convertono le stringhe aggiunte al campo original
di un
documento interessato in maiuscolo e scrive il nuovo valore nello stesso documento:
Go
Per eseguire l'autenticazione su Firestore, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Java
Per eseguire l'autenticazione su Firestore, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione su Firestore, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Utilizza protobufjs per decodificare i dati sugli eventi. Includi l'elementogoogle.events.cloud.firestore.v1
data.proto
nella fonte.
Python
Per autenticarti a Firestore, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
C#
Per eseguire l'autenticazione su Firestore, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Includi le dipendenze proto nell'origine
Devi includere Firestore data.proto
nella directory di origine per la tua funzione. Questo file importa i seguenti dati
che devi includere anche nella directory di origine:
Usa la stessa struttura di directory per le dipendenze. Ad esempio, posiziona
struct.proto
in google/protobuf
.
Questi file sono necessari per decodificare i dati sugli eventi. Se l'origine della funzione non non include questi file, restituisce un errore durante l'esecuzione.
Attributi evento
Ogni evento include attributi dei dati che includono informazioni sull'evento, come l'ora in cui l'evento è stato attivato. Firestore aggiunge ulteriori dati sul database e sul documento coinvolti nell'evento. 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 delle funzioni Cloud Run devono avere Sviluppatore funzioni Cloud Run un ruolo IAM o un ruolo che include le stesse autorizzazioni. Vedi anche Configurazione aggiuntiva per il deployment.
Puoi eseguire il deployment di una funzione utilizzando la riga di comando gcloud o la console Google Cloud. L'esempio seguente mostra il deployment con con gcloud CLI. Per maggiori dettagli sul deployment con la console Google Cloud, consulta Eseguire il deployment delle funzioni di Cloud Run
gcloud
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Utilizza la
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 della funzione di cui hai eseguito il deployment. Il nome della funzione deve iniziare con una lettera seguito 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 su funzioni Cloud Run (2ª generazione). Omissione questo flag porta al deployment in Cloud Run Functions (1ª generazione.).Il flag
--region
specifica la regione in cui eseguire il deployment della funzione.Per massimizzare la prossimità, imposta una regione vicina a Firestore per configurare un database. Se il database Firestore si trova in una località multiregionale località, impostata su
us-central1
per i database innam5
e sueurope-west4
per i database ineur3
. Per regioni Località Firestore, impostate sulla stessa regione.La
--trigger-location
specifica la posizione del trigger. Devi impostare questo flag su del tuo database Firestore.Il flag
--runtime
specifica il runtime del linguaggio utilizzato dalla funzione. Funzioni di Cloud Run supporta diversi runtime, vedi Runtime per ulteriori informazioni.Il flag
--source
specifica la posizione del codice sorgente della funzione. Consulta quanto segue: per maggiori dettagli:La
--entry-point
specifica il punto di ingresso della funzione nel codice sorgente. Questo è il codice che verrà eseguito quando la funzione viene eseguita. Il valore di questo deve essere un nome di funzione o un nome di classe completo esistente del codice sorgente. Consulta Punto di ingresso alla funzione per ulteriori informazioni.EVENT_FILTER_TYPE
: Firestore supporta i seguenti tipi di eventi.google.cloud.firestore.document.v1.created
: l'evento viene inviato quando del documento per la prima volta.google.cloud.firestore.document.v1.updated
: l'evento viene inviato quando documento già esistente e con qualsiasi valore modificato.google.cloud.firestore.document.v1.deleted
: l'evento viene inviato quando documento eliminato.google.cloud.firestore.document.v1.written
: l'evento viene inviato quando quando un documento viene creato, aggiornato o eliminato.google.cloud.firestore.document.v1.created.withAuthContext
: l'evento viene inviato quando documento è scritto per la prima volta e l'evento include ulteriori informazioni di autenticazione.google.cloud.firestore.document.v1.updated.withAuthContext
: l'evento viene inviato quando documento già esistente e con qualsiasi valore modificato. Include informazioni di autenticazione aggiuntivegoogle.cloud.firestore.document.v1.deleted.withAuthContext
: l'evento viene inviato quando documento eliminato. Include informazioni di autenticazione aggiuntivegoogle.cloud.firestore.document.v1.written.withAuthContext
: l'evento viene inviato quando viene creato, aggiornato o eliminato ed evento. Include informazioni di autenticazione aggiuntive
DATABASE
: il database Firestore. Per il nome predefinito del database, utilizza(default)
.DOCUMENT
: il percorso del database attiva eventi quando i dati vengono creati, aggiornati 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 configurazione, networking e le opzioni di sicurezza quando esegui il deployment di una funzione.
Per un riferimento completo al comando di deployment e ai 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 le funzioni di Cloud Run:
- Le funzioni Cloud Run (1ª generazione.) preparano un prerequisito "(predefinito)" esistente in modalità nativa Firestore. Non supportare i database denominati Firestore o la modalità Datastore. Utilizza le funzioni di Cloud Run (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. Evita di fare affidamento su meccanismi di esecuzione esattamente una volta e scrivi funzioni idempotenti.
- Firestore in modalità Datastore richiede le funzioni Cloud Run (2ª generazione.). Le funzioni Cloud Run (1ª gen.) non supportano 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. L'attivatore interrompe l'invio di eventi, ma continua a esistere finché non lo elimini.
- Se un evento corrispondente supera le dimensioni massime della richiesta, il valore
potrebbe non essere consegnato a Cloud Run 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 Run Functions (2ª generazione.)
- Riduci le dimensioni del documento
- Elimina le funzioni Cloud Run in questione
- Puoi disattivare il logging utilizzando le esclusioni ma tieni presente che gli eventi offensivi non verranno comunque pubblicati.
Località Eventarc e Firestore
Eventarc non supporta più regioni per l'evento Firestore ma puoi comunque creare trigger per i database Firestore in località multiregionali. Eventarc mappa Firestore località multiregionali alle seguenti regioni Eventarc:
Firestore (più regioni) | Regione Eventarc |
---|---|
nam5 |
us-central1 |
eur3 |
europe-west4 |
Differenze tra le funzioni Cloud Run (2ª generazione. e 1ª generazione.)
Le funzioni Cloud Run (2ª generazione) utilizzano gli eventi Eventarc per tutti i runtime. In precedenza, le funzioni Cloud Run (1ª generazione.) utilizzavano gli eventi Eventarc per solo alcuni runtime. Gli eventi Eventarc presentano le seguenti differenze rispetto alle funzioni Cloud Run (1ª gen.).
I trigger Firestore per il supporto Eventarc oltre alle funzioni di Cloud Run. Puoi indirizzare
CloudEvents
verso una serie di destinazioni, tra cui a titolo esemplificativo, Cloud Run, GKE Workflows.I trigger di Firestore per Eventarc recuperano la definizione del trigger all'inizio di un'operazione di scrittura del database e utilizza quella definizione per decidere se Firestore deve emettere un evento. La l'operazione di scrittura non prende in considerazione le modifiche apportate all'attivatore della definizione che potrebbe verificarsi durante l'esecuzione.
Le funzioni Cloud Run (1ª gen.) recuperano la definizione dell'attivatore durante la valutazione della scrittura del database e le modifiche all'attivatore durante la valutazione possono influire sull'emissione o meno di un evento da parte di Firestore.
Per maggiori dettagli, consulta Confronto delle versioni di Cloud Run Functions.