Gravar funções do Cloud Run

Esta página descreve como escrever funções HTTP e orientadas a eventos do Cloud Run com o Functions Framework.

Visão geral do Functions Framework

Ao escrever o código-fonte das funções, use o Functions Framework, uma biblioteca de código aberto para escrever funções do Cloud Run. Com o Functions Framework, é possível escrever funções leves que são executadas no Cloud Run e em outros ambientes, incluindo a máquina de desenvolvimento local e ambientes baseados em Knative.

Com o Functions Framework, é possível:

  • Invocar uma função do Cloud Run em resposta a uma solicitação.
  • Cancele automaticamente o marshal de eventos em conformidade com a especificação do CloudEvents, um padrão do setor para descrever dados de eventos de maneira comum.
  • Inicie um servidor de desenvolvimento local para testes.

O Functions Framework fornece uma interface para criar serviços modulares. Para usar o Functions Framework no código-fonte, especifique o seguinte:

Ponto de entrada da função

O código-fonte precisa definir um ponto de entrada de função, que é o código executado quando o Cloud Run invoca sua função. Você especifica esse ponto de entrada ao implantar a função.

A definição do ponto de entrada depende do ambiente de execução da linguagem usada. Algumas linguagens usam uma função como ponto de entrada, enquanto outras usam uma classe.

Tipo de assinatura

Ao escrever o código-fonte de uma função com o Functions Framework, você precisa especificar um dos dois tipos de assinatura:

  • Funções HTTP: registra uma função de processador HTTP. Use uma função HTTP quando ela precisar de um endpoint de URL e responder a solicitações HTTP, como para webhooks.
  • Funções baseadas em eventos, também conhecidas como funções do CloudEvents: registra uma função de gerenciador do CloudEvents. Use uma função baseada em eventos quando ela for acionada diretamente em resposta a eventos no seu projeto Google Cloud , como mensagens em um tópico do Pub/Sub ou alterações em um bucket do Cloud Storage.

Estrutura do diretório de origem

O Functions Framework é compatível com várias linguagens de programação. O ambiente de execução da linguagem que você escolhe e o tipo de função que você quer escrever determinam como estruturar seu código e implementar sua função.

Para que o Cloud Run localize a definição da função, cada ambiente de execução da linguagem tem requisitos para estruturar o código-fonte.

Node.js

A estrutura de diretórios básica para funções Node.js é a seguinte:

.
├── index.js
└── package.json

Por padrão, o Cloud Run tenta carregar o código-fonte de um arquivo chamado index.js na raiz do diretório da função. Para especificar um arquivo principal diferente, use o campo main no seu arquivo package.json.

Seu arquivo package.json também precisa incluir o Functions Framework para Node.js como uma dependência:

{
  "main": "index.js",
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  },
  "type": "module"
}

O código no arquivo principal precisa definir o ponto de entrada de função e importar outros códigos e módulos do Node.js. O arquivo principal também pode definir vários pontos de entrada de função que podem ser implantados separadamente.

Consulte a visão geral do ambiente de execução do Node.js e o Functions Framework para Node.js para mais detalhes.

Python

A estrutura de diretórios básica para funções Python é a seguinte:

.
├── main.py
└── requirements.txt

O Cloud Run carrega o código-fonte de um arquivo chamado main.py na raiz do diretório de funções. O arquivo principal precisa ser nomeado como main.py.

O arquivo requirements.txt precisa incluir o Functions Framework para Python como uma dependência:

functions-framework==3.*

O código no arquivo main.py precisa definir seu ponto de entrada de função e pode importar outras dependências de código e externas normalmente. O arquivo main.py também pode definir vários pontos de entrada de função que podem ser implantados separadamente.

Consulte a Visão geral do ambiente de execução do Python e o Functions Framework para Python para mais detalhes.

Go

A estrutura de diretórios básica para funções Go é a seguinte:

.
├── myfunction.go
└── go.mod

Sua função deve estar em um pacote Go na raiz do projeto. O pacote e os arquivos de origem dele podem ter qualquer nome, exceto se a função não puder estar em package main. Se você precisar de um pacote main, por exemplo, para testes locais, crie um em um subdiretório:

.
├── myfunction.go
├── go.mod
└── cmd/
  └── main.go

Seu arquivo go.mod precisa incluir o Functions Framework para Go como uma dependência:

module example.com/my-module

require (
  github.com/GoogleCloudPlatform/functions-framework-go v1.5.2
)

O código no pacote raiz precisa definir o ponto de entrada de função e importar outros códigos de subpacotes e dependências normalmente. Seu pacote também pode definir vários pontos de entrada de função que podem ser implantados separadamente.

Consulte a Visão geral do ambiente de execução do Go e o Functions Framework para Go para mais detalhes.

Java

A estrutura de diretórios básica para funções Java é a seguinte:

.
├── pom.xml
└── src/
  └── main/
      └── java/
          └── MyFunction.java

Os arquivos de origem Java precisam estar no diretório src/main/java/ e podem ter qualquer nome. Se os arquivos de origem declararem um pacote, adicione um diretório extra em src/main/java com o nome do pacote:

.
├── pom.xml
└── src/
  └── main/
      └── java/
          └── mypackage/
              └── MyFunction.java

Recomendamos colocar os testes associados em um subdiretório src/test/java/.

O arquivo pom.xml precisa incluir o Functions Framework para Java como dependência:

...
    <dependency>
      <groupId>com.google.cloud.functions</groupId>
      <artifactId>functions-framework-api</artifactId>
      <version>1.0.4</version>
    </dependency>
...

O código nos arquivos de origem precisa definir o ponto de entrada de função e importar outros códigos e dependências externas normalmente. Seus arquivos de origem também podem definir vários pontos de entrada de função que podem ser implantados separadamente.

Consulte a visão geral do ambiente de execução do Java e o Functions Framework para Java para mais detalhes.

.NET

A estrutura de diretórios básica para funções .NET é a seguinte:

.
├── MyFunction.cs
└── MyProject.csproj

Você pode estruturar seus projetos como faria com qualquer outro código-fonte .NET. Seus arquivos de origem podem ter qualquer nome.

O arquivo do projeto precisa incluir o Functions Framework para .NET como uma dependência:

...
    <PackageReference Include="Google.Cloud.Functions.Hosting" Version="1.0.0" />
...

O código nos arquivos de origem precisa definir o ponto de entrada de função e importar outros códigos e dependências externas normalmente. Seus arquivos de origem também podem definir vários pontos de entrada de função que podem ser implantados separadamente.

Consulte a visão geral do ambiente de execução do.NET e o Functions Framework para .NET para mais detalhes.

Ruby

A estrutura de diretórios básica para funções do Ruby é a seguinte:

.
├── app.rb
├── Gemfile
└── Gemfile.lock

O Cloud Run carrega o código-fonte de um arquivo chamado app.rb na raiz do diretório de funções. O arquivo principal precisa ter o nome app.rb.

O arquivo Gemfile precisa incluir o Functions Framework para Ruby como uma dependência:

source "https://rubygems.org"
gem "functions_framework", "~> 1.0"

O código no arquivo app.rb precisa definir seu ponto de entrada de função e pode importar outras dependências de código e externas normalmente. O arquivo app.rb também pode definir vários pontos de entrada de função que podem ser implantados separadamente.

Consulte a visão geral do ambiente de execução do Ruby e o Functions Framework para Ruby para mais detalhes.

PHP

A estrutura de diretórios básica para funções PHP é a seguinte:

.
├── index.php
└── composer.json

O Cloud Run carrega o código-fonte de um arquivo chamado index.php na raiz do diretório de funções. O arquivo principal precisa ser nomeado como index.php.

O arquivo composer.json precisa incluir o Functions Framework para PHP como uma dependência:

{
  "require": {
    "google/cloud-functions-framework": "^1.1"
  }
}

O código no arquivo index.php precisa definir seu ponto de entrada de função e pode importar outras dependências de código e externas normalmente. O arquivo index.php também pode definir vários pontos de entrada de função que podem ser implantados separadamente.

Consulte a visão geral do ambiente de execução do PHP e o Functions Framework para PHP para mais detalhes.

Se você agrupar várias funções em um único projeto, esteja ciente de que cada função pode acabar compartilhando o mesmo conjunto de dependências. No entanto, algumas das funções podem não precisar de todas as dependências.

Sempre que possível, recomendamos dividir grandes bases de código multifuncionais e colocar cada função no próprio diretório de nível superior, conforme mostrado nos exemplos anteriores, com os próprios arquivos de configuração de origem e projeto. Essa abordagem minimiza o número de dependências necessárias para uma função específica, o que reduz a quantidade de memória necessária para a função.

Escrever funções HTTP

Escreva uma função HTTP quando quiser invocar uma função por meio de uma solicitação HTTP(S). Para permitir a semântica HTTP, use o Function Framework e especifique a assinatura da função HTTP para aceitar argumentos específicos de HTTP.

O exemplo a seguir mostra um arquivo de origem da função HTTP básico para cada ambiente de execução. Para um exemplo completo, consulte Implantar uma função do Cloud Run usando a Google Cloud CLI. Para mais informações sobre onde localizar o código-fonte, consulte Estrutura do diretório de origem.

Node.js

Módulo ES 

  import { http } from '@google-cloud/functions-framework';
  http('myHttpFunction', (req, res) => {
    // Your code here

    // Send an HTTP response
    res.send('OK');
  });

Adicione as seguintes dependências, incluindo "type": "module" no arquivo package.json:

  {
    "dependencies": {
      "@google-cloud/functions-framework": "^3.0.0"
    },
    "type": "module"
  }

Módulo CommonJS 

  const functions = require('@google-cloud/functions-framework');

  // Register an HTTP function with the Functions Framework
  functions.http('myHttpFunction', (req, res) => {
    // Your code here

    // Send an HTTP response
    res.send('OK');
  });

Adicione as seguintes dependências ao arquivo package.json:

  {
    "dependencies": {
      "@google-cloud/functions-framework": "^3.0.0"
    }
  }

No Node.js, você registra uma função de gerenciador HTTP com o Framework do Functions para Node.js. A função de gerenciador HTTP precisa ser uma função de middleware Express que aceita os argumentos de solicitação e resposta e envia uma resposta HTTP.

O Cloud Run analisa automaticamente o corpo da solicitação com base no cabeçalho Content-Type da solicitação usando body-parser. Assim, você pode acessar os objetos req.body e req.rawBody no seu gerenciador HTTP.

O ponto de entrada de função é o nome com que o gerenciador está registrado no Functions Framework. Neste exemplo, o ponto de entrada é myHttpFunction.

Python

import functions_framework

# Register an HTTP function with the Functions Framework
@functions_framework.http
def my_http_function(request):
  # Your code here

  # Return an HTTP response
  return 'OK'

Em Python, você registra uma função de gerenciador HTTP com o Framework de funções para Python. A função de gerenciador HTTP precisa aceitar um objeto de solicitação do Flask como argumento e retornar um valor que o Flask pode converter em um objeto de resposta HTTP.

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

Go

package myhttpfunction

import (
    "fmt"
    "net/http"

    "github.com/GoogleCloudPlatform/functions-framework-go/functions"
)

func init() {
    // Register an HTTP function with the Functions Framework
    functions.HTTP("MyHTTPFunction", myHTTPFunction)
}

// Function myHTTPFunction is an HTTP handler
func myHTTPFunction(w http.ResponseWriter, r *http.Request) {
    // Your code here

    // Send an HTTP response
    fmt.Fprintln(w, "OK")
}

Em Go, registre uma função de gerenciador HTTP com o Framework de funções para Go na sua função init(). A função de gerenciador HTTP precisa usar a interface http.HandlerFunc padrão para enviar uma resposta HTTP.

O ponto de entrada de função é o nome com que o gerenciador está registrado no Functions Framework. Neste exemplo, o ponto de entrada é MyHTTPFunction.

Sua função de gerenciador HTTP precisa implementar a interface http.HandlerFunc padrão. Ele aceita uma interface http.ResponseWriter que sua função usa para criar uma resposta à solicitação e um ponteiro para um struct http.Request contendo os detalhes da solicitação HTTP recebida.

Java

package myhttpfunction;

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;

// Define a class that implements the HttpFunction interface
public class MyHttpFunction implements HttpFunction {
  // Implement the service() method to handle HTTP requests
  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    // Your code here

    // Send an HTTP response
    response.getWriter().write("OK");
  }
}

Em Java, use a API Functions Framework para Java para implementar uma classe de gerenciador HTTP com a interface HttpFunction. O método service() precisa enviar uma resposta HTTP.

O ponto de entrada de função é o nome totalmente qualificado da classe de gerenciador HTTP, incluindo o nome do pacote. Neste exemplo, o ponto de entrada é myhttpfunction.MyHttpFunction.

O método service recebe um objeto HttpRequest que descreve a solicitação HTTP de entrada e um HttpResponse que sua função preenche com uma mensagem de resposta.

.NET

using Google.Cloud.Functions.Framework;
using Microsoft.AspNetCore.Http;
using System.Threading.Tasks;

namespace MyProject
{
    // Define a class that implements the IHttpFunction interface
    public class MyHttpFunction : IHttpFunction
    {
        // Implement the HandleAsync() method to handle HTTP requests
        public async Task HandleAsync(HttpContext context)
        {
            // Your code here

            // Send an HTTP response
            await context.Response.WriteAsync("OK");
        }
    }
}

Nos ambientes de execução do .NET, use o Functions Framework para .NET para implementar uma classe de gerenciador HTTP com a interface IHttpFunction. O método HandleAsync() aceita um objeto HttpContext padrão do ASP.NET como argumento e precisa enviar uma resposta HTTP.

O ponto de entrada de função é o nome totalmente qualificado da classe de gerenciador HTTP, incluindo o namespace. Neste exemplo, o ponto de entrada é MyProject.MyHttpFunction.

Ruby

require "functions_framework"

# Register an HTTP function with the Functions Framework
FunctionsFramework.http "my_http_function" do |request|
  # Your code here

  # Return an HTTP response
  "OK"
end

No Ruby, você registra uma função de gerenciador HTTP com o frameworks Functions para Ruby. A função de gerenciador HTTP precisa aceitar um objeto Solicitação de rack como um argumento e retornar um valor que pode ser usado como uma resposta HTTP.

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

PHP

<?php

use Google\CloudFunctions\FunctionsFramework;
use Psr\Http\Message\ServerRequestInterface;

// Register an HTTP function with the Functions Framework
FunctionsFramework::http('myHttpFunction', 'myHttpHandler');

// Define your HTTP handler
function myHttpHandler(ServerRequestInterface $request): string
{
    // Your code here

    // Return an HTTP response
    return 'OK';
}

Em PHP, você registra uma função de gerenciador HTTP com o Framework de funções para PHP. A função de gerenciador HTTP precisa aceitar um argumento que implemente a interface ServerRequestInterface do PSR-7 e retornar uma resposta HTTP como uma string ou um objeto que implemente a interface ResponseInterface do PSR-7.

O ponto de entrada de função é o nome com que o gerenciador está registrado no Functions Framework. Neste exemplo, o ponto de entrada é myHttpFunction.

Solicitações e respostas HTTP

Ao registrar uma função de gerenciador HTTP com o Functions Framework, seu gerenciador HTTP pode inspecionar o método da solicitação e executar diferentes ações com base no método.

Quando você configura um provedor de eventos para enviar solicitações HTTP à sua função do Cloud Run, ela envia uma resposta HTTP. Se a função criar tarefas em segundo plano (como com linhas de execução, contratos futuros, objetos de promessa do JavaScript, callbacks ou processos do sistema), é necessário encerrar ou resolver essas tarefas antes de enviar uma resposta HTTP. Qualquer tarefa não encerrada antes do envio da resposta HTTP pode não ser concluída e pode causar um comportamento indefinido.

Processar CORS

O Compartilhamento de recursos entre origens (CORS) é uma forma de permitir que aplicativos executados em um domínio acessem recursos de outro domínio. Por exemplo, talvez seja necessário permitir que o domínio faça solicitações ao domínio do Cloud Run functions para acessar a função.

Para permitir solicitações de origem cruzada para sua função, defina o cabeçalho Access-Control-Allow-Origin conforme apropriado na sua resposta HTTP. Para solicitações de origem cruzada simuladas, é necessário responder à solicitação OPTIONS de simulação com um código de resposta 204 e cabeçalhos adicionais.

Node.js

const functions = require('@google-cloud/functions-framework');

/**
 * HTTP function that supports CORS requests.
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
functions.http('corsEnabledFunction', (req, res) => {
  // Set CORS headers for preflight requests
  // Allows GETs from any origin with the Content-Type header
  // and caches preflight response for 3600s

  res.set('Access-Control-Allow-Origin', '*');

  if (req.method === 'OPTIONS') {
    // Send response to OPTIONS requests
    res.set('Access-Control-Allow-Methods', 'GET');
    res.set('Access-Control-Allow-Headers', 'Content-Type');
    res.set('Access-Control-Max-Age', '3600');
    res.status(204).send('');
  } else {
    res.send('Hello World!');
  }
});

Python

import functions_framework

@functions_framework.http
def cors_enabled_function(request):
    # For more information about CORS and CORS preflight requests, see:
    # https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request

    # Set CORS headers for the preflight request
    if request.method == "OPTIONS":
        # Allows GET requests from any origin with the Content-Type
        # header and caches preflight response for an 3600s
        headers = {
            "Access-Control-Allow-Origin": "*",
            "Access-Control-Allow-Methods": "GET",
            "Access-Control-Allow-Headers": "Content-Type",
            "Access-Control-Max-Age": "3600",
        }

        return ("", 204, headers)

    # Set CORS headers for the main request
    headers = {"Access-Control-Allow-Origin": "*"}

    return ("Hello World!", 200, headers)

Go


// Package http provides a set of HTTP Cloud Functions samples.
package http

import (
	"fmt"
	"net/http"

	"github.com/GoogleCloudPlatform/functions-framework-go/functions"
)

// CORSEnabledFunction is an example of setting CORS headers.
// For more information about CORS and CORS preflight requests, see
// https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request.
func CORSEnabledFunction(w http.ResponseWriter, r *http.Request) {
	// Set CORS headers for the preflight request
	if r.Method == http.MethodOptions {
		w.Header().Set("Access-Control-Allow-Origin", "*")
		w.Header().Set("Access-Control-Allow-Methods", "POST")
		w.Header().Set("Access-Control-Allow-Headers", "Content-Type")
		w.Header().Set("Access-Control-Max-Age", "3600")
		w.WriteHeader(http.StatusNoContent)
		return
	}
	// Set CORS headers for the main request.
	w.Header().Set("Access-Control-Allow-Origin", "*")
	fmt.Fprint(w, "Hello, World!")
}

func init() {
	functions.HTTP("CORSEnabledFunction", CORSEnabledFunction)
}

Java


import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import java.io.BufferedWriter;
import java.io.IOException;
import java.net.HttpURLConnection;

public class CorsEnabled implements HttpFunction {
  // corsEnabled is an example of setting CORS headers.
  // For more information about CORS and CORS preflight requests, see
  // https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request.
  @Override
  public void service(HttpRequest request, HttpResponse response)
      throws IOException {
    // Set CORS headers
    //   Allows GETs from any origin with the Content-Type
    //   header and caches preflight response for 3600s
    response.appendHeader("Access-Control-Allow-Origin", "*");

    if ("OPTIONS".equals(request.getMethod())) {
      response.appendHeader("Access-Control-Allow-Methods", "GET");
      response.appendHeader("Access-Control-Allow-Headers", "Content-Type");
      response.appendHeader("Access-Control-Max-Age", "3600");
      response.setStatusCode(HttpURLConnection.HTTP_NO_CONTENT);
      return;
    }

    // Handle the main request.
    BufferedWriter writer = response.getWriter();
    writer.write("CORS headers set successfully!");
  }
}

.NET

using Google.Cloud.Functions.Framework;
using Microsoft.AspNetCore.Http;
using System.Net;
using System.Threading.Tasks;

namespace Cors;

// For more information about CORS and CORS preflight requests, see
// https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request.
public class Function : IHttpFunction
{
    public async Task HandleAsync(HttpContext context)
    {
        HttpRequest request = context.Request;
        HttpResponse response = context.Response;

        // Set CORS headers
        //   Allows GETs from any origin with the Content-Type
        //   header and caches preflight response for 3600s

        response.Headers.Append("Access-Control-Allow-Origin", "*");
        if (HttpMethods.IsOptions(request.Method))
        {
            response.Headers.Append("Access-Control-Allow-Methods", "GET");
            response.Headers.Append("Access-Control-Allow-Headers", "Content-Type");
            response.Headers.Append("Access-Control-Max-Age", "3600");
            response.StatusCode = (int) HttpStatusCode.NoContent;
            return;
        }

        await response.WriteAsync("CORS headers set successfully!", context.RequestAborted);
    }
}

Ruby

FunctionsFramework.http "cors_enabled_function" do |request|
  # For more information about CORS and CORS preflight requests, see
  # https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request
  # for more information.

  # Set CORS headers for the preflight request
  if request.options?
    # Allows GET requests from any origin with the Content-Type
    # header and caches preflight response for an 3600s
    headers = {
      "Access-Control-Allow-Origin"  => "*",
      "Access-Control-Allow-Methods" => "GET",
      "Access-Control-Allow-Headers" => "Content-Type",
      "Access-Control-Max-Age"       => "3600"
    }
    [204, headers, []]
  else
    # Set CORS headers for the main request
    headers = {
      "Access-Control-Allow-Origin" => "*"
    }

    [200, headers, ["Hello World!"]]
  end
end

PHP


use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use GuzzleHttp\Psr7\Response;

function corsEnabledFunction(ServerRequestInterface $request): ResponseInterface
{
    // Set CORS headers for preflight requests
    // Allows GETs from any origin with the Content-Type header
    // and caches preflight response for 3600s
    $headers = ['Access-Control-Allow-Origin' => '*'];

    if ($request->getMethod() === 'OPTIONS') {
        // Send response to OPTIONS requests
        $headers = array_merge($headers, [
            'Access-Control-Allow-Methods' => 'GET',
            'Access-Control-Allow-Headers' => 'Content-Type',
            'Access-Control-Max-Age' => '3600'
        ]);
        return new Response(204, $headers, '');
    } else {
        return new Response(200, $headers, 'Hello World!');
    }
}

Se o CORS não estiver configurado corretamente, poderão aparecer erros como os seguintes:

XMLHttpRequest cannot load https://YOUR_FUNCTION_URL.
No 'Access-Control-Allow-Origin' header is present on the requested resource.
Origin 'https://YOUR_DOMAIN' is therefore not allowed access.

Limitações do CORS

Para solicitações de origem cruzada de simulação, as solicitações OPTIONS de simulação são enviadas sem um cabeçalho de autorização. Portanto, elas serão rejeitadas em todas as funções HTTP que exigem autenticação. Como há falha nas solicitações simuladas, as principais solicitações também vão falhar. Para contornar essa limitação, use uma das seguintes opções:

Escrever funções orientadas a eventos

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

As funções orientadas a 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.

Confira no exemplo a seguir um arquivo de origem da função orientada a eventos para cada ambiente de execução. Consulte Estrutura do diretório de origem para saber onde localizar o código-fonte.

Node.js

Módulo ES 

  import { cloudEvent } from "@google-cloud/functions-framework";
  cloudEvent('myCloudEventFunction', cloudEvent => {
    // Your code here
    // Access the CloudEvent data payload using cloudEvent.data
  });

Adicione as seguintes dependências, incluindo "type": "module" no arquivo package.json:

  {
    "dependencies": {
      "@google-cloud/functions-framework": "^3.0.0"
    },
    "type": "module"
  }

Módulo CommonJS 

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

Adicione as seguintes dependências ao arquivo package.json:

  {
    "dependencies": {
      "@google-cloud/functions-framework": "^3.0.0"
    }
  }

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 exemplo de código 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 por 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 sua 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 em linhas de execução, contratos futuros, objetos de promessa 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