Escrever funções orientadas a eventos
No Cloud Functions, use funções orientadas a eventos para que uma função seja invocada automaticamente em resposta a um evento que ocorre no ambiente da nuvem.
Há duas maneiras de implementar funções baseadas em eventos. A maneira como você usa depende do ambiente de execução da linguagem escolhida e de se você está usando o Cloud Functions (1ª geração) ou o Cloud Functions (2nd gen):
- No Cloud Functions (2nd gen), para todos os ambientes de execução, use as funções do CloudEvent.
- No Cloud Functions (1ª geração):
- Para ambientes de execução Node.js, Python, Go e Java, use as funções em segundo plano.
- Para ambientes de execução .NET, Ruby e PHP, use as funções do CloudEvent.
Funções do CloudEvent
As funções do CloudEvent são baseadas no CloudEvents, uma especificação padrão do setor para descrever dados de eventos de maneira comum. Saiba mais sobre a especificação do CloudEvents no repositório do GitHub do CloudEvents. O projeto CloudEvents também fornece um conjunto de SDKs do CloudEvents para ajudar a trabalhar com objetos do CloudEvents no código.
Veja no exemplo a seguir um arquivo de origem da função do CloudEvent básico para cada ambiente de execução. Consulte Estrutura do diretório de origem para ver informações sobre onde localizar o código-fonte.
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 via cloudEvent.data
});
No Node.js, você registra uma função de gerenciador do CloudEvent com o frameworks Functions para Node.js.
A função de gerenciador precisa aceitar um objeto
CloudEvent
como argumento.
O
ponto de entrada de função
é o nome com que o gerenciador está registrado no Functions Framework.
Neste exemplo, o ponto de entrada é 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
Em Python, você registra uma função de gerenciador do CloudEvent com o Framework de funções para Python.
A função de gerenciador precisa aceitar um objeto
CloudEvent
como argumento.
O
ponto de entrada da função
é o nome da função do gerenciador registrada no Functions Framework.
Neste exemplo, o ponto de entrada é my_cloudevent_function
.
Go
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 via e.Data() or e.DataAs(...)
// Return nil if no error occurred
return nil
}
Em Go, registre uma função de manipulador do CloudEvent com o
Functions Framework para Go.
Sua função de gerenciador precisa aceitar um CloudEvents
event.Event
objeto como um argumento.
O
ponto de entrada de função
é o nome com que o gerenciador está registrado no Functions Framework.
Neste exemplo, o ponto de entrada é 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 via event.getData()
// To get the data payload as a JSON string, use:
// new String(event.getData().toBytes())
}
}
Em Java, use a
API Java Functions Functions Framework
para implementar uma classe de manipulador do CloudEvent com a
interface
CloudEventsFunction
. O método accept()
precisa aceitar um objeto
CloudEvent
como argumento e executar qualquer processamento no evento.
O ponto de entrada de função é o nome totalmente qualificado da classe de gerenciador do CloudEvent, incluindo o nome do pacote. Neste exemplo, o ponto de entrada é mycloudeventfunction.MyCloudEventFunction
.
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 ambientes de execução do .NET, você usa o
Framework do Functions para .NET
para implementar uma classe de manipulador do CloudEvent com a
ICloudEventFunction<T>
interface. O método HandleAsync()
aceita um objeto
CloudEvent
e o payload de dados associado do CloudEvent como argumentos.
O tipo de argumento de payload de dados do CloudEvent, mostrado no exemplo acima como CloudEventDataType
, precisa corresponder ao tipo de evento que a função processa. A
biblioteca .NET do Google CloudEvents
fornece tipos de dados para os vários eventos compatíveis com o Google.
O ponto de entrada de função é o nome totalmente qualificado da classe de manipulador do CloudEvent, incluindo o namespace. 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
No Ruby, você registra uma função de gerenciador do CloudEvent com o Functions Framework para Ruby.
A função de gerenciador precisa aceitar um objeto
Event
do CloudEvents como argumento.
O
ponto de entrada de função
é o nome com que o gerenciador está registrado 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, você registra uma função de gerenciador do CloudEvent com o Functions Framework para PHP.
A função de gerenciador precisa aceitar um argumento compatível com a
interface
CloudEventInterface
.
O
ponto de entrada de função
é o nome com que o gerenciador está registrado no Functions Framework.
Neste exemplo, o ponto de entrada é myCloudEventFunction
.
Para funções do CloudEvent, os dados de evento são transmitidos para a função no formato CloudEvents, com um payload de dados do CloudEvent correspondente ao tipo de evento que aciona sua função. Consulte Acionadores do Cloud Functions para ver informações sobre acionadores compatíveis, tipos de eventos e formatos de dados de eventos associados.
O repositório de Eventos do Google contém recursos para trabalhar com CloudEvents emitidos pelo Google.
Funções em segundo plano
As funções baseadas em eventos nos ambientes de execução do Cloud Functions (1ª geração) do Node.js, Python, Go e Java esperam argumentos diferentes das funções do CloudEvent. Esse estilo antigo de função baseada em eventos é chamado de função em segundo plano.
Veja no exemplo a seguir um arquivo de origem da função do segundo plano básico para cada ambiente de execução. Consulte Estrutura do diretório de origem para ver 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, você define e exporta uma função que processa dados de eventos. O Cloud Functions transmite à sua função do gerenciador os seguintes argumentos:
eventData
: um objeto que representa o payload de dados de evento. O formato depende do tipo de evento.context
: um objeto que contém metadados sobre o evento.callback
: uma função opcional que pode ser chamada para a conclusão do sinal. O primeiro argumento para esse callback é interpretado como indicando um erro. Transmita nenhum argumento ou um primeiro argumentonull
para sinalizar a conclusão.
O ponto de entrada da função é o nome do manipulador 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, você define uma função que lida com dados de eventos. O Cloud Functions transmite à sua função do gerenciador os seguintes argumentos:
event_data
: um dicionário que representa o payload de dados do evento. 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 gerenciador. 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 }
No Go, você define uma função exportada que processa dados de eventos. O Cloud Functions transmite à sua função do gerenciador os seguintes argumentos:
ctx
: um objetocontext.Context
que contém metadados sobre o evento. É possível recuperar os metadados usando o pacotecloud.google.com/go/functions/metadata
.e
: um objeto que representa o payload de dados de evento. O tipo, mostrado no exemplo acima comoEventDataType
, precisa ser uma estrutura correspondente ao tipo de evento que a função processa. O payload de dados do evento é desmontado na struct usandojson.Unmarshal()
.
O ponto de entrada da função é o nome do manipulador 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, use a
API Java Functions Functions Framework
para implementar uma classe de manipulador de eventos com a
interface
BackgroundFunction<T>
. O método accept()
aceita como argumentos o payload de dados de eventos
e um objeto
Context
contendo metadados sobre o evento.
O tipo de argumento de payload de dados de evento, mostrado no exemplo acima como EventDataType
, precisa corresponder ao tipo de evento que a função processa. O payload de dados do evento é desserializado em uma instância dessa
classe usando
Gson.fromJson()
.
O
ponto de entrada de função
é o nome totalmente qualificado da classe de manipulador de eventos, incluindo o nome do
pacote. Neste exemplo, o ponto de entrada é mybackgroundfunction.MyBackgroundFunction
.
Para funções em segundo plano, o payload de dados do evento é transmitido diretamente para sua função em um formato correspondente ao tipo de evento que aciona sua função. Consulte Acionadores compatíveis no Cloud Functions (1ª geração) para informações sobre acionadores compatíveis, tipos de eventos e formatos de dados de eventos associados.
Encerramento da função
O Cloud Functions considera a execução da função orientada a eventos concluída quando a
função é retornada. Se a função criar tarefas em segundo plano (como em linhas de execução, contratos futuros, objetos Promise
JavaScript, callbacks ou processos do sistema),
é necessário encerrar ou resolver essas tarefas antes de retornar da
função. As tarefas não encerradas antes do retorno da função podem não ser
concluídas e podem causar um comportamento indefinido.
Novas tentativas automáticas
As funções baseadas em eventos 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
- Saiba mais sobre os gatilhos do Cloud Functions.
- Saiba como implantar uma função do Cloud.
- Consulte Tutoriais para ver exemplos de diferentes casos de uso do Cloud Functions, incluindo exemplos de funções orientadas a eventos.