Scrivi funzioni basate su eventi

In Cloud Run Functions, utilizzi 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, a seconda del runtime del linguaggio scelto:

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ù sulle specifiche CloudEvents nel repository GitHub di CloudEvents. Il progetto CloudEvents fornisce anche un insieme di SDK CloudEvents per aiutarti a lavorare con gli oggetti CloudEvents nel tuo codice.

L'esempio seguente mostra un file di codice sorgente di una funzione CloudEvent di base per ogni runtime. Consulta 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 framework di Functions per .NET per implementare una classe 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 di dati CloudEvent, mostrato nell'esempio precedente come CloudEventDataType, deve corrispondere al tipo di evento gestito dalla funzione. La libreria Google CloudEvents .NET fornisce tipi di dati per i vari eventi supportati da Google.

L'entry point della funzione è il nome completo della classe gestore CloudEvent, incluso lo spazio dei nomi. In questo esempio, l'entry point è 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 gestione CloudEvent con il framework di Functions per Ruby. La funzione del gestore deve accettare un oggetto CloudEvents Event come argomento.

L'entry point della funzione è il nome con cui il gestore viene registrato con il framework di Functions. In questo esempio, l'entry point è 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 gestione CloudEvent con il framework di Functions per PHP. La funzione del gestore deve accettare un argomento conforme all'interfaccia CloudEventInterface.

L'entry point della funzione è il nome con cui il gestore viene registrato con il framework di Functions. In questo esempio, l'entry point è 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 di Cloud Run Functions per informazioni su trigger, tipi di eventi e formati dei dati sugli eventi associati supportati.

Il repository Google Eventi contiene le 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 precedente di funzione basata sugli eventi è chiamato funzione in background.

L'esempio seguente mostra un file di codice sorgente di una funzione di base in background 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 esporti una funzione che gestisce i dati sugli eventi. Cloud Run Functions passa alla funzione di gestione 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 segnalazione di un errore. Non passare argomenti o un primo argomento null per segnalare la riuscita.

L'entry point della funzione è il nome del gestore di eventi esportato. In questo esempio, l'entry point è 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. Cloud Run Functions passa alla funzione di gestione 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.

L'entry point della funzione è il nome della funzione di gestione. In questo esempio, l'entry point è 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 sugli eventi. Cloud Run Functions passa alla funzione di gestione i seguenti argomenti:

  • ctx: un oggetto context.Context contenente i metadati dell'evento. Puoi recuperare i metadati utilizzando il pacchetto cloud.google.com/go/functions/metadata.
  • e: un oggetto che rappresenta il payload dei dati sugli eventi. Il suo tipo, mostrato nell'esempio precedente come EventDataType, deve essere uno struct corrispondente al tipo di evento gestito dalla funzione. Il payload dei dati sugli evento viene deserializzato nella struttura utilizzando json.Unmarshal().

L'entry point della funzione è il nome del gestore di eventi esportato. In questo esempio, l'entry point è 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 Functions Framework Java per implementare una classe gestore di 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 dell'evento.

Il tipo di argomento del payload dei dati sugli eventi, 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().

L'entry point della funzione è il nome completo della classe gestore di eventi, incluso il nome del pacchetto. In questo esempio, l'entry point è 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 la sezione Trigger supportati in Cloud Run Functions (1ª gen.) per informazioni su trigger, tipi di eventi e formati dei dati sugli eventi associati supportati.

Termine della funzione

Cloud Run Functions considera completata l'esecuzione della funzione basata su eventi quando la funzione restituisce un valore. Se la funzione crea attività in background (ad esempio con thread, future, oggetti JavaScript Promise, callback o processi di sistema), devi terminare o risolvere queste attività prima di uscire dalla funzione. Le attività non terminate prima del termine della funzione potrebbero non essere completate e causare un comportamento indefinito.

Nuovi tentativi automatici

Le funzioni basate su eventi possono essere configurate in modo da riprovare automaticamente le chiamate non riuscite. Per saperne di più, consulta Ripetizione dei tentativi di esecuzione delle funzioni basate su eventi.

Passaggi successivi