Funções do CloudEvent

Uma função do CloudEvent é um tipo de função orientada a eventos. As funções do CloudEvent são chamadas indiretamente em resposta a eventos, como uma mensagem em um tópico do Pub/Sub, uma alteração em um bucket do Cloud Storage ou um evento do Firebase.

Conceitualmente, as funções do CloudEvent são semelhantes a funções em segundo plano. A principal diferença entre as duas é que as funções do CloudEvent usam um formato de evento padrão do setor, conhecido como CloudEvents. Outra diferença é que o Cloud Functions invoca funções do CloudEvent usando solicitações HTTP, que podem ser reproduzidas em outro lugar. Juntas, essas diferenças permitem que as funções do CloudEvent sejam movidas facilmente entre as plataformas de computação.

Ambientes de execução compatíveis

Os ambientes de execução a seguir são compatíveis com as funções do CloudEvent:

Idioma Versão(ões):
PHP Beta Tudo
C# Beta Tudo
Ruby Beta Tudo

Parâmetros de função

As funções do CloudEvent recebem um único argumento cloudEvent que contém as propriedades e os metadados associados ao evento que acionou a execução da função. Os CloudEvents de entrada são convertidos em representações específicas de linguagem mostradas abaixo usando as bibliotecas do Functions Framework.

C#

O parâmetro cloudEvent é transmitido para a função como um objeto CloudEvent que contém estas propriedades:

Propriedade Tipo Descrição
Id String O ID exclusivo do evento.
Source Uri A entidade do Google Cloud afetada pelo evento, no formato /[SERVICE_DOMAIN_NAME]/[RESOURCE]/.
Type String O tipo de CloudEvent do evento recebido.
Time Anulável DateTimeOffset Um carimbo de data e hora de quando o evento ocorreu.
SpecVersion CloudEventsSpecVersion A versão de especificação do CloudEvents usada para criar o evento.
Data Object Um object contendo dados específicos de tipo de evento.
Subject String anulável O valor do assunto depende do tipo de evento acionado. Se o evento subjacente se referir a um objeto do Cloud Storage, ele será definido como o local do objeto, no formato objects/path/to/object. Alguns eventos não definem um assunto. Nesse caso, essa propriedade será null.

Ruby

O parâmetro cloudEvent é transmitido para a função como um objeto CloudEvents::Event::V1 que contém estas propriedades:

Propriedade Tipo Descrição
cloudEvent.id String O ID exclusivo do evento.
cloudEvent.source URI A entidade do Google Cloud afetada pelo evento, no formato /[SERVICE_DOMAIN_NAME]/[RESOURCE]/.
cloudEvent.type String O tipo de CloudEvent do evento recebido.
cloudEvent.time DateTime Um carimbo de data e hora de quando o evento ocorreu.
cloudEvent.specversion String A versão de especificação do CloudEvents usada para criar o evento.
cloudEvent.data Hash Um Hash contendo dados específicos de tipo de evento.
cloudEvent.subject String ou Nil O valor do assunto depende do tipo de evento acionado. Se o evento subjacente se referir a um objeto do Cloud Storage, ele será definido como o local do objeto, no formato objects/path/to/object. Alguns eventos não definem um assunto. Nesse caso, essa propriedade será Nil.

PHP

O parâmetro cloudEvent é transmitido para a função como um objeto CloudEvent que contém estas funções:

Função Tipo Descrição
cloudEvent->getId() string O ID exclusivo do evento.
cloudEvent->getSource() string A entidade do Google Cloud afetada pelo evento, no formato /[SERVICE_DOMAIN_NAME]/[RESOURCE]/.
cloudEvent->getType() string O tipo de CloudEvent do evento recebido.
cloudEvent->getTime() ?string Um carimbo de data e hora de quando o evento ocorreu.
cloudEvent->getSpecVersion() string A versão de especificação do CloudEvents usada para criar o evento.
cloudEvent->getSubject() ?string O valor do assunto depende do tipo de evento acionado. Se o evento subjacente se referir a um objeto do Cloud Storage, ele será definido como o local do objeto, no formato objects/path/to/object. Alguns eventos não definem um assunto. Nesse caso, essa propriedade será null.
cloudEvent->getData() Object Um object contendo dados específicos de tipo de evento.

Exemplo de uso

Os exemplos abaixo mostram como processar eventos do Pub/Sub e do Cloud Storage. Para ver mais informações sobre como processar eventos de diferentes origens, consulte Como chamar Cloud Functions.

Exemplo do Pub/Sub

Este exemplo mostra uma função do CloudEvent acionada por eventos do Pub/Sub. Toda vez que uma mensagem é publicada em um tópico do Pub/Sub, a função é invocada e uma saudação usando dados derivados da mensagem é gravada no registro.

C#

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

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


use Google\CloudFunctions\CloudEvent;

function helloworldPubsub(CloudEvent $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);
}

Para ver mais informações sobre como implantar o Cloud Functions acionado por eventos do Pub/Sub, consulte Acionadores do Pub/Sub e Tutorial do Pub/Sub.

Exemplo do Cloud Storage

Neste exemplo, você verá uma função do CloudEvent acionada por eventos do Cloud Storage. Toda vez que um objeto é criado em um bucket do Cloud Storage, a função é invocada e uma mensagem sobre a alteração é gravada no registro.

C#

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
{
    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

require "functions_framework"

FunctionsFramework.cloud_event "hello_gcs" do |event|
  # 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


use Google\CloudFunctions\CloudEvent;

function helloGCS(CloudEvent $cloudevent)
{
    $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);
}

Para mais informações sobre como implantar funções do CloudEvent acionadas por eventos do Cloud Storage, consulte Acionadores do Cloud Storage e Tutorial do Cloud Storage.

Para informações sobre como enviar eventos (também no formato CloudEvents) para um serviço de destino do Cloud Run usando Eventarc, consulte Guia de início rápido: Receber eventos do Cloud Storage.

Dicas

Geração de registros de eventos

O conteúdo dos eventos não é registrado automaticamente, porque pode conter informações confidenciais. Para registrar o conteúdo do evento, você precisa fazê-lo explicitamente, conforme descrito em Como gravar, ver e responder a registros.

Como encerrar funções do CloudEvent

Se uma função do CloudEvent criar tarefas em segundo plano, você precisará resolvê-las antes de retornar a função para evitar erros e/ou comportamento indefinido.

Novas tentativas automáticas

As funções do CloudEvent podem ser configuradas para repetir automaticamente invocações com falha. Consulte Como repetir funções orientadas a eventos para mais informações.

Próximas etapas