Escrever funções orientadas a eventos

No Cloud Run, você escreve uma função orientada a eventos quando quer que ela seja acionada diretamente em resposta a eventos no seu projeto do Google Cloud, como mensagens em um tópico do Pub/Sub ou alterações em um bucket do Cloud Storage.

Implementar funções de manipuladores orientados a eventos

As funções baseadas em eventos 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 using 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 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
}

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 using 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.

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

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 código de exemplo 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 using $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 orientadas a eventos, 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 a função. Consulte Acionadores de função para 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.

Encerramento da função

O Cloud Run 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 linhas de execução, futuros, objetos de promessas do 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.

A seguir