Escreva funções orientadas por eventos

Nas funções do Cloud Run, usa funções orientadas por eventos quando quer que uma função seja invocada automaticamente em resposta a um evento que ocorra no seu ambiente de nuvem.

Existem duas formas de implementar funções orientadas por eventos. A forma como usa o depende do tempo de execução do idioma escolhido:

Funções CloudEvent

As funções CloudEvent baseiam-se em CloudEvents, uma especificação da indústria para descrever dados de eventos de forma comum. Pode saber mais acerca da especificação CloudEvents no repositório do GitHub do CloudEvents. O projeto CloudEvents também fornece um conjunto de SDKs CloudEvents para ajudar a trabalhar com objetos CloudEvents no seu código.

O exemplo seguinte mostra um ficheiro de origem de função CloudEvent básico para cada tempo de execução. Consulte a secção Estrutura do diretório de origem para obter informações sobre onde localizar o código-fonte.

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;
        }
    }
}

Nos runtimes .NET, usa o Functions Framework para .NET para implementar uma classe de controlador CloudEvent com a interface ICloudEventFunction<T>. O método HandleAsync() aceita um objeto CloudEvent e a carga útil de dados CloudEvent associada como argumentos.

O tipo do argumento de payload de dados do CloudEvent, apresentado no exemplo acima como CloudEventDataType, tem de corresponder ao tipo de evento que a função processa. A biblioteca .NET Google CloudEvents fornece tipos de dados para os vários eventos suportados pela Google.

O ponto de entrada da função é o nome totalmente qualificado da classe do controlador de CloudEvent, incluindo o espaço de nomes. Neste exemplo, o ponto de entrada é 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

Em Ruby, regista uma função de controlador de CloudEvent com o Functions Framework para Ruby. A função de controlador tem de aceitar um objeto CloudEvents Event como argumento.

O ponto de entrada da função é o nome com o qual o controlador está registado no Functions Framework. Neste exemplo, o ponto de entrada é 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()
}

Em PHP, regista uma função de controlador de CloudEvent com o Functions Framework para PHP. A função de controlador tem de aceitar um argumento em conformidade com a interface CloudEventInterface.

O ponto de entrada da função é o nome com o qual o controlador está registado no Functions Framework. Neste exemplo, o ponto de entrada é myCloudEventFunction.

Para as funções CloudEvent, os dados de eventos são transmitidos à sua função no formato CloudEvents, com uma carga útil de dados CloudEvent correspondente ao tipo de evento que aciona a sua função. Consulte os acionadores de funções do Cloud Run para ver informações sobre os acionadores suportados, os tipos de eventos e os formatos de dados de eventos associados.

O repositório Google Events contém recursos para trabalhar com CloudEvents emitidos pela Google.

Funções em segundo plano

As funções acionadas por eventos nos runtimes Node.js, Python, Go e Java esperam argumentos diferentes das funções CloudEvent. Este estilo mais antigo de função orientada por eventos chama-se função em segundo plano.

O exemplo seguinte mostra um ficheiro de origem de função de fundo básico para cada tempo de execução. Consulte a secção Estrutura do diretório de origem para obter informações sobre onde localizar o código-fonte.

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();
};

No Node.js, define e exporta uma função que processa dados de eventos. As funções do Cloud Run transmitem os seguintes argumentos à sua função de controlador:

  • eventData: um objeto que representa o payload de dados de eventos. O formato depende do tipo de evento.
  • context: um objeto que contém metadados sobre o evento.
  • callback: uma função opcional que pode chamar para sinalizar a conclusão. O primeiro argumento desta função de retorno de chamada é interpretado como um sinal de erro. Não transmita argumentos ou transmita um primeiro argumento null para sinalizar o sucesso.

O ponto de entrada da função é o nome do controlador de eventos exportado. Neste exemplo, o ponto de entrada é 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

Em Python, define uma função que processa dados de eventos. As funções do Cloud Run transmitem os seguintes argumentos à sua função de controlador:

  • event_data: um dicionário que representa a carga útil de dados de eventos. O formato depende do tipo de evento.
  • context: um objeto que contém metadados sobre o evento.

O ponto de entrada da função é o nome da função do controlador. Neste exemplo, o ponto de entrada é 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
}

Em Go, define uma função exportada que processa dados de eventos. As funções do Cloud Run transmitem os seguintes argumentos à sua função de controlador:

  • ctx: um objeto context.Context que contém metadados sobre o evento. Pode obter os metadados através do pacote cloud.google.com/go/functions/metadata.
  • e: um objeto que representa o payload de dados de eventos. O respetivo tipo, apresentado no exemplo acima como EventDataType, tem de ser uma struct correspondente ao tipo de evento que a função processa. A carga útil dos dados de eventos é desorganizada na estrutura através de json.Unmarshal().

O ponto de entrada da função é o nome do controlador de eventos exportado. Neste exemplo, o ponto de entrada é 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
  }
}

Em Java, usa a API Java do Functions Framework para implementar uma classe de controlador de eventos com a interface BackgroundFunction<T>. O método accept() aceita como argumentos a carga útil de dados do evento e um objeto Context que contém metadados sobre o evento.

O tipo do argumento de payload de dados de eventos, apresentado no exemplo acima como EventDataType, tem de corresponder ao tipo de evento que a função processa. A carga útil de dados de eventos é desserializada numa instância desta classe através de Gson.fromJson().

O ponto de entrada da função é o nome totalmente qualificado da classe do controlador de eventos, incluindo o nome do pacote. Neste exemplo, o ponto de entrada é mybackgroundfunction.MyBackgroundFunction.

Para funções em segundo plano, a carga útil de dados de eventos é transmitida diretamente à sua função num formato correspondente ao tipo de evento que aciona a sua função. Consulte o artigo Acionadores suportados nas funções do Cloud Run (1.ª geração) para obter informações sobre os acionadores suportados, os tipos de eventos e os formatos de dados de eventos associados.

Terminação da função

As funções do Cloud Run consideram a execução de funções orientada por eventos concluída quando a função devolve um valor. Se a função criar tarefas em segundo plano (como com threads, futuros, objetos JavaScript Promise, callbacks ou processos do sistema), tem de terminar ou resolver estas tarefas antes de regressar da função. As tarefas não terminadas antes de a função ser devolvida podem não ser concluídas e podem causar um comportamento indefinido.

Novas tentativas automáticas

As funções acionadas por eventos podem ser configuradas para repetir automaticamente as invocações com falhas. Consulte o artigo Voltar a tentar funções acionadas por eventos para mais informações.

Passos seguintes