Scrivere funzioni CloudEvents

In Cloud Run, scrivi una funzione CloudEvents (chiamata anche funzione basata su eventi) quando vuoi che una funzione venga attivata direttamente in risposta a eventi all'interno del tuo progetto Google Cloud, ad esempio messaggi su un argomento Pub/Sub o modifiche in un bucket Cloud Storage.

Implementare le funzioni di gestore CloudEvents

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.

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 using cloudEvent.data
});

In Node.js, registri una funzione di gestore CloudEvent con il Functions Framework per Node.js. La funzione del gestore deve accettare un oggetto CloudEvent 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 è 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 di gestore di CloudEvent con il Functions Framework per Python. La funzione del gestore deve accettare un oggetto CloudEvent come argomento.

Il punto di ingresso della funzione è il nome della funzione di gestore registrata nel Functions Framework. In questo esempio, il punto di ingresso è my_cloudevent_function.

Vai

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 using e.Data() or e.DataAs(...)

    // Returning an error causes its message to be logged.
    // Example:
    err := myInternalFunction() // may return an error
    if err != nil {
        // Append error message to log
        return err
    }

    // Return nil if no error occurred
    return nil
}

In Go, registri una funzione di gestore CloudEvent con il Functions Framework per Go. La funzione di gestore deve accettare un oggetto CloudEvents event.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 è 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 using event.getData()
    // To get the data payload as a JSON string, use:
    // new String(event.getData().toBytes())
  }
}

In Java, utilizza l'API Java di Functions Framework per implementare una classe di gestore CloudEvent con l'interfaccia CloudEventsFunction. Il metodo accept() deve accettare un oggetto CloudEvent come argomento ed eseguire qualsiasi elaborazione sull'evento.

Il punto di ingresso della funzione è il nome completo della classe di gestore degli eventi Cloud, incluso il nome del pacchetto. In questo esempio, il punto di ingresso è mycloudeventfunction.MyCloudEventFunction.

.NET

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, mostrato nel codice di esempio 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 using $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 per informazioni su trigger, tipi di eventi e formati dei dati degli eventi supportati.

Il repository Google Events contiene risorse per lavorare con CloudEvents emessi da Google.

Terminazione della funzione

Cloud Run considera completata l'esecuzione di una funzione basata su eventi quando la funzione restituisce un valore. Se la funzione crea attività in background (ad esempio con thread, future, oggetti Promise di 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