O ambiente de execução Node.js

A Função do Cloud é executada em um ambiente que consiste em uma versão do sistema operacional, além de pacotes complementares, suporte a linguagens e a biblioteca do Functions Framework que dá suporte e invoca a função. Esse ambiente é identificado pela versão da linguagem e é conhecido como ambiente de execução.

Para mais informações sobre ambientes de execução em geral e para saber qual versão do Ubuntu cada ambiente de execução Node.js usa, consulte o Ambiente de execução do Cloud Functions.

Para começar a criar e implantar o Cloud Functions com Node.js, consulte o Guia de início rápido.

Para criar e testar funções no sistema local, consulte Executar funções com o Functions Framework.

Selecionar o ambiente de execução

O Cloud Functions dá suporte a várias versões do Node.js, que estão listadas na página Suporte ao ambiente de execução. Selecione seu ambiente de execução Node.js preferencial para a função durante a implantação.

Ambiente de execução

Isso inclui o ambiente de execução, o sistema operacional, os pacotes e uma biblioteca que invoca a função.

O Node.js 18 e as versões mais recentes usam um ambiente de execução que é baseado no Ubuntu 22.04. As versões anteriores ao Node.js 18 são baseadas no Ubuntu 18.04. Consulte o Ambiente de execução do Cloud Functions para mais informações.

A biblioteca que invoca a função é o Functions Framework para Node.js.

Estrutura do código-fonte

Para que o Cloud Functions encontre a definição da sua função, cada ambiente de execução possui determinados requisitos de estruturação para o código-fonte. Consulte Como escrever Cloud Functions para mais informações.

Especificar as dependências

É possível especificar dependências para suas funções listando-as em um arquivo package.json. Para ver mais informações, consulte Como especificar dependências no Node.js.

Script de build do NPM

Por padrão, o ambiente de execução do Node.js executará npm run build se um script build for detectado em package.json. Se você precisar de mais controle sobre as etapas do build antes de iniciar o aplicativo, forneça uma etapa de build personalizada adicionando um script gcp-build ao arquivo package.json.

Para evitar que sua build execute o script npm run build:

  • Adicione um script gcp-build com um valor vazio ao arquivo package.json: "gcp-build":"".

  • Definir a variável de ambiente de build GOOGLE_NODE_RUN_SCRIPTS como a string vazia para impedir que todos os scripts sejam executados.

Conclusão de função assíncrona

Ao trabalhar com tarefas assíncronas que envolvem callbacks ou objetos Promise, é necessário informar explicitamente o ambiente de execução que sua função encerrou a execução dessas tarefas. É possível fazer isso de várias maneiras diferentes, conforme mostrado nos exemplos abaixo. O segredo é que o código aguarde a conclusão da tarefa assíncrona ou da Promise antes de retornar. Caso contrário, o componente assíncrono da função pode ser encerrado antes da conclusão.

Funções baseadas em eventos

Retorno implícito

  exports.implicitlyReturning = async (event, context) => {
    return await asyncFunctionThatReturnsAPromise();
  };

Retorno explícito

  exports.explicitlyReturning = function (event, context) {
    return asyncFunctionThatReturnsAPromise();
  };

Funções HTTP

Node.js 

// OK: await-ing a Promise before sending an HTTP response
await Promise.resolve();

// WRONG: HTTP functions should send an
// HTTP response instead of returning.
return Promise.resolve();

// HTTP functions should signal termination by returning an HTTP response.
// This should not be done until all background tasks are complete.
res.send(200);
res.end();

// WRONG: this may not execute since an
// HTTP response has already been sent.
return Promise.resolve();

Usar o middleware para processar solicitações HTTP

As Cloud Functions HTTP para Node.js fornecem objetos request e response compatíveis com ExpressJS (em inglês) para simplificar o consumo das solicitações HTTP. O Cloud Functions lê automaticamente o corpo da solicitação. Dessa maneira, você sempre recebe o corpo de uma solicitação, independentemente do tipo de conteúdo. Isso significa que as solicitações HTTP precisam ser consideradas totalmente lidas no momento em que o código é executado. O aninhamento de apps ExpressJS precisa ser usado com a ressalva de que um middleware com corpo de solicitação não lido pode não ter o comportamento esperado.

Usar módulos ES

Os módulos do ECMAScript (módulos ES ou ESM) são um recurso padrão do TC39, sem sinalização, na versão 14 ou posterior do Node para carregar módulos JavaScript. Ao contrário do CommonJS, o ESM fornece uma API assíncrona para carregar módulos. Ele também fornece uma melhoria de sintaxe popular com as instruções import e export, que podem ser usadas em uma função do Cloud (em vez das instruções require).

Para usar o ESM em uma função do Cloud, você precisa declarar "type": "module" no package.json.

{
  ...
  "type": "module",
  ...
}

Em seguida, use as instruções import e export.