Dicas e truques

Neste documento, descrevemos as práticas recomendadas para projetar, implementar, testar e implantar o Cloud Run functions.

Observação: várias das recomendações neste documento baseiam-se no que é conhecido como inicialização a frio. As funções não têm estado, e o ambiente de execução normalmente é inicializado do zero, o que é chamado de inicialização a frio. Inicializações a frio podem levar um tempo significativo para serem concluídas. Recomendamos evitar inicializações a frio desnecessárias e agilizar o processamento delas o máximo possível (por exemplo, evitando dependências desnecessárias).

Correção

Nesta seção, você verá as práticas recomendadas gerais para projetar e implementar o Cloud Run functions.

Escreva funções idempotentes

As funções devem produzir o mesmo resultado, mesmo que sejam chamadas várias vezes. Isso permite que você tente executar uma invocação novamente caso a anterior falhe no seu código. Para mais informações, consulte Como repetir funções orientadas a eventos.

Confirme se as funções HTTP enviam uma resposta HTTP

Se a função for acionada por HTTP, lembre-se de enviar uma resposta HTTP, como mostrado abaixo. Não fazer isso pode resultar na execução da função até o tempo limite. Se isso ocorrer, você será cobrado por todo o tempo limite. Os tempos limite também podem causar um comportamento imprevisível ou inicializações a frio em invocações subsequentes, resultando em um comportamento imprevisível ou latência adicional.

Node.js

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

/**
 * Responds to an HTTP request using data from the request body parsed according
 * to the "content-type" header.
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
functions.http('helloHttp', (req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});

Python

import functions_framework


from markupsafe import escape

@functions_framework.http
def hello_http(request):
    """HTTP Cloud Function.
    Args:
        request (flask.Request): The request object.
        <https://flask.palletsprojects.com/en/1.1.x/api/#incoming-request-data>
    Returns:
        The response text, or any set of values that can be turned into a
        Response object using `make_response`
        <https://flask.palletsprojects.com/en/1.1.x/api/#flask.make_response>.
    """
    request_json = request.get_json(silent=True)
    request_args = request.args

    if request_json and "name" in request_json:
        name = request_json["name"]
    elif request_args and "name" in request_args:
        name = request_args["name"]
    else:
        name = "World"
    return f"Hello {escape(name)}!"

Go

// Package helloworld provides a set of Cloud Functions samples.
package helloworld

import (
	"encoding/json"
	"fmt"
	"html"
	"net/http"

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

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

// HelloHTTP is an HTTP Cloud Function with a request parameter.
func HelloHTTP(w http.ResponseWriter, r *http.Request) {
	var d struct {
		Name string `json:"name"`
	}
	if err := json.NewDecoder(r.Body).Decode(&d); err != nil {
		fmt.Fprint(w, "Hello, World!")
		return
	}
	if d.Name == "" {
		fmt.Fprint(w, "Hello, World!")
		return
	}
	fmt.Fprintf(w, "Hello, %s!", html.EscapeString(d.Name))
}

Java

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import com.google.gson.JsonParseException;
import java.io.IOException;
import java.io.PrintWriter;
import java.util.logging.Logger;

public class HelloHttp implements HttpFunction {
  private static final Logger logger = Logger.getLogger(HelloHttp.class.getName());

  private static final Gson gson = new Gson();

  @Override
  public void service(HttpRequest request, HttpResponse response)
      throws IOException {
    // Check URL parameters for "name" field
    // "world" is the default value
    String name = request.getFirstQueryParameter("name").orElse("world");

    // Parse JSON request and check for "name" field
    try {
      JsonElement requestParsed = gson.fromJson(request.getReader(), JsonElement.class);
      JsonObject requestJson = null;

      if (requestParsed != null && requestParsed.isJsonObject()) {
        requestJson = requestParsed.getAsJsonObject();
      }

      if (requestJson != null && requestJson.has("name")) {
        name = requestJson.get("name").getAsString();
      }
    } catch (JsonParseException e) {
      logger.severe("Error parsing JSON: " + e.getMessage());
    }

    var writer = new PrintWriter(response.getWriter());
    writer.printf("Hello %s!", name);
  }
}

C#

using Google.Cloud.Functions.Framework;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using System.IO;
using System.Text.Json;
using System.Threading.Tasks;

namespace HelloHttp;

public class Function : IHttpFunction
{
    private readonly ILogger _logger;

    public Function(ILogger<Function> logger) =>
        _logger = logger;

    public async Task HandleAsync(HttpContext context)
    {
        HttpRequest request = context.Request;
        // Check URL parameters for "name" field
        // "world" is the default value
        string name = ((string) request.Query["name"]) ?? "world";

        // If there's a body, parse it as JSON and check for "name" field.
        using TextReader reader = new StreamReader(request.Body);
        string text = await reader.ReadToEndAsync();
        if (text.Length > 0)
        {
            try
            {
                JsonElement json = JsonSerializer.Deserialize<JsonElement>(text);
                if (json.TryGetProperty("name", out JsonElement nameElement) &&
                    nameElement.ValueKind == JsonValueKind.String)
                {
                    name = nameElement.GetString();
                }
            }
            catch (JsonException parseException)
            {
                _logger.LogError(parseException, "Error parsing JSON request");
            }
        }

        await context.Response.WriteAsync($"Hello {name}!", context.RequestAborted);
    }
}

Ruby

require "functions_framework"
require "cgi"
require "json"

FunctionsFramework.http "hello_http" do |request|
  # The request parameter is a Rack::Request object.
  # See https://www.rubydoc.info/gems/rack/Rack/Request
  name = request.params["name"] ||
         (request.body.rewind && JSON.parse(request.body.read)["name"] rescue nil) ||
         "World"
  # Return the response body as a string.
  # You can also return a Rack::Response object, a Rack response array, or
  # a hash which will be JSON-encoded into a response.
  "Hello #{CGI.escape_html name}!"
end

PHP

<?php

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

// Register the function with Functions Framework.
// This enables omitting the `FUNCTIONS_SIGNATURE_TYPE=http` environment
// variable when deploying. The `FUNCTION_TARGET` environment variable should
// match the first parameter.
FunctionsFramework::http('helloHttp', 'helloHttp');

function helloHttp(ServerRequestInterface $request): string
{
    $name = 'World';
    $body = $request->getBody()->getContents();
    if (!empty($body)) {
        $json = json_decode($body, true);
        if (json_last_error() != JSON_ERROR_NONE) {
            throw new RuntimeException(sprintf(
                'Could not parse body: %s',
                json_last_error_msg()
            ));
        }
        $name = $json['name'] ?? $name;
    }
    $queryString = $request->getQueryParams();
    $name = $queryString['name'] ?? $name;

    return sprintf('Hello, %s!', htmlspecialchars($name));
}

Não inicie atividades em segundo plano

Atividade em segundo plano é tudo que ocorre depois que a função é encerrada. A invocação de uma função termina quando a função retorna ou sinaliza a conclusão, por exemplo, chamando o argumento callback nas funções orientadas por eventos do Node.js. Qualquer código executado após a finalização normal não pode acessar a CPU e não progredirá.

Observação: se uma função orientada por eventos do Node.js retornar uma Promessa, o Cloud Run functions garante que essa Promessa seja resolvida antes da finalização.

Além disso, quando uma invocação subsequente é executada no mesmo ambiente, a atividade em segundo plano é retomada, interferindo na nova invocação. Isso pode levar a um comportamento inesperado e erros difíceis de diagnosticar. O acesso à rede depois que uma função é concluída normalmente causa a redefinição das conexões (código do erro ECONNRESET).

Ela normalmente pode ser detectada em registros de invocações individuais, encontrando tudo o que será registrado depois da linha que informa sobre o término da invocação. Às vezes, a atividade em segundo plano pode ser aprofundada no código, especialmente quando operações assíncronas, como callbacks ou timers, estão presentes. Revise o código para verificar se todas as operações assíncronas foram concluídas antes de você finalizar a função.

Sempre exclua arquivos temporários

O armazenamento de disco local no diretório temporário é um sistema de arquivos na memória. Os arquivos que você grava consomem memória disponível para sua função e, às vezes, permanecem entre as invocações. A não exclusão deles pode resultar em um erro de memória insuficiente e uma subsequente inicialização a frio.

Veja a memória usada por uma função individual selecionando-a na lista de funções do console do Google Cloud e escolhendo o gráfico Uso da memória.

Se você precisar de acesso ao armazenamento de longo prazo, use as montagens de volume do Cloud Run com o Cloud Storage ou volumes do NFS.

É possível reduzir os requisitos de memória ao processar arquivos maiores usando pipelines. Por exemplo, processe um arquivo no Cloud Storage criando um stream de leitura, transmitindo-o por um processo baseado em stream e gravando o stream de saída diretamente no Cloud Storage.

Functions Framework

Para garantir que as mesmas dependências sejam instaladas de maneira consistente em diferentes ambientes, recomendamos que você inclua a biblioteca do Functions Framework no gerenciador de pacotes e fixe a dependência a uma versão específica do Functions Framework.

Para isso, inclua a versão de sua preferência no arquivo de bloqueio relevante (por exemplo, package-lock.json para Node.js ou requirements.txt para Python).

Se o Functions Framework não estiver listado explicitamente como uma dependência, ele será adicionado automaticamente durante o processo de build usando a versão mais recente disponível.

Ferramentas

Nesta seção, você verá diretrizes sobre como usar ferramentas para implementar, testar e interagir com o Google Run functions.

Desenvolvimento local

A implantação de funções demora um pouco, então geralmente é mais rápido testar o código da sua função localmente.

Os desenvolvedores podem usar o Functions Framework para fazer testes locais.

Error Reporting

Em linguagens que usam processamento de exceção, não crie exceções não capturadas, pois elas forçam inicialização a frio em futuras invocações. Consulte o guia do Error Reporting para ver informações sobre como relatar erros corretamente.

Não sair manualmente

Sair manualmente pode causar um comportamento inesperado. Use os seguintes idiomas específicos de linguagem:

Node.js

Não use process.exit(). As funções HTTP precisam enviar uma resposta com res.status(200).send(message), e as funções orientadas a eventos sairão quando elas retornarem, implicitamente ou explicitamente.

Python

Não use sys.exit(). As funções HTTP retornarão uma resposta como uma string de maneira explícita, e as funções orientadas a eventos sairão assim que retornarem um valor, implicitamente ou explicitamente.

Go

Não use os.Exit(). As funções HTTP retornarão uma resposta como uma string de maneira explícita, e as funções orientadas a eventos sairão assim que retornarem um valor, implicitamente ou explicitamente.

Java

Não use System.exit(). As funções HTTP precisam enviar uma resposta com response.getWriter().write(message), e as funções orientadas a eventos sairão quando elas retornarem, implicitamente ou explicitamente.

C#

Não use System.Environment.Exit(). As funções HTTP precisam enviar uma resposta com context.Response.WriteAsync(message), e as funções orientadas a eventos sairão quando elas retornarem, implicitamente ou explicitamente.

Ruby

Não use exit() ou abort(). As funções HTTP retornarão uma resposta como uma string de maneira explícita, e as funções orientadas a eventos sairão assim que retornarem um valor, implicitamente ou explicitamente.

PHP

Não use exit() ou die(). As funções HTTP retornarão uma resposta como uma string de maneira explícita, e as funções orientadas a eventos sairão assim que retornarem um valor, implicitamente ou explicitamente.

Use SendGrid para enviar e-mails

O Cloud Run functions não permite conexões de saída na porta 25, então não é possível estabelecer conexões não seguras com um servidor SMTP. A maneira recomendada de enviar e-mails é usar um serviço de terceiros, como o SendGrid. Confira outras opções para enviar e-mails no tutorial Como enviar e-mails a partir de uma instância do Google Compute Engine.

Desempenho

Nesta seção, você verá as práticas recomendadas para otimizar o desempenho.

Evite baixa simultaneidade

Como as inicializações a frio são caras, a capacidade de reutilizar instâncias iniciadas recentemente durante um pico é uma ótima otimização para lidar com a carga. Limitar a contemporaneidade limita como as instâncias atuais podem ser aproveitadas, o que gera mais inicializações a frio.

O aumento da simultaneidade ajuda a adiar várias solicitações por instância, facilitando o processamento de picos de carga.

Observação: à medida que a eficiência aumenta e o número necessário é reduzido, as instâncias de função individuais podem usar mais memória para armazenar solicitações e exigir mais CPU para processá-las.

Observação: as funções de 1ª geração têm simultaneidade limitada a 1. Recomendamos que você migre para as funções do Cloud Run.

Use dependências com sabedoria

Como as funções não têm estado, o ambiente de execução normalmente é inicializado do zero, o que é chamado de inicialização a frio. Quando ocorre uma inicialização a frio, o contexto global da função é avaliado.

Se suas funções importam módulos, o tempo de carregamento deles pode ser adicionado à latência de invocação durante uma inicialização a frio. É possível reduzir essa latência, bem como o tempo necessário para implantar sua função, carregando as dependências necessárias e não carregando as dependências que sua função não utiliza.

Use variáveis globais para reutilizar objetos em futuras invocações

Não há garantia de que o estado de um Cloud Run function seja preservado para futuras invocações. No entanto, essas funções reciclam frequentemente o ambiente de execução de uma invocação anterior. Se você declarar uma variável no escopo global, o valor dela pode ser reutilizado em invocações subsequentes sem necessidade de recálculo.

Dessa forma, é possível armazenar em cache os objetos cuja recriação em cada invocação de função pode ser cara. Mover esses objetos do corpo da função para o escopo global pode resultar em melhorias significativas de desempenho. No exemplo a seguir, um objeto pesado é criado apenas uma vez por instância de função e é compartilhado em todas as invocações da função que alcançam a instância determinada:

Node.js

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

// TODO(developer): Define your own computations
const {lightComputation, heavyComputation} = require('./computations');

// Global (instance-wide) scope
// This computation runs once (at instance cold-start)
const instanceVar = heavyComputation();

/**
 * HTTP function that declares a variable.
 *
 * @param {Object} req request context.
 * @param {Object} res response context.
 */
functions.http('scopeDemo', (req, res) => {
  // Per-function scope
  // This computation runs every time this function is called
  const functionVar = lightComputation();

  res.send(`Per instance: ${instanceVar}, per function: ${functionVar}`);
});

Python

import time

import functions_framework


# Placeholder
def heavy_computation():
    return time.time()


# Placeholder
def light_computation():
    return time.time()


# Global (instance-wide) scope
# This computation runs at instance cold-start
instance_var = heavy_computation()


@functions_framework.http
def scope_demo(request):
    """
    HTTP Cloud Function that declares a variable.
    Args:
        request (flask.Request): The request object.
        <http://flask.pocoo.org/docs/1.0/api/#flask.Request>
    Returns:
        The response text, or any set of values that can be turned into a
        Response object using `make_response`
        <http://flask.pocoo.org/docs/1.0/api/#flask.Flask.make_response>.
    """

    # Per-function scope
    # This computation runs every time this function is called
    function_var = light_computation()
    return f"Instance: {instance_var}; function: {function_var}"

Go

// h is in the global (instance-wide) scope.
var h string

// init runs during package initialization. So, this will only run during an
// an instance's cold start.
func init() {
	h = heavyComputation()
	functions.HTTP("ScopeDemo", ScopeDemo)
}

// ScopeDemo is an example of using globally and locally
// scoped variables in a function.
func ScopeDemo(w http.ResponseWriter, r *http.Request) {
	l := lightComputation()
	fmt.Fprintf(w, "Global: %q, Local: %q", h, l)
}

Java

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import java.io.IOException;
import java.io.PrintWriter;
import java.util.Arrays;

public class Scopes implements HttpFunction {
  // Global (instance-wide) scope
  // This computation runs at instance cold-start.
  // Warning: Class variables used in functions code must be thread-safe.
  private static final int INSTANCE_VAR = heavyComputation();

  @Override
  public void service(HttpRequest request, HttpResponse response)
      throws IOException {
    // Per-function scope
    // This computation runs every time this function is called
    int functionVar = lightComputation();

    var writer = new PrintWriter(response.getWriter());
    writer.printf("Instance: %s; function: %s", INSTANCE_VAR, functionVar);
  }

  private static int lightComputation() {
    int[] numbers = new int[] { 1, 2, 3, 4, 5, 6, 7, 8, 9 };
    return Arrays.stream(numbers).sum();
  }

  private static int heavyComputation() {
    int[] numbers = new int[] { 1, 2, 3, 4, 5, 6, 7, 8, 9 };
    return Arrays.stream(numbers).reduce((t, x) -> t * x).getAsInt();
  }
}

C#

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

namespace Scopes;

public class Function : IHttpFunction
{
    // Global (server-wide) scope.
    // This computation runs at server cold-start.
    // Warning: Class variables used in functions code must be thread-safe.
    private static readonly int GlobalVariable = HeavyComputation();

    // Note that one instance of this class (Function) is created per invocation,
    // so calling HeavyComputation in the constructor would not have the same
    // benefit.

    public async Task HandleAsync(HttpContext context)
    {
        // Per-function-invocation scope.
        // This computation runs every time this function is called.
        int functionVariable = LightComputation();

        await context.Response.WriteAsync(
            $"Global: {GlobalVariable}; function: {functionVariable}",
            context.RequestAborted);
    }

    private static int LightComputation()
    {
        int[] numbers = { 1, 2, 3, 4, 5, 6, 7, 8, 9 };
        return numbers.Sum();
    }

    private static int HeavyComputation()
    {
        int[] numbers = { 1, 2, 3, 4, 5, 6, 7, 8, 9 };
        return numbers.Aggregate((current, next) => current * next);
    }
}

Ruby

# Global (instance-wide) scope.
# This block runs on cold start, before any function is invoked.
#
# Note: It is usually best to run global initialization in an on_startup block
# instead at the top level of the Ruby file. This is because top-level code
# could be executed to verify the function during deployment, whereas an
# on_startup block is run only when an actual function instance is starting up.
FunctionsFramework.on_startup do
  instance_data = perform_heavy_computation

  # To pass data into function invocations, the best practice is to set a
  # key-value pair using the Ruby Function Framework's built-in "set_global"
  # method. Functions can call the "global" method to retrieve the data by key.
  # (You can also use Ruby global variables or "toplevel" local variables, but
  # they can make it difficult to isolate global data for testing.)
  set_global :my_instance_data, instance_data
end

FunctionsFramework.http "tips_scopes" do |_request|
  # Per-function scope.
  # This method is called every time this function is called.
  invocation_data = perform_light_computation

  # Retrieve the data computed by the on_startup block.
  instance_data = global :my_instance_data

  "instance: #{instance_data}; function: #{invocation_data}"
end

PHP

use Psr\Http\Message\ServerRequestInterface;

function scopeDemo(ServerRequestInterface $request): string
{
    // Heavy computations should be cached between invocations.
    // The PHP runtime does NOT preserve variables between invocations, so we
    // must write their values to a file or otherwise cache them.
    // (All writable directories in Cloud Functions are in-memory, so
    // file-based caching operations are typically fast.)
    // You can also use PSR-6 caching libraries for this task:
    // https://packagist.org/providers/psr/cache-implementation
    $cachePath = sys_get_temp_dir() . '/cached_value.txt';

    $response = '';
    if (file_exists($cachePath)) {
        // Read cached value from file, using file locking to prevent race
        // conditions between function executions.
        $response .= 'Reading cached value.' . PHP_EOL;
        $fh = fopen($cachePath, 'r');
        flock($fh, LOCK_EX);
        $instanceVar = stream_get_contents($fh);
        flock($fh, LOCK_UN);
    } else {
        // Compute cached value + write to file, using file locking to prevent
        // race conditions between function executions.
        $response .= 'Cache empty, computing value.' . PHP_EOL;
        $instanceVar = _heavyComputation();
        file_put_contents($cachePath, $instanceVar, LOCK_EX);
    }

    // Lighter computations can re-run on each function invocation.
    $functionVar = _lightComputation();

    $response .= 'Per instance: ' . $instanceVar . PHP_EOL;
    $response .= 'Per function: ' . $functionVar . PHP_EOL;

    return $response;
}

É muito importante fazer o armazenamento em cache de conexões de rede, referências de biblioteca e objetos de cliente de API em escopo global. Consulte Otimizar redes para exemplos.

Observação: tarefas em segundo plano não devem ser realizadas fora da duração de uma solicitação. Se for necessário inicializar uma variável global com o resultado de uma tarefa em segundo plano cara, execute-a durante a execução da função e armazene o resultado antes de enviar uma resposta.

Reduza a inicialização a frio definindo um número mínimo de instâncias

Por padrão, o Cloud Run functions dimensiona o número de instâncias com base no número de solicitações de entrada. É possível alterar esse comportamento padrão definindo um número mínimo de instâncias que o Cloud Run functions precisa manter prontas para exibir solicitações. Definir um número mínimo de instâncias reduz as inicializações a frio do aplicativo. Recomendamos definir um número mínimo de instâncias e concluir a inicialização no momento do carregamento se o aplicativo for sensível à latência.

Para saber como definir um número mínimo de instâncias, consulte Como usar o mínimo instâncias.

Observações sobre inicialização a frio e inicialização

A inicialização global acontece no momento do carregamento. Sem ele, a primeira solicitação precisaria concluir a inicialização e carregar módulos, o que resultaria em uma latência maior.

No entanto, a inicialização global também tem um impacto nas inicializações a frio. Para minimizar esse impacto, inicialize apenas o que for necessário para a primeira solicitação, para manter a latência da primeira solicitação o mais baixa possível.

Isso é especialmente importante se você configurou instâncias mínimas, conforme descrito acima, para uma função sensível à latência. Nesse cenário, a conclusão da inicialização no momento do carregamento e o armazenamento em cache de dados úteis garante que a primeira solicitação não precise fazer isso e seja enviada com baixa latência.

Se você inicializar variáveis no escopo global, dependendo da linguagem, tempos de inicialização longos podem resultar em dois comportamentos: - Para algumas combinações de linguagens e bibliotecas assíncronas, o framework de função pode ser executado de forma assíncrona e retornar imediatamente, fazendo com que o código continue sendo executado em segundo plano, o que pode causar problemas, como não conseguir acessar a CPU. Para evitar isso, bloqueie a inicialização do módulo, conforme descrito abaixo. Isso também garante que as solicitações não sejam atendidas até que a inicialização seja concluída. - Por outro lado, se a inicialização for síncrona, o tempo de inicialização longo vai causar inicializações a frio mais longas, o que pode ser um problema, especialmente com funções de baixa simultaneidade durante picos de carga.

Observação: se você optar por usar tempos de inicialização a frio mais longos e min_instances, também recomendamos usar alta simultaneidade para oferecer melhor suporte a picos de tráfego.

Exemplo de pré-aquecimento de uma biblioteca node.js assíncrona

O Node.js com o Firestore é um exemplo de biblioteca assíncrona do Node.js. Para aproveitar o min_instances, o código abaixo conclui o carregamento e a inicialização no momento do carregamento, bloqueando o carregamento do módulo.

O TLA é usado, o que significa que o ES6 é necessário, usando uma extensão .mjs para o código node.js ou adicionando type: module ao arquivo package.json.

{
  "main": "main.js",
  "type": "module",
  "dependencies": {
    "@google-cloud/firestore": "^7.10.0",
    "@google-cloud/functions-framework": "^3.4.5"
  }
}

Node.js

import Firestore from '@google-cloud/firestore';
import * as functions from '@google-cloud/functions-framework';

const firestore = new Firestore({preferRest: true});

// Pre-warm firestore connection pool, and preload our global config
// document in cache. In order to ensure no other request comes in,
// block the module loading with a synchronous global request:
const config = await firestore.collection('collection').doc('config').get();

functions.http('fetch', (req, res) => {

// Do something with config and firestore client, which are now preloaded
// and will execute at lower latency.
});

Exemplos de inicialização global

Node.js

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

// Always initialized (at cold-start)
const nonLazyGlobal = fileWideComputation();

// Declared at cold-start, but only initialized if/when the function executes
let lazyGlobal;

/**
 * HTTP function that uses lazy-initialized globals
 *
 * @param {Object} req request context.
 * @param {Object} res response context.
 */
functions.http('lazyGlobals', (req, res) => {
  // This value is initialized only if (and when) the function is called
  lazyGlobal = lazyGlobal || functionSpecificComputation();

  res.send(`Lazy global: ${lazyGlobal}, non-lazy global: ${nonLazyGlobal}`);
});

Python

import functions_framework

# Always initialized (at cold-start)
non_lazy_global = file_wide_computation()

# Declared at cold-start, but only initialized if/when the function executes
lazy_global = None


@functions_framework.http
def lazy_globals(request):
    """
    HTTP Cloud Function that uses lazily-initialized globals.
    Args:
        request (flask.Request): The request object.
        <http://flask.pocoo.org/docs/1.0/api/#flask.Request>
    Returns:
        The response text, or any set of values that can be turned into a
        Response object using `make_response`
        <http://flask.pocoo.org/docs/1.0/api/#flask.Flask.make_response>.
    """
    global lazy_global, non_lazy_global

    # This value is initialized only if (and when) the function is called
    if not lazy_global:
        lazy_global = function_specific_computation()

    return f"Lazy: {lazy_global}, non-lazy: {non_lazy_global}."

Go

// Package tips contains tips for writing Cloud Functions in Go.
package tips

import (
	"context"
	"log"
	"net/http"
	"sync"

	"cloud.google.com/go/storage"
	"github.com/GoogleCloudPlatform/functions-framework-go/functions"
)

// client is lazily initialized by LazyGlobal.
var client *storage.Client
var clientOnce sync.Once

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

// LazyGlobal is an example of lazily initializing a Google Cloud Storage client.
func LazyGlobal(w http.ResponseWriter, r *http.Request) {
	// You may wish to add different checks to see if the client is needed for
	// this request.
	clientOnce.Do(func() {
		// Pre-declare an err variable to avoid shadowing client.
		var err error
		client, err = storage.NewClient(context.Background())
		if err != nil {
			http.Error(w, "Internal error", http.StatusInternalServerError)
			log.Printf("storage.NewClient: %v", err)
			return
		}
	})
	// Use client.
}

Java

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import java.io.IOException;
import java.io.PrintWriter;
import java.util.Arrays;

public class LazyFields implements HttpFunction {
  // Always initialized (at cold-start)
  // Warning: Class variables used in Servlet classes must be thread-safe,
  // or else might introduce race conditions in your code.
  private static final int NON_LAZY_GLOBAL = fileWideComputation();

  // Declared at cold-start, but only initialized if/when the function executes
  // Uses the "initialization-on-demand holder" idiom
  // More information: https://en.wikipedia.org/wiki/Initialization-on-demand_holder_idiom
  private static class LazyGlobalHolder {
    // Making the default constructor private prohibits instantiation of this class
    private LazyGlobalHolder() {}

    // This value is initialized only if (and when) the getLazyGlobal() function below is called
    private static final Integer INSTANCE = functionSpecificComputation();

    private static Integer getInstance() {
      return LazyGlobalHolder.INSTANCE;
    }
  }

  @Override
  public void service(HttpRequest request, HttpResponse response)
      throws IOException {
    Integer lazyGlobal = LazyGlobalHolder.getInstance();

    var writer = new PrintWriter(response.getWriter());
    writer.printf("Lazy global: %s; non-lazy global: %s%n", lazyGlobal, NON_LAZY_GLOBAL);
  }

  private static int functionSpecificComputation() {
    int[] numbers = new int[] {1, 2, 3, 4, 5, 6, 7, 8, 9};
    return Arrays.stream(numbers).sum();
  }

  private static int fileWideComputation() {
    int[] numbers = new int[] {1, 2, 3, 4, 5, 6, 7, 8, 9};
    return Arrays.stream(numbers).reduce((t, x) -> t * x).getAsInt();
  }
}

C#

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

namespace LazyFields;

public class Function : IHttpFunction
{
    // This computation runs at server cold-start.
    // Warning: Class variables used in functions code must be thread-safe.
    private static readonly int NonLazyGlobal = FileWideComputation();

    // This variable is initialized at server cold-start, but the
    // computation is only performed when the function needs the result.
    private static readonly Lazy<int> LazyGlobal = new Lazy<int>(
        FunctionSpecificComputation,
        LazyThreadSafetyMode.ExecutionAndPublication);

    public async Task HandleAsync(HttpContext context)
    {
        // In a more complex function, there might be some paths that use LazyGlobal.Value,
        // and others that don't. The computation is only performed when necessary, and
        // only once per server.
        await context.Response.WriteAsync(
            $"Lazy global: {LazyGlobal.Value}; non-lazy global: {NonLazyGlobal}",
            context.RequestAborted);
    }

    private static int FunctionSpecificComputation()
    {
        int[] numbers = { 1, 2, 3, 4, 5, 6, 7, 8, 9 };
        return numbers.Sum();
    }

    private static int FileWideComputation()
    {
        int[] numbers = { 1, 2, 3, 4, 5, 6, 7, 8, 9 };
        return numbers.Aggregate((current, next) => current * next);
    }
}

Ruby

FunctionsFramework.on_startup do
  # This method is called when the function is initialized, not on each
  # invocation.

  # Declare and set non_lazy_global
  set_global :non_lazy_global, file_wide_computation

  # Declare, but do not set, lazy_global
  set_global :lazy_global do
    function_specific_computation
  end
end

FunctionsFramework.http "tips_lazy" do |_request|
  # This method is called every time this function is called.

  "Lazy: #{global :lazy_global}; non_lazy: #{global :non_lazy_global}"
end

PHP

As funções PHP não preservam variáveis entre solicitações. A amostra de escopos acima usa o carregamento lento para armazenar em cache os valores de variáveis globais em um arquivo.

Isso é importante principalmente se você definir várias funções em um único arquivo e diferentes funções usarem variáveis distintas. A menos que você use a inicialização lenta, poderá desperdiçar recursos em variáveis que são inicializadas, mas nunca usadas.

Observação: essa técnica também pode ser usada ao importar dependências no Node.js e no Python, embora prejudique a legibilidade do código.

Outros recursos

Saiba mais sobre como otimizar o desempenho no vídeo do "Atlas de desempenho do Google Cloud", Tempo de inicialização a frio do Cloud Run functions.