Estendere Datastore con Cloud Functions (2nd gen)

Con le funzioni Cloud Run ed Eventarc, puoi eseguire il deployment del codice per gestire gli eventi attivati dalle modifiche nel database Firestore in modalità Datastore. In questo modo, puoi aggiungere funzionalità lato server senza dover eseguire i tuoi server.

Trigger in modalità Datastore

Eventarc supporta i seguenti attivatori di eventi Firestore in modalità Datastore per consentirti di creare gestori di funzioni Cloud Run (2ª generazione.) associati agli eventi Firestore in modalità Datastore:

Tipo di evento	Trigger
google.cloud.datastore.entity.v1.created	Si attiva quando un'entità viene scritta per la prima volta.
google.cloud.datastore.entity.v1.updated	Viene attivato quando esiste già un'entità e viene modificato un valore.
google.cloud.datastore.entity.v1.deleted	Si attiva quando un'entità viene eliminata.
google.cloud.datastore.entity.v1.written	Si attiva quando viene attivato created, updated o deleted.
google.cloud.datastore.entity.v1.created.withAuthContext	Come created, ma aggiunge le informazioni di autenticazione.
google.cloud.datastore.entity.v1.updated.withAuthContext	Come updated, ma aggiunge le informazioni di autenticazione.
google.cloud.datastore.entity.v1.deleted.withAuthContext	Come deleted, ma aggiunge le informazioni di autenticazione.
google.cloud.datastore.entity.v1.written.withAuthContext	Come written, ma aggiunge le informazioni di autenticazione.

Gli attivatori di eventi in modalità Datastore rispondono solo alle modifiche delle entità. Un aggiornamento a un'entità in modalità Datastore in cui i dati rimangono invariati (una scrittura senza operazioni) non genera un evento di aggiornamento o scrittura. Non puoi generare eventi solo per proprietà specifiche.

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 ulteriori informazioni sull'entità che ha attivato l'evento. Aggiunge gli attributi authtype e authid oltre alle informazioni restituite nell'evento di base. Per ulteriori informazioni sui valori degli attributi, consulta la documentazione di riferimento di authcontext.

Scrivere una funzione attivata da entità

Per scrivere una funzione che risponda agli eventi di Firestore in modalità Datastore, preparati a specificare quanto segue durante il deployment:

• un tipo di evento di trigger
• un filtro evento di trigger per selezionare le entità associate alla funzione
• il codice della funzione da eseguire

Filtri evento trigger

Quando specifichi un filtro evento, puoi specificare una corrispondenza esatta dell'entità o un pattern di percorso. Utilizza un pattern di percorso per trovare corrispondenze con più entità con i caratteri jolly * o **.

Ad esempio, puoi specificare una corrispondenza esatta dell'entità per rispondere alle modifiche alla seguente entità:

users/marie

Utilizza i caratteri jolly * o ** per rispondere alle modifiche delle entità che corrispondono a un pattern. Il carattere jolly * corrisponde a un singolo segmento, mentre il carattere jolly multisegmento ** corrisponde a zero o più segmenti nel pattern.

Per le corrispondenze di singoli segmenti (*), puoi anche utilizzare un gruppo di cattura denominato, ad esempio users/{userId}.

La tabella seguente mostra i pattern di percorso validi:

Pattern	Descrizione
users/* o users/{userId}	Corrisponde a tutte le entità di tipo users. Non corrisponde al livello delle entità discendenti come /users/marie/messages/33e2IxYBD9enzS50SJ68
users/**	Corrisponde a tutte le entità di tipo users e a tutte le entità discendenti come /users/marie/messages/33e2IxYBD9enzS50SJ68

Per saperne di più sui pattern di percorso, consulta Pattern di percorso Eventarc.

L'attivatore deve sempre puntare a un'entità, anche se utilizzi un'espressione generica. Vedi i seguenti esempi:

• users/{userId=*}/{messages=*} non è valido perché {messages=*} è un ID tipo.

• users/{userId=*}/{messages}/{messageId=*} è valido perché {messageId=*} fa sempre riferimento a un'entità.

Escape dei caratteri

La sezione descrive le situazioni in cui è necessario utilizzare l'interpretazione letterale dei caratteri negli ID tipo e negli ID entità. L'inserimento di un carattere di escape consente al filtro dell'evento di interpretare correttamente l'ID.

• Se un ID tipo o un ID entità include un carattere ~ o /, devi eseguire la codifica dell'ID nel filtro evento. Per eseguire l'escape di un ID, utilizza il formato__escENCODED_ID__. Sostituisci ENCODED_ID con un ID tipo o un ID entità in cui tutti i caratteri ~ e / sono sostituiti dai relativi ID codifica, che sono i seguenti:

  • ~: ~0
  • /: ~1

  Ad esempio, l'ID tipo user/profile diventa __escusers~1profile__. Un Esempio di pattern del percorso con questo ID tipo è __escusers~1profile__/{userId}

• Se utilizzi l'ID tipo o l'ID entità di . o .. nel filtro evento, devi eseguire la fuga dell'ID come segue:

  • .: __esc~2__
  • ..: __esc~2~2__

  Devi inserire il carattere di escape per . solo se l'ID è esattamente . o ... Ad esempio, l'ID tipo customers.info non richiede caratteri di escape.

• Se il tipo o l'ID entità è un valore numerico anziché una stringa, devi eseguire l'escapismo dell'ID con __idNUMERIC_VALUE__. Ad esempio, il pattern del percorso per un'entità di tipo 111 e con ID entità 222 è __id111__/__id222__.

• Se hai eseguito la migrazione da Cloud Datastore precedente a Firestore in modalità Datastore, il tuo database potrebbe contenere ID precedenti in una codifica non UTF-8. Devi utilizzare l'interpretazione letterale di questi ID con __bytesBASE64_ENCODING__. Sostituisci BASE64_ENCODING con la codifica base-64 dell'ID. Ad esempio, il pattern del percorso Task/{task} con sfuggita per l'ID tipo non UTF-8Task diventa __bytesVGFzaw==__/{task}.

Funzioni di esempio

L'esempio seguente mostra come ricevere gli eventi della modalità Datastore. Per lavorare con i dati coinvolti in un evento, esamina i campi value e old_value.

• value: un oggetto EntityResult che contiene un'istantanea dell'entità post-operazione. Questo campo non viene compilato per gli eventi di eliminazione.
• old_value: un oggetto EntityResult che contiene uno snapshot dell'entità pre-operazione. Questo campo viene compilato solo per gli eventi di aggiornamento ed eliminazione.

Java

Per scoprire come installare e utilizzare la libreria client per la modalità Datastore, consulta Librerie client per la modalità Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java in modalità Datastore.

Per autenticarti alla modalità Datastore, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

import com.google.cloud.functions.CloudEventsFunction;
import com.google.events.cloud.datastore.v1.EntityEventData;
import com.google.protobuf.InvalidProtocolBufferException;
import io.cloudevents.CloudEvent;
import java.util.logging.Logger;

public class Datastore implements CloudEventsFunction {
  private static final Logger logger = Logger.getLogger(Datastore.class.getName());

  @Override
  public void accept(CloudEvent event) throws InvalidProtocolBufferException {
    EntityEventData datastoreEventData = EntityEventData.parseFrom(event.getData().toBytes());

    logger.info("Function triggered by event on: " + event.getSource());
    logger.info("Event type: " + event.getType());

    logger.info("Old value:");
    logger.info(datastoreEventData.getOldValue().toString());

    logger.info("New value:");
    logger.info(datastoreEventData.getValue().toString());
  }
}

Includi le dipendenze proto nel codice sorgente

Devi includere il file Modalità Datastore data.proto nella directory di origine della funzione. Questo file importa i seguenti proto che devi includere anche nella directory di origine:

• google/protobuf/struct.proto
• google/protobuf/timestamp.proto
• google/type/latlng.proto

Utilizza la stessa struttura di directory per le dipendenze. Ad esempio, inserisci struct.proto in google/protobuf.

Questi file sono necessari per decodificare i dati sugli eventi. Se l'origine della funzione non include questi file, restituisce un errore durante l'esecuzione.

Attributi evento

Ogni evento include attributi dati che includono informazioni sull'evento, ad esempio l'ora in cui è stato attivato. Firestore in modalità Datastore aggiunge dati aggiuntivi sul database e sull'entità coinvolti nell'evento. Puoi accedere a questi attributi come segue:

Java

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 namespace: " + event.getExtension("namespace"));
logger.info("Database entity: " + event.getExtension("entity"));
// For withAuthContext events
logger.info("Auth information: " + event.getExtension("authid"));
logger.info("Auth information: " + event.getExtension("authtype"));

Esegui il deployment di una funzione

Gli utenti che eseguono il deployment delle funzioni Cloud Run devono disporre del ruolo IAM Sviluppatore di funzioni Cloud Run o di un ruolo che includa le stesse autorizzazioni. Consulta anche Configurazione aggiuntiva per il deployment.

Puoi eseguire il deployment di una funzione utilizzando la gcloud CLI o la console Google Cloud. L'esempio seguente mostra il deployment con gcloud CLI. Per informazioni dettagliate sul deployment con la console Google Cloud, consulta Eseguire il deployment di funzioni Cloud Run.

1. In the Google Cloud console, activate Cloud Shell.

   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.

2. Utilizza il comando gcloud functions deploy per eseguire il deployment di una funzione:

   gcloud functions deploy FUNCTION_NAME \
   --gen2 \
   --region=FUNCTION_LOCATION \
   --trigger-location=TRIGGER_LOCATION \
   --runtime=RUNTIME \
   --source=SOURCE_LOCATION \
   --entry-point=CODE_ENTRYPOINT \
   --trigger-event-filters="type=EVENT_FILTER_TYPE" \
   --trigger-event-filters="database=DATABASE" \
   --trigger-event-filters="namespace=NAMESPACE" \
   --trigger-event-filters-path-pattern="entity=ENTITY_OR_PATH" \
   

   Il primo argomento, FUNCTION_NAME, è un nome per la funzione di cui è stato eseguito il deployment. Il nome della funzione deve iniziare con una lettera followed da un massimo di 62 lettere, numeri, trattini o trattini bassi e deve terminare con una lettera o un numero. Sostituisci FUNCTION_NAME con un nome funzione valido. Aggiungi poi i seguenti flag:

   • Il flag --gen2 specifica che vuoi eseguire il deployment in Cloud Run Functions (2ª generazione.). Se ometti questo flag, il deployment viene eseguito nelle funzioni Cloud Run (1ª generazione.).

   • Il flag --region=FUNCTION_LOCATION specifica la regione in cui eseguire il deployment della funzione.

     Per massimizzare la prossimità, imposta FUNCTION_LOCATION su una regione vicino al tuo database Firestore. Se il database Firestore si trova in una località multiregionale, imposta il valore su us-central1 per i database in nam5 e su europe-west4 per i database in eur3. Per le località Firestore regionali, imposta la stessa regione.

   • Il flag --trigger-location=TRIGGER_LOCATION specifica la posizione dell'attivatore. Devi impostare TRIGGER_LOCATION sulla posizione del database in modalità Datastore.

   • Il flag --runtime=RUNTIME specifica il runtime della lingua utilizzato dalla funzione. Cloud Run Functions supporta diversi runtime. Per ulteriori informazioni, consulta la sezione Ambienti di runtime. Imposta RUNTIME su un runtime supportato.

   • Il flag --source=SOURCE_LOCATION specifica la posizione del codice sorgente della funzione. Per maggiori dettagli, consulta quanto segue:

     • Esegui il deployment dalla tua macchina locale
     • Esegui il deployment da Cloud Storage
     • Esegui il deployment da un repository codice sorgente

     Imposta SOURCE_LOCATION sulla posizione del codice sorgente della funzione.

   • Il flag --entry-point=CODE_ENTRYPOINT specifica il punto di ingresso della funzione nel codice sorgente. Questo è il codice eseguito dalla funzione durante l'esecuzione. Devi impostare CODE_ENTRYPOINT su un nome di funzione o un nome di classe completo che esiste nel codice sorgente. Per ulteriori informazioni, consulta Entry point della funzione.

   • I flag --trigger-event-filters definiscono il filtro degli eventi che include il tipo di attivatore e l'entità o il percorso che attiva gli eventi. Imposta i seguenti valori degli attributi per definire il filtro evento:

     • type=EVENT_FILTER_TYPE: Firestore supporta i seguenti tipi di eventi:

       • google.cloud.datastore.entity.v1.created: viene inviato quando un'entità viene scritta per la prima volta.
       • google.cloud.datastore.entity.v1.updated: l'evento viene inviato quando un'entità esistente viene modificata.
       • google.cloud.datastore.entity.v1.deleted: viene inviato quando viene eliminata un'entità.
       • google.cloud.datastore.entity.v1.written: l'evento viene inviato quando un'entità viene creata, aggiornata o eliminata.
       • L'evento google.cloud.datastore.entity.v1.created.withAuthContext viene inviato quando viene scritto un documento per la prima volta e include informazioni di autenticazione aggiuntive
       • L'evento google.cloud.datastore.entity.v1.updated.withAuthContext viene inviato quando esiste già un documento e un valore è stato modificato. Include informazioni di autenticazione aggiuntive
       • L'evento google.cloud.datastore.entity.v1.deleted.withAuthContext viene inviato quando un documento viene eliminato. Include informazioni di autenticazione aggiuntive
       • L'evento google.cloud.datastore.entity.v1.written.withAuthContext viene inviato quando viene creato, aggiornato o eliminato un documento. Include informazioni di autenticazione aggiuntive

       Imposta EVENT_FILTER_TYPE su uno di questi tipi di eventi.

     • database=DATABASE: il database Firestore. Per il nome del database predefinito, imposta DATABASE su (default).

     • namespace=NAMESPACE: lo spazio dei nomi del database. Per il nome del database predefinito, imposta NAMESPACE su (default). Rimuovi il flag per fare corrispondere qualsiasi spazio dei nomi.

       Nota: imposta esattamente su (default) per lo spazio dei nomi predefinito. Si tratta di un nome della risorsa non canonico utilizzato solo per Eventarc. Non impostare il valore su [default] come mostrato nella console Google Cloud.

     • entity=ENTITY_OR_PATH: il percorso del database che attiva gli eventi quando i dati vengono creati, aggiornati o eliminati. I valori accettati per ENTITY_OR_PATH sono:

       • Uguale; ad esempio, --trigger-event-filters="entity='users/marie'"
       • Pattern del percorso; ad esempio, --trigger-event-filters-path-pattern="entity='users/*'". Per ulteriori informazioni, consulta Informazioni sui pattern di percorso.

     Facoltativamente, puoi specificare opzioni aggiuntive di configurazione, networking e 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.

Esempi di implementazioni

I seguenti esempi mostrano i deployment con Google Cloud CLI.

Esegui il deployment di una funzione per un database nella regione us-west2:

gcloud functions deploy gcfv2-trigger-datastore-node \
--gen2 \
--region=us-west2 \
--trigger-location=us-west2 \
--runtime=nodejs18 \
--source=gs://example_bucket-1/datastoreEventFunction.zip \
--entry-point=makeUpperCase \
--trigger-event-filters=type=google.cloud.datastore.entity.v1.written \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern="entity='messages/{pushId}'"

Esegui il deployment di una funzione per un database nella regione multipla nam5:

gcloud functions deploy gcfv2-trigger-datastore-python \
--gen2 \
--region=us-central1 \
--trigger-location=nam5 \
--runtime=python311 \
--source=gs://example_bucket-1/datastoreEventFunction.zip \
--entry-point=make_upper_case \
--trigger-event-filters=type=google.cloud.datastore.entity.v1.written.withAuthContext \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern="entity='messages/{pushId}'"

Limitazioni

Tieni presenti le seguenti limitazioni per gli trigger Firestore per le funzioni Cloud Run:

• Le funzioni Cloud Run (1ª generazione.) richiedono un database "(default)" esistente in modalità nativa di Firestore. Non supporta i database Firestore con nome o la modalità Datastore. Utilizza le funzioni Cloud Run (2ª generazione.) per configurare gli eventi in questi casi.
• L'ordine non è garantito. Le variazioni 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 su meccanismi di esecuzione esattamente una volta e scrivi funzioni idempotenti.
• Firestore in modalità Datastore richiede Cloud Run Functions (2ª generazione.). Le funzioni Cloud Run (1ª generazione.) non supportano la modalità Datastore.
• Un trigger è associato a un singolo database. Non puoi creare un attivatore che corrisponda a più database.
• L'eliminazione di un database non comporta l'eliminazione automatica degli attivatori per quel database. L'attivatore interrompe l'invio di 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 inviato alle funzioni Cloud Run (1ª generazione.).
  • Gli eventi non inviati a causa delle dimensioni della richiesta vengono registrati nei log della piattaforma e conteggiati ai fini dell'utilizzo dei log per il progetto.
  • Puoi trovare questi log in Esplora log con il messaggio "Impossibile inviare l'evento alla funzione Cloud perché le dimensioni superano il limite per 1ª generazione." di gravità error. Puoi trovare il nome della funzione nel campo functionName. Se il campo receiveTimestamp è ancora entro un'ora da adesso, puoi dedurre i contenuti effettivi dell'evento leggendo il documento in questione con uno snapshot prima e dopo il timestamp.
  • Per evitare questa cadenza, 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 stesso utilizzando le esclusioni, ma tieni presente che gli eventi in violazione non verranno comunque inviati.

Località di Eventarc e Firestore in modalità Datastore

Eventarc non supporta le regioni multiple per gli attivatori di eventi Firestore, ma puoi comunque creare attivatori per i database Firestore in località multiregionali. Eventarc mappa le località Firestore in più regioni alle seguenti regioni Eventarc:

Firestore (più regioni)	Regione Eventarc
nam5	us-central1
eur3	europe-west4

Passaggi successivi

• Scopri di più sulle architetture basate su eventi.
• Consulta gli esempi di codice per la modalità Datastore.