Scrivere funzioni basate su eventi
Nelle funzioni Cloud Run, utilizzi le funzioni basate sugli 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. Il metodo che utilizzi dipende dal runtime della lingua scelto:
- Per i runtime Node.js, Python, Go e Java, utilizza funzioni in background.
- Per gli ambienti di 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 un modo comune. Per saperne di più sulla specifica CloudEvents, visita il repository GitHub di CloudEvents. Il progetto CloudEvents fornisce anche un insieme di SDK CloudEvents per aiutarti a utilizzare gli oggetti CloudEvents nel codice.
L'esempio seguente mostra un file di origine della funzione CloudEvent di base per ogni ambiente di esecuzione. Consulta la sezione Struttura della directory di origine per informazioni su dove trovare il codice sorgente.
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, utilizzi il
Functions Framework per .NET
per implementare una classe di gestore CloudEvent con l'interfaccia
ICloudEventFunction<T>
. Il metodo HandleAsync()
accetta come argomenti un oggetto CloudEvent
e il payload dei dati CloudEvent associato.
Il tipo dell'argomento del payload dei dati CloudEvent, indicato nell'esempio precedente come
CloudEventDataType
, deve corrispondere al tipo di evento gestito dalla funzione. La libreria .NET Google CloudEvents fornisce i tipi di dati per i vari eventi supportati da Google.
Il
punto di ingresso della funzione
è il nome completo della classe di 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 di gestore di CloudEvent con il Functions Framework per Ruby.
La funzione del gestore deve accettare un oggetto CloudEvents
Event
come argomento.
Il
punto di ingresso della funzione
è il nome con cui il gestore è registrato nel Functions Framework.
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 di gestore di CloudEvent con il Framework di Functions per PHP.
La funzione del gestore deve accettare un argomento conforme all'interfaccia CloudEventInterface
.
Il
punto di ingresso della funzione
è il nome con cui il gestore è registrato nel Functions Framework.
In questo esempio, il punto di ingresso è myCloudEventFunction
.
Per le funzioni CloudEvent, i dati sugli eventi vengono passati alla funzione nel formato CloudEvents, con un payload di dati CloudEvent corrispondente al tipo di evento che attiva la funzione. Consulta Trigger delle funzioni Cloud Run per informazioni su trigger, tipi di eventi e formati dei dati sugli eventi 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 prevedono argomenti diversi rispetto alle funzioni CloudEvent. Questo stile più antico di funzione basata sugli eventi è chiamato funzione in background.
L'esempio seguente mostra un file di origine della funzione in background di base per ogni ambiente di runtime. Consulta la sezione 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 esporti una funzione che gestisce i dati sugli eventi. Le funzioni Cloud Run passano alla funzione di gestore i seguenti argomenti:
eventData
: un oggetto che rappresenta il payload dei dati sugli eventi. Il formato dipende dal tipo di evento.context
: un oggetto contenente i metadati dell'evento.callback
: una funzione facoltativa che puoi chiamare per segnalare il completamento. Il primo argomento di questo callback viene interpretato come un segnale di errore. Non passare argomenti o un primo argomentonull
per indicare il successo.
Il
punto di ingresso della funzione
è il nome del gestore degli 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 sugli eventi. Le funzioni Cloud Run passano alla funzione di gestore i seguenti argomenti:
event_data
: un dizionario che rappresenta il payload dei dati sugli eventi. Il formato dipende dal tipo di evento.context
: un oggetto contenente i metadati dell'evento.
Il
punto di ingresso della funzione
è il nome della funzione di gestore. In questo esempio, il punto di ingresso è
my_background_function
.
Vai
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 sugli eventi. Le funzioni Cloud Run passano alla funzione di gestore i seguenti argomenti:
ctx
: un oggettocontext.Context
contenente i metadati dell'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 relativo tipo, indicato nell'esempio precedente comeEventDataType
, deve essere una struct corrispondente al tipo di evento gestito dalla funzione. Il payload dei dati dell'evento viene sunmarshaled nella struttura utilizzandojson.Unmarshal()
.
Il
punto di ingresso della funzione
è il nome del gestore degli 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, utilizzi l'API Java di Functions Framework per implementare una classe di gestore eventi con l'interfaccia BackgroundFunction<T>
. Il metodo accept()
accetta come argomenti il payload dei dati sugli eventi e un oggetto Context
contenente i metadati relativi all'evento.
Il tipo dell'argomento del payload dei dati sugli eventi, indicato nell'esempio precedente come
EventDataType
, deve corrispondere al tipo di evento gestito dalla
funzione. Il payload dei dati dell'evento viene deserializzato in un'istanza di questa classe utilizzando Gson.fromJson()
.
Il
punto di ingresso della funzione
è il nome completo della classe di gestore eventi, incluso il nome del pacchetto. In questo esempio, il punto di ingresso è
mybackgroundfunction.MyBackgroundFunction
.
Per le funzioni in background, il payload dei dati dell'evento viene passato direttamente alla funzione in un formato corrispondente al tipo di evento che attiva la funzione. Consulta Trigger supportati nelle funzioni Cloud Run (1ª generazione.) per informazioni sui trigger, sui tipi di eventi e sui formati dei dati degli eventi associati supportati.
Terminazione della funzione
Le funzioni Cloud Run considerano completata l'esecuzione di funzioni basate su eventi quando la funzione restituisce un valore. 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. Eventuali attività non terminate prima del ritorno della funzione potrebbero non essere completate e potrebbero causare un comportamento non definito.
Nuovi tentativi automatici
Le funzioni basate su eventi possono essere configurate per riprovare automaticamente le invocazioni non riuscite. Per ulteriori informazioni, consulta Riprovare le funzioni basate su eventi.
Passaggi successivi
- Scopri di più sugli trigger delle funzioni Cloud Run.
- Scopri come eseguire il deployment di una funzione Cloud Run.
- Consulta la sezione Tutorial per esempi di diversi casi d'uso delle funzioni Cloud Run, inclusi esempi di funzioni basate su eventi.