O tempo de execução do Node.js

A sua função do Cloud Run é executada num ambiente que consiste numa versão do sistema operativo, além de pacotes suplementares, suporte de idiomas e a biblioteca Functions Framework que suporta e invoca a sua função. Este ambiente é identificado pela versão do idioma e é conhecido como o tempo de execução.

Para obter informações sobre os tempos de execução em geral e saber que versão do Ubuntu cada tempo de execução do Node.js usa, consulte o ambiente de execução das funções do Cloud Run.

Para começar a criar e implementar funções do Cloud Run com o Node.js, consulte o Início rápido.

Para criar e testar as suas funções no sistema local, consulte o artigo Execute funções com o Functions Framework.

Selecione o tempo de execução

As funções do Cloud Run suportam várias versões do Node.js, indicadas na página Suporte de tempo de execução. Pode selecionar o tempo de execução do Node.js preferido para a sua função durante a implementação:

Ambiente de execução

O ambiente de execução inclui o tempo de execução, o sistema operativo, os pacotes e uma biblioteca que invoca a sua função.

O Node.js 18 e versões mais recentes usam um ambiente de execução baseado no Ubuntu 22.04. As versões anteriores ao Node.js 18 baseiam-se no Ubuntu 18.04. Consulte o ambiente de execução das funções do Cloud Run para mais informações.

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

Estrutura do código-fonte

Para que as funções do Cloud Run encontrem a definição da sua função, cada tempo de execução tem determinados requisitos de estruturação para o seu código-fonte. Consulte o artigo Escrever funções do Cloud Run para mais informações.

Especifique dependências

Pode especificar dependências para as suas funções listando-as num ficheiro package.json. Para mais informações, consulte o artigo Especificar dependências no Node.js.

Script de compilação do NPM

Por predefinição, o tempo de execução do Node.js executa npm run build se for detetado um script build em package.json. Se precisar de controlo adicional sobre os passos de compilação antes de iniciar a aplicação, pode fornecer um passo de compilação personalizado adicionando um script gcp-build ao ficheiro package.json.

Pode impedir que a compilação execute o script npm run build de uma das seguintes formas:

  • Adicionar um script gcp-build com um valor vazio no ficheiro package.json: "gcp-build":"".

  • Definir a variável de ambiente de compilação GOOGLE_NODE_RUN_SCRIPTS para a string vazia para impedir a execução de todos os scripts.

Conclusão de funções assíncronas

Quando trabalha com tarefas assíncronas que envolvem callbacks ou objetos Promise, tem de informar explicitamente o tempo de execução de que a sua função terminou de executar estas tarefas. Pode fazê-lo de várias formas diferentes, conforme mostrado nos exemplos seguintes. A chave é que o seu código tem de aguardar que a tarefa assíncrona ou Promise seja concluída antes de ser devolvida; caso contrário, o componente assíncrono da sua função pode ser terminado antes de ser concluído.

Funções orientadas por eventos

Devolução implícita

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

Devolução explícita

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

Use software intermédio para processar pedidos HTTP

As funções HTTP do Node.js Cloud Run fornecem objetos request e response compatíveis com o ExpressJS para simplificar o consumo de pedidos HTTP. As funções do Cloud Run leem automaticamente o corpo do pedido, pelo que recebe sempre o corpo de um pedido independentemente do tipo de suporte. Isto significa que os pedidos HTTP devem ser considerados como tendo sido totalmente lidos no momento em que o seu código é executado. A aninhagem de apps ExpressJS deve ser usada com esta ressalva. Especificamente, o middleware que espera que o corpo de um pedido não seja lido pode não funcionar conforme esperado.

Use módulos ES

Os módulos ECMAScript (módulos ES ou ESM) são uma funcionalidade padrão do TC39, sem indicação de flag, na versão 14 ou superior do Node para carregar módulos JavaScript. Ao contrário do CommonJS, o ESM oferece uma API assíncrona para carregar módulos. Também oferece uma melhoria popular da sintaxe com declarações import e export que podem ser usadas numa função do Cloud Run (em vez de declarações require).

Para usar ESM numa função do Cloud Run, tem de declarar "type": "module" no seu package.json.

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

Em seguida, pode usar as declarações import e export.