Dicas e truques

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

Correção

Nesta seção, você verá as práticas recomendadas gerais para projetar e implementar funções do Google Functions.

Escrever 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 em segundo plano.

Garantir que as funções HTTP enviem uma resposta HTTP

Se sua 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 escapeHtml = require('escape-html');

/**
 * HTTP Cloud Function.
 *
 * @param {Object} req Cloud Function request context.
 *                     More info: https://expressjs.com/en/api.html#req
 * @param {Object} res Cloud Function response context.
 *                     More info: https://expressjs.com/en/api.html#res
 */
exports.helloHttp = (req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
};

Python

from flask import escape

def hello_http(request):
    """HTTP Cloud Function.
    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>.
    """
    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 'Hello {}!'.format(escape(name))

Go


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

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

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

Não iniciar 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 callbackcallback nas funções de segundo plano do Node.js. Qualquer código executado após a finalização normal não pode acessar a CPU e não progredirá.

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. Deixar de excluir explicitamente esses arquivos pode resultar em um erro de memória insuficiente e uma inicialização a frio subsequente.

Veja a memória usada por uma função individual ao selecioná-la na lista de funções do Console do Cloud e escolher o gráfico Uso de memória.

Não tente gravar fora do diretório temporário e não se esqueça de usar métodos independentes de plataforma/SO para criar caminhos de arquivo.

Você pode ignorar as restrições de tamanho em arquivos temporários usando o pipelining. Por exemplo, processe um arquivo no Cloud Storage criando um stream de leitura, passando-o por um processo baseado em stream e gravando o stream de saída diretamente no Cloud Storage.

Ferramentas

Nesta seção, você verá diretrizes sobre como usar ferramentas para implementar, testar e interagir com funções do Google Functions.

Desenvolvimento local

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

Relatórios de erros

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.

Usar o SendGrid para enviar e-mails

O Cloud 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 é usando o SendGrid (em inglês). Veja um exemplo completo no Tutorial do SendGrid e outras opções para enviar e-mails na documentação Como enviar e-mails de uma instância do Google Compute Engine.

Desempenho

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

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 uma função do Google Functions 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

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

/**
 * HTTP function that declares a variable.
 *
 * @param {Object} req request context.
 * @param {Object} res response context.
 */
exports.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

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

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 'Instance: {}; function: {}'.format(instance_var, 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()
}

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

É 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 Como otimizar as redes para ver alguns exemplos.

Faça a inicialização lenta de variáveis globais

Se você inicializar variáveis em escopo global, o código de inicialização sempre será executado por meio de uma invocação de inicialização a frio, aumentando a latência da sua função. Se alguns objetos não forem usados em todos os caminhos de código, convém inicializá-los somente sob demanda:

Node.js

// 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.
 */
exports.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

# 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

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 'Lazy: {}, non-lazy: {}.'.format(lazy_global, 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"
)

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

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

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.

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