Scrivere funzioni basate su eventi

Nelle funzioni di Cloud Run, utilizzi le funzioni basate su eventi quando vuoi una funzione da richiamare automaticamente in risposta a un evento che si verifica nel tuo completamente gestito di Google Cloud.

Esistono due modi per implementare le funzioni basate su eventi. Il metodo che utilizzi dipende dal runtime della lingua scelto:

Funzioni CloudEvent

Le funzioni di CloudEvent si basano su CloudEvents, uno standard di settore per descrivere i dati sugli eventi in modo comune. Puoi scoprire di più sulla specifica CloudEvents Repository GitHub di CloudEvents. Il progetto CloudEvents offre anche una serie SDK CloudEvents per lavorare con gli oggetti Cloud Eventi 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 di argomento payload dei dati CloudEvent, mostrato nell'esempio precedente come CloudEventDataType, deve corrispondere al tipo di evento gli handle della funzione. La libreria .NET Google CloudEvents fornisce i tipi di dati per i vari eventi supportati da Google.

La punto di accesso alla funzione è il nome completo della classe di gestori CloudEvent, che include nello 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 CloudEvent con il Framework di funzioni per Ruby. La funzione del gestore deve accettare un oggetto CloudEvents Event come argomento.

La punto di accesso alla funzione è il nome con cui il gestore viene 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 di gestore di CloudEvent con il Functions Framework per PHP. La tua funzione gestore deve accettare un argomento conforme alle CloudEventInterface a riga di comando.

La punto di accesso alla funzione è il nome con cui il gestore viene registrato nel framework di Functions. 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 di Cloud Run per informazioni su trigger, tipi di eventi e dati di eventi associati supportati formati.

La Google Eventi il repository contiene risorse per lavorare con gli eventi CloudEvents forniti 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 il vecchio stile 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 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 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 i metadati dell'evento.
  • callback: una funzione facoltativa che puoi richiamare per segnalare il completamento. Il primo a questo callback viene interpretato come segnalazione di un errore. Non passare argomenti o un primo argomento null 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 degli eventi. Le funzioni Cloud Run passano alla funzione 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 oggetto context.Context contenente i metadati relativi all'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 relativo tipo, indicato nell'esempio precedente come EventDataType, deve essere una struct corrispondente al tipo di evento gestito dalla funzione. I dati sugli eventi il payload viene disordinato nello struct json.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 Context contenente i metadati relativi all'evento.

Il tipo di argomento payload dei dati sugli eventi, mostrato nell'esempio precedente come EventDataType, deve corrispondere al tipo di evento che gli handle di funzione. Il payload dei dati sugli eventi viene deserializzato in un’istanza di questo corso 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 di Cloud Run (1ª generazione.) per informazioni su trigger e tipi di eventi supportati e dati sugli eventi associati formati.

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. Le attività non terminate prima della restituzione della funzione potrebbero non essere e potrebbe causare un comportamento indefinito.

Nuovi tentativi automatici

Le funzioni basate su eventi possono essere configurate per riprovare automaticamente le invocazioni non riuscite. Per saperne di più, consulta Riprovare le funzioni basate su eventi.

Passaggi successivi