O ambiente de execução do Node.js

A função do Cloud Run é 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 das funções do Cloud Run.

Para começar a criar e implantar as funções do Cloud Run 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.

Selecione o ambiente de execução

As funções do Cloud Run dão 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.

• Consulte Implantar uma função do Cloud Run para saber como realizar a implantação usando a CLI do Google Cloud.

• Consulte o guia de início rápido do console do Google Cloud para saber como realizar a implantação usando o console do Google Cloud.

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 Ambiente de execução das funções do Cloud Run para mais informações.

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

Estrutura do código-fonte

Para que as funções do Cloud Run encontrem 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 funções do Cloud Run 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();

Aviso: não sinalizar o encerramento da função corretamente pode fazer com que ela seja encerrada antecipadamente ou permaneça em execução até que o tempo limite seja atingido. Para mais informações, consulte o Guia de solução de problemas.

Usar o middleware para processar solicitações HTTP

As funções do Cloud Run HTTP para Node.js fornecem objetos request e response compatíveis com ExpressJS para simplificar o consumo das solicitações HTTP. As funções do Cloud Run leem 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. Elas também fornecem uma melhoria de sintaxe popular com as instruções import e export, que podem ser usadas em uma função do Cloud Run (em vez das instruções require).

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

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

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

Observação: saiba mais sobre como usar módulos ES.