Scrivere funzioni basate su eventi
In Cloud Functions, puoi utilizzare le funzioni basate su eventi quando vuoi che una funzione venga richiamata automaticamente in risposta a un evento che si verifica nel tuo ambiente cloud.
Esistono due modi per implementare le funzioni basate su eventi. La modalità di utilizzo dipende dal runtime del linguaggio scelto e dal fatto che utilizzi Cloud Functions (1ª generazione) o Cloud Functions (2nd gen):
- In Cloud Functions (2nd gen), per tutti i runtime, utilizza le funzioni CloudEvent.
- In Cloud Functions (1ª generazione):
- Per i runtime Node.js, Python, Go e Java, utilizza le funzioni in background.
- Per i runtime .NET, Ruby e PHP, utilizza le funzioni CloudEvent.
Funzioni CloudEvent
Le funzioni CloudEvent si basano su CloudEvents, una specifica standard di settore per descrivere i dati sugli eventi in modo comune. Puoi scoprire di più sulla specifica CloudEvents nel repository GitHub di CloudEvents. Il progetto CloudEvents fornisce inoltre un set di SDK CloudEvents per aiutarti a lavorare con gli oggetti CloudEvents nel tuo codice.
L'esempio seguente mostra un file di origine della funzione CloudEvent di base per ogni runtime. Consulta Struttura della directory di origine per informazioni su dove trovare il codice sorgente.
Node.js
const functions = require('@google-cloud/functions-framework');
// Register a CloudEvent function with the Functions Framework
functions.cloudEvent('myCloudEventFunction', cloudEvent => {
// Your code here
// Access the CloudEvent data payload via cloudEvent.data
});
In Node.js, registri una funzione gestore CloudEvent con il framework delle funzioni per Node.js.
La funzione gestore deve accettare un oggetto CloudEvent
come argomento.
Il punto di ingresso della funzione è il nome con cui il gestore è registrato nel framework di Functions.
In questo esempio, il punto di ingresso è myCloudEventFunction
.
Python
import functions_framework
# Register a CloudEvent function with the Functions Framework
@functions_framework.cloud_event
def my_cloudevent_function(cloud_event):
# Your code here
# Access the CloudEvent data payload via cloud_event.data
In Python, registri una funzione gestore CloudEvent con il framework delle funzioni per Python.
La funzione gestore deve accettare un oggetto CloudEvent
come argomento.
Il punto di ingresso della funzione è il nome della funzione gestore registrata con il framework di Functions.
In questo esempio, il punto di ingresso è my_cloudevent_function
.
Go
package mycloudeventfunction
import (
"context"
"github.com/GoogleCloudPlatform/functions-framework-go/functions"
"github.com/cloudevents/sdk-go/v2/event"
)
func init() {
// Register a CloudEvent function with the Functions Framework
functions.CloudEvent("MyCloudEventFunction", myCloudEventFunction)
}
// Function myCloudEventFunction accepts and handles a CloudEvent object
func myCloudEventFunction(ctx context.Context, e event.Event) error {
// Your code here
// Access the CloudEvent data payload via e.Data() or e.DataAs(...)
// Return nil if no error occurred
return nil
}
In Go, registri una funzione gestore CloudEvent con il framework delle funzioni per Go. La funzione gestore deve accettare un oggetto CloudEvents event.Event
come argomento.
Il punto di ingresso della funzione è il nome con cui il gestore è registrato nel framework di Functions.
In questo esempio, il punto di ingresso è MyCloudEventFunction
.
Java
package mycloudeventfunction;
import com.google.cloud.functions.CloudEventsFunction;
import io.cloudevents.CloudEvent;
// Define a class that implements the CloudEventsFunction interface
public class MyCloudEventFunction implements CloudEventsFunction {
// Implement the accept() method to handle CloudEvents
@Override
public void accept(CloudEvent event) {
// Your code here
// Access the CloudEvent data payload via event.getData()
// To get the data payload as a JSON string, use:
// new String(event.getData().toBytes())
}
}
In Java, utilizzerai
l'API Java del framework delle funzioni
per implementare una classe del gestore CloudEvent con l'interfaccia
CloudEventsFunction
. Il metodo accept()
deve accettare un oggetto
CloudEvent
come argomento ed eseguire qualsiasi elaborazione dell'evento.
Il punto di ingresso della funzione è il nome completo della classe del gestore CloudEvent, incluso il nome del pacchetto. In questo esempio, il punto di ingresso è mycloudeventfunction.MyCloudEventFunction
.
C#
using CloudNative.CloudEvents; using Google.Cloud.Functions.Framework; using System.Threading; using System.Threading.Tasks; namespace MyProject { // Define a class that implements the ICloudEventFunction<T> interface public class MyCloudEventFunction : ICloudEventFunction<CloudEventDataType> { // Implement the HandleAsync() method to handle CloudEvents public Task HandleAsync(CloudEvent cloudEvent, CloudEventDataType data, CancellationToken cancellationToken) { // Your code here // The data argument represents the CloudEvent data payload // Signal function completion return Task.CompletedTask; } } }
Nei runtime .NET, utilizzerai il framework delle funzioni per .NET per implementare una classe del gestore CloudEvent con l'interfaccia ICloudEventFunction<T>
. Il metodo HandleAsync()
accetta un oggetto
CloudEvent
e il payload di dati CloudEvent associato come argomenti.
Il tipo di argomento del payload dei dati CloudEvent, mostrato nell'esempio precedente come CloudEventDataType
, deve corrispondere al tipo di evento che gestisce la funzione. La libreria .NET di Google CloudEvents fornisce tipi di dati per i vari eventi supportati da Google.
Il punto di ingresso della funzione è il nome completo della classe del gestore CloudEvent, incluso lo spazio dei nomi. In questo esempio, il punto di ingresso è MyProject.MyCloudEventFunction
.
Ruby
require "functions_framework"
# Register a CloudEvent function with the Functions Framework
FunctionsFramework.cloud_event "my_cloudevent_function" do |cloud_event|
# Your code here
# Access the CloudEvent data payload via cloud_event.data
end
In Ruby, registri una funzione gestore CloudEvent con il framework delle funzioni per Ruby.
La funzione gestore deve accettare un oggetto CloudEvents Event
come argomento.
Il punto di ingresso della funzione è il nome con cui il gestore è registrato nel framework di Functions.
In questo esempio, il punto di ingresso è my_cloudevent_function
.
PHP
<?php
use CloudEvents\V1\CloudEventInterface;
use Google\CloudFunctions\FunctionsFramework;
// Register a CloudEvent function with the Functions Framework
FunctionsFramework::cloudEvent('myCloudEventFunction', 'myCloudEventHandler');
// Define your CloudEvent handler
function myCloudEventHandler(CloudEventInterface $event): void
{
// Your code here
// Access the CloudEvent data payload via $event->getData()
}
In PHP, registri una funzione gestore CloudEvent con il framework delle funzioni per PHP.
La funzione gestore deve accettare un argomento conforme all'interfaccia CloudEventInterface
.
Il punto di ingresso della funzione è il nome con cui il gestore è registrato nel framework di Functions.
In questo esempio, il punto di ingresso è myCloudEventFunction
.
Per le funzioni CloudEvent, i dati degli eventi vengono passati alla funzione nel formato CloudEvents, con un payload dei dati CloudEvent corrispondente al tipo di evento che attiva la funzione. Consulta Trigger di Cloud Functions per informazioni su trigger, tipi di eventi e formati dei dati degli eventi associati supportati.
Il repository Google Events contiene risorse per lavorare con CloudEvents emessi da Google.
Funzioni in background
Le funzioni basate su eventi nei runtime Node.js, Python, Go e Java di Cloud Functions (1ª generazione) prevedono argomenti diversi dalle funzioni CloudEvent. Questo stile precedente di funzione basata su eventi è chiamato funzione in background.
L'esempio seguente mostra un file di origine della funzione in background di base per ogni runtime. Consulta Struttura della directory di origine per informazioni su dove trovare il codice sorgente.
Node.js
// Define and export an event handler
exports.myBackgroundFunction = (eventData, context, callback) => {
// Your code here
// The eventData argument represents the event data payload
// Optionally signal function completion:
callback();
};
In Node.js, definisci ed esporta una funzione che gestisce i dati degli eventi. Cloud Functions trasmette alla funzione gestore i seguenti argomenti:
eventData
: un oggetto che rappresenta il payload dei dati sugli eventi. Il suo formato dipende dal tipo di evento.context
: un oggetto contenente metadati relativi all'evento.callback
: una funzione facoltativa che puoi chiamare per segnalare il completamento dell'operazione. Il primo argomento di questo callback viene interpretato come segnalazione di un errore. Non trasmettere argomenti o un primo argomentonull
per indicare l'esito positivo.
Il punto di ingresso della funzione è il nome del gestore di eventi esportato. In questo esempio, il punto di ingresso è myBackgroundFunction
.
Python
# Define an event handler
def my_background_function(event_data, context):
# Your code here
# The event_data argument represents the event data payload
In Python, definisci una funzione che gestisce i dati degli eventi. Cloud Functions trasmette alla funzione gestore i seguenti argomenti:
event_data
: un dizionario che rappresenta il payload dei dati sugli eventi. Il suo formato dipende dal tipo di evento.context
: un oggetto contenente metadati relativi all'evento.
Il punto di ingresso della funzione è il nome della funzione del gestore. In questo esempio, il punto di ingresso è my_background_function
.
Go
package mybackgroundfunction import ( "context" ) // Function MyBackgroundFunction accepts and handles event data func MyBackgroundFunction(ctx context.Context, e EventDataType) error { // Your code here // The argument e represents the event data payload // Return nil if no error occurred return nil }
In Go, definisci una funzione esportata che gestisce i dati degli eventi. Cloud Functions trasmette alla funzione gestore i seguenti argomenti:
ctx
: un oggettocontext.Context
contenente i metadati sull'evento. Puoi recuperare i metadati utilizzando il pacchettocloud.google.com/go/functions/metadata
.e
: un oggetto che rappresenta il payload dei dati sugli eventi. Il suo tipo, mostrato nell'esempio sopra comeEventDataType
, deve essere uno struct corrispondente al tipo di evento gestito dalla funzione. Il payload dei dati degli eventi viene eseguito nello struct utilizzandojson.Unmarshal()
.
Il punto di ingresso della funzione è il nome del gestore di eventi esportato. In questo esempio, il punto di ingresso è MyBackgroundFunction
.
Java
package mybackgroundfunction; import com.google.cloud.functions.BackgroundFunction; import com.google.cloud.functions.Context; // Define a class that implements the BackgroundFunction<T> interface public class MyBackgroundFunction implements BackgroundFunction<EventDataType> { // Implement the accept() method to handle events @Override public void accept(EventDataType eventData, Context context) { // Your code here // The eventData argument represents the event data payload } }
In Java, puoi usare
l'API Java del framework delle funzioni
per implementare una classe del gestore di eventi con l'interfaccia
BackgroundFunction<T>
. Il metodo accept()
accetta come argomenti il payload dei dati dell'evento e un oggetto Context
contenente metadati relativi all'evento.
Il tipo di argomento del payload dei dati dell'evento, mostrato nell'esempio precedente come EventDataType
, deve corrispondere al tipo di evento gestito dalla funzione. Il payload dei dati sugli eventi viene deserializzato in un'istanza di questa classe utilizzando Gson.fromJson()
.
Il punto di ingresso della funzione è il nome completo della classe del gestore di eventi, incluso il nome del pacchetto. In questo esempio, il punto di ingresso è mybackgroundfunction.MyBackgroundFunction
.
Per le funzioni in background, il payload dei dati sugli eventi viene passato direttamente alla tua funzione in un formato corrispondente al tipo di evento che attiva la funzione. Consulta Trigger supportati in Cloud Functions (1ª generazione.) per informazioni su trigger, tipi di eventi e formati di dati degli eventi associati supportati.
Terminazione della funzione
Cloud Functions considera completa l'esecuzione della funzione basata su eventi quando la funzione restituisce. Se la funzione crea attività in background (ad esempio, con thread, future, oggetti Promise
JavaScript, callback o processi di sistema), devi terminare o risolvere in altro modo queste attività prima di tornare dalla funzione. Qualsiasi attività non terminata prima della restituzione della funzione potrebbe non essere completata e potrebbe causare un comportamento indefinito.
Nuovi tentativi automatici
Le funzioni basate su eventi possono essere configurate per ritentare automaticamente le chiamate non riuscite. Per ulteriori informazioni, consulta Riprovare le funzioni basate su eventi.
Passaggi successivi
- Scopri di più sui trigger di Cloud Functions.
- Scopri come eseguire il deployment di una funzione Cloud Functions.
- Consulta i tutorial per esempi di diversi casi d'uso di Cloud Functions, inclusi esempi di funzioni basate su eventi.