Funzioni CloudEvent

Una funzione CloudEvent è un tipo di funzione basata su eventi. Le funzioni CloudEvent vengono richiamate indirettamente in risposta a eventi, come un messaggio su un argomento Pub/Sub, una modifica in un bucket Cloud Storage o un evento Firebase.

Le funzioni CloudEvent sono concettualmente simili alle funzioni in background. La differenza principale tra i due è che le funzioni CloudEvent utilizzano un formato di evento standard del settore noto come CloudEvents. Un'altra differenza è che Cloud Functions richiama le funzioni CloudEvent utilizzando le richieste HTTP, che possono essere riprodotte altrove. Insieme, queste differenze consentono di spostare senza problemi le funzioni CloudEvent tra le piattaforme di computing.

Runtime supportati

I seguenti runtime supportano le funzioni CloudEvent:

Lingua Versioni
PHP Beta Tutti
C# Beta Tutti
Beta rubino Tutti

Parametri funzione

Alle funzioni CloudEvent viene passato un singolo argomento cloudEvent che contiene le proprietà e i metadati associati all'evento che ha attivato l'esecuzione della funzione. Gli eventi CloudEvent in entrata vengono quindi convertiti nelle rappresentazioni specifiche del linguaggio mostrate di seguito utilizzando le librerie Functions Framework.

C#

Il parametro cloudEvent viene passato alla funzione come oggetto CloudEvent che contiene le seguenti proprietà:

Proprietà Tipo Descrizione
Id String L'ID univoco dell'evento.
Source Uri L'entità Google Cloud interessata dall'evento nel formato /[SERVICE_DOMAIN_NAME]/[RESOURCE]/.
Type String Il tipo CloudEvent dell'evento ricevuto.
Time DateTimeOffset annullabili Un timestamp del momento in cui si è verificato l'evento.
SpecVersion CloudEventsSpecVersion La versione della specifica CloudEvents utilizzata per creare l'evento.
Data Object Un elemento object contenente dati specifici del tipo di evento.
Subject String annullabili Il valore dell'oggetto dipende dal tipo di evento attivato. Ad esempio, se l'evento sottostante si riferisce a un oggetto Cloud Storage, verrà impostato sulla posizione dell'oggetto, nel formato objects/path/to/object. Alcuni eventi non impostano un oggetto, nel qual caso questa proprietà sarà null.

Ruby

Il parametro cloudEvent viene trasmesso alla funzione come un oggetto CloudEvents::Event::V1 contenente le seguenti proprietà:

Proprietà Tipo Descrizione
cloudEvent.id String L'ID univoco dell'evento.
cloudEvent.source URI L'entità Google Cloud interessata dall'evento nel formato /[SERVICE_DOMAIN_NAME]/[RESOURCE]/.
cloudEvent.type String Il tipo CloudEvent dell'evento ricevuto.
cloudEvent.time DateTime Un timestamp del momento in cui si è verificato l'evento.
cloudEvent.specversion String La versione della specifica CloudEvents utilizzata per creare l'evento.
cloudEvent.data Hash Un elemento Hash contenente dati specifici del tipo di evento.
cloudEvent.subject String o Nil Il valore dell'oggetto dipende dal tipo di evento attivato. Ad esempio, se l'evento sottostante si riferisce a un oggetto Cloud Storage, verrà impostato sulla posizione dell'oggetto, nel formato objects/path/to/object. Alcuni eventi non impostano un oggetto, nel qual caso questa proprietà sarà Nil.

PHP

Il parametro cloudEvent viene inserito nella funzione come un oggetto CloudEvent che contiene quanto segue:

Funzione Tipo Descrizione
cloudEvent->getId() string L'ID univoco dell'evento.
cloudEvent->getSource() string L'entità Google Cloud interessata dall'evento nel formato /[SERVICE_DOMAIN_NAME]/[RESOURCE]/.
cloudEvent->getType() string Il tipo CloudEvent dell'evento ricevuto.
cloudEvent->getTime() ?string Un timestamp del momento in cui si è verificato l'evento.
cloudEvent->getSpecVersion() string La versione della specifica CloudEvents utilizzata per creare l'evento.
cloudEvent->getSubject() ?string Il valore dell'oggetto dipende dal tipo di evento attivato. Ad esempio, se l'evento sottostante si riferisce a un oggetto Cloud Storage, verrà impostato sulla posizione dell'oggetto, nel formato objects/path/to/object. Alcuni eventi non impostano un oggetto, nel qual caso questa proprietà sarà null.
cloudEvent->getData() Object Un elemento object contenente dati specifici del tipo di evento.

Esempi di utilizzo

Gli esempi riportati di seguito mostrano come elaborare gli eventi da Pub/Sub e Cloud Storage. Per ulteriori informazioni sulla gestione degli eventi da sorgenti diverse, consulta Chiamata di Cloud Functions.

Esempio di Pub/Sub

Questo esempio mostra una funzione CloudEvent attivata da eventi Pub/Sub. Ogni volta che un messaggio viene pubblicato in un argomento Pub/Sub, la funzione viene richiamata e un saluto utilizzando i dati derivati dal messaggio viene scritto nel log.

C#

Functions/helloworld/HelloPubSub/Function.cs 
using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using Google.Events.Protobuf.Cloud.PubSub.V1;
using Microsoft.Extensions.Logging;
using System.Threading;
using System.Threading.Tasks;

namespace HelloPubSub
{
    public class Function : ICloudEventFunction<MessagePublishedData>
    {
        private readonly ILogger _logger;

        public Function(ILogger<Function> logger) =>
            _logger = logger;

        public Task HandleAsync(CloudEvent cloudEvent, MessagePublishedData data, CancellationToken cancellationToken)
        {
            string nameFromMessage = data.Message?.TextData;
            string name = string.IsNullOrEmpty(nameFromMessage) ? "world" : nameFromMessage;
            _logger.LogInformation("Hello {name}", name);
            return Task.CompletedTask;
        }
    }
}

Ruby

Functions/helloworld/pubsub/app.rb 
require "functions_framework"
require "base64"

FunctionsFramework.cloud_event "hello_pubsub" do |event|
  # The event parameter is a CloudEvents::Event::V1 object.
  # See https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event/V1.html
  name = Base64.decode64 event.data["message"]["data"] rescue "World"

  # A cloud_event function does not return a response, but you can log messages
  # or cause side effects such as sending additional events.
  logger.info "Hello, #{name}!"
end

PHP

Functions/helloworld_pubsub/index.php 

use CloudEvents\V1\CloudEventInterface;
use Google\CloudFunctions\FunctionsFramework;

// Register the function with Functions Framework.
// This enables omitting the `FUNCTIONS_SIGNATURE_TYPE=cloudevent` environment
// variable when deploying. The `FUNCTION_TARGET` environment variable should
// match the first parameter.
FunctionsFramework::cloudEvent('helloworldPubsub', 'helloworldPubsub');

function helloworldPubsub(CloudEventInterface $event): void
{
    $log = fopen(getenv('LOGGER_OUTPUT') ?: 'php://stderr', 'wb');

    $cloudEventData = $event->getData();
    $pubSubData = base64_decode($cloudEventData['message']['data']);

    $name = $pubSubData ? htmlspecialchars($pubSubData) : 'World';
    fwrite($log, "Hello, $name!" . PHP_EOL);
}

Per ulteriori informazioni sul deployment di Cloud Functions attivati da eventi Pub/Sub, consulta gli argomenti Trigger Pub/Sub e Tutorial su Pub/Sub.

Esempio di Cloud Storage

Questo esempio mostra una funzione CloudEvent attivata dagli eventi Cloud Storage. Ogni volta che viene creato un oggetto in un bucket Cloud Storage, la funzione viene richiamata e un messaggio sulla modifica viene scritto nel log.

C#

Functions/helloworld/HelloGcs/Function.cs 
using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using Google.Events.Protobuf.Cloud.Storage.V1;
using Microsoft.Extensions.Logging;
using System.Threading;
using System.Threading.Tasks;

namespace HelloGcs
{
     /// <summary>
     /// Example Cloud Storage-triggered function.
     /// This function can process any event from Cloud Storage.
     /// </summary>
    public class Function : ICloudEventFunction<StorageObjectData>
    {
        private readonly ILogger _logger;

        public Function(ILogger<Function> logger) =>
            _logger = logger;

        public Task HandleAsync(CloudEvent cloudEvent, StorageObjectData data, CancellationToken cancellationToken)
        {
            _logger.LogInformation("Event: {event}", cloudEvent.Id);
            _logger.LogInformation("Event Type: {type}", cloudEvent.Type);
            _logger.LogInformation("Bucket: {bucket}", data.Bucket);
            _logger.LogInformation("File: {file}", data.Name);
            _logger.LogInformation("Metageneration: {metageneration}", data.Metageneration);
            _logger.LogInformation("Created: {created:s}", data.TimeCreated?.ToDateTimeOffset());
            _logger.LogInformation("Updated: {updated:s}", data.Updated?.ToDateTimeOffset());
            return Task.CompletedTask;
        }
    }
}

Ruby

Functions/helloworld/storage/app.rb 
require "functions_framework"

FunctionsFramework.cloud_event "hello_gcs" do |event|
  # This function supports all Cloud Storage events.
  # The `event` parameter is a CloudEvents::Event::V1 object.
  # See https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event/V1.html
  payload = event.data

  logger.info "Event: #{event.id}"
  logger.info "Event Type: #{event.type}"
  logger.info "Bucket: #{payload['bucket']}"
  logger.info "File: #{payload['name']}"
  logger.info "Metageneration: #{payload['metageneration']}"
  logger.info "Created: #{payload['timeCreated']}"
  logger.info "Updated: #{payload['updated']}"
end

PHP

Functions/helloworld_storage/index.php 

use CloudEvents\V1\CloudEventInterface;
use Google\CloudFunctions\FunctionsFramework;

// Register the function with Functions Framework.
// This enables omitting the `FUNCTIONS_SIGNATURE_TYPE=cloudevent` environment
// variable when deploying. The `FUNCTION_TARGET` environment variable should
// match the first parameter.
FunctionsFramework::cloudEvent('helloGCS', 'helloGCS');

function helloGCS(CloudEventInterface $cloudevent)
{
    // This function supports all Cloud Storage event types.
    $log = fopen(getenv('LOGGER_OUTPUT') ?: 'php://stderr', 'wb');
    $data = $cloudevent->getData();
    fwrite($log, 'Event: ' . $cloudevent->getId() . PHP_EOL);
    fwrite($log, 'Event Type: ' . $cloudevent->getType() . PHP_EOL);
    fwrite($log, 'Bucket: ' . $data['bucket'] . PHP_EOL);
    fwrite($log, 'File: ' . $data['name'] . PHP_EOL);
    fwrite($log, 'Metageneration: ' . $data['metageneration'] . PHP_EOL);
    fwrite($log, 'Created: ' . $data['timeCreated'] . PHP_EOL);
    fwrite($log, 'Updated: ' . $data['updated'] . PHP_EOL);
}

Per ulteriori informazioni sul deployment delle funzioni CloudEvent attivate dagli eventi di Cloud Storage, consulta i attivatori di Cloud Storage e il tutorial su Cloud Storage.

Per informazioni sulla distribuzione degli eventi (anche in formato CloudEvents) a un servizio Cloud Run di destinazione utilizzando Eventarc, consulta la sezione Creare un trigger per Cloud Run.

Suggerimenti utili

Logging degli eventi

I contenuti dell'evento non vengono registrati automaticamente perché potrebbero contenere informazioni riservate. Se vuoi registrare i contenuti degli eventi, devi farlo in modo esplicito come descritto nelle sezioni Scrittura, visualizzazione e risposta ai log.

Terminazione delle funzioni CloudEvent

Se una funzione CloudEvent crea attività in background, è necessario risolvere queste attività prima di tornare dalla funzione per evitare errori e/o comportamenti non definiti.

Tentativi automatici

Le funzioni CloudEvent possono essere configurate per riprovare automaticamente le chiamate non riuscite. Per ulteriori informazioni, consulta la sezione Riprovare le funzioni basate su eventi.

Passaggi successivi