Especifique dependências no Node.js

Uma função pode usar módulos Node.js externos, bem como dados locais. As dependências no Node.js são geridas com o npm e expressas num ficheiro de metadados denominado package.json. Pode usar o npm, o yarn ou o pnpm para instalar dependências do Node.js.

O Functions Framework do Node.js é uma dependência necessária para todas as funções. Embora as funções do Cloud Run o instalem em seu nome quando a função é criada, recomendamos que o inclua como uma dependência explícita para maior clareza.

Se a sua função depender de dependências privadas, recomendamos que duplique functions-framework no seu registo privado. Inclua o pacote functions-framework duplicado como uma dependência da sua função para evitar a instalação do pacote a partir da Internet pública.

Para especificar uma dependência para a sua função, adicione-a ao ficheiro package.json.

Nota: se for encontrado um ficheiro package-lock.json, yarn.lock ou pnpm-lock.yaml no seu projeto, esse ficheiro de bloqueio é respeitado quando as dependências são instaladas através do npm ci, yarn install ou pnpm install.

Neste exemplo, é apresentada uma dependência no ficheiro package.json:

{
  "dependencies": {
    "escape-html": "^1.0.3"
  }
}

A dependência é, em seguida, importada na função:

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')}!`);
});

Usar npm para instalar módulos Node.js localmente

A forma mais fácil de instalar um módulo do Node.js localmente é usar o comando npm install na pasta que contém a sua função do Cloud Run. Por exemplo, o seguinte comando adiciona o módulo uuid:

npm install uuid

Isto combina dois passos:

1. Marca a versão mais recente do módulo como uma dependência no ficheiro package.json. Isto é muito importante: as funções do Cloud Run só instalam módulos declarados no seu ficheiro package.json.
2. Transfere o módulo para o diretório node_modules. Isto permite-lhe usar o módulo quando desenvolve localmente.

Se não tiver o npm instalado no seu computador, obtenha o npm.

Nota: os pacotes npm estão disponíveis para uma variedade de Google Cloud produtos. Consulte as bibliotecas cliente Node.js.

Configurar dependências de implementação

Pode instalar dependências de produção para NPM, Yarn ou Pnpm:

NPM

Quando implementa a sua função, as funções do Cloud Run instalam as dependências declaradas no ficheiro package.json através do comando npm install:

npm install --production

Fio

No tempo de execução do Node.js 8 e superior, se existir um ficheiro yarn.lock, as funções do Cloud Run usam, em alternativa, o comando yarn install:

yarn install --production

Pnpm

No tempo de execução do Node.js 8 e superior, se existir um ficheiro pnpm-lock.yaml, as funções do Cloud Run usam, em alternativa, o comando pnpm install:

pnpm install

Nota: as dependências declaradas em subdiretórios não são instaladas. Se estiver a usar um monorepo, é recomendável executar um script de compilação personalizado durante a implementação para instalar essas dependências.

Executar passos de compilação personalizados durante a implementação

Após a implementação, pode executar um passo de compilação personalizado durante o processo de compilação da função adicionando um script gcp-build no ficheiro package.json.

Quando este script é executado, as dependências nos campos dependencies e devDependencies do seu ficheiro package.json estão disponíveis. Depois de executar o passo de compilação personalizado, as funções do Cloud Run removem e regeneram a pasta node_modules instalando apenas as dependências de produção declaradas no campo dependencies do ficheiro package.json.

Se não existir um guião gcp-build em package.json, as funções do Cloud Run apenas instalam dependências de produção.

Usar pacotes do sistema

O tempo de execução do Node.js também inclui vários pacotes do sistema no ambiente de execução.

Incluir módulos Node.js locais

Também pode incluir módulos Node.js locais como parte da sua função. Pode consegui-lo declarando o seu módulo em package.json usando o prefixo file:. No exemplo seguinte, mymodule refere-se ao nome do módulo e mymoduledir é o diretório que contém o módulo:

  {
  "dependencies": {
    "mymodule": "file:mymoduledir"
  }
}

O código deste módulo local deve ser armazenado num local diferente da pasta node_modules no diretório raiz da sua função.

Nota: se fizer a implementação através da ferramenta de linha de comandos gcloud, esta cria automaticamente um ficheiro .gcloudignore no diretório da função.gcloud Por predefinição, a pasta node_modules é adicionada a este .gcloudignore e não é carregada como parte da sua implementação. Não precisa de incluir a pasta node_modules quando carrega manualmente código como um ficheiro ZIP. Pode implementar com êxito a sua função sem a pasta node_modules.

Carregar módulos Node.js

Use a função Node.js require() para carregar qualquer módulo Node.js que tenha instalado. Também pode usar a função require() para importar ficheiros locais que implementa juntamente com a sua função.

Usar módulos privados

Pode usar um módulo npm privado fornecendo definições para autenticação com o registo num ficheiro .npmrc no diretório da função. Se estiver a usar o Yarn v2 ou superior como gestor de pacotes, este ficheiro chama-se .yarnrc.yml.

Módulos privados do Artifact Registry

Um repositório de pacotes do Node.js do Artifact Registry pode alojar módulos privados para a sua função. Quando implementa uma função do Cloud Run Functions, o processo de compilação gera automaticamente credenciais do Artifact Registry para a conta de serviço do Cloud Build. Só tem de listar o repositório do Artifact Registry no seu .npmrc sem gerar credenciais adicionais. Por exemplo:

@SCOPE:registry=https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
//REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME:always-auth=true

Esta abordagem também funciona para o gestor de pacotes Yarn v1. Se estiver a usar o Yarn v2 ou superior, só precisa de listar o repositório do Artifact Registry no seu .yarnrc.yml sem credenciais adicionais. Por exemplo:

npmScopes:
  SCOPE:
    npmRegistryServer: https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
    npmAlwaysAuth: true

Módulos privados de outros repositórios

A documentação do npm explica como criar tokens de acesso personalizados de só de leitura. Desaconselhamos a utilização do ficheiro .npmrc criado no diretório inicial, uma vez que contém um token de leitura/escrita. As autorizações de escrita não são necessárias durante a implementação e podem representar um risco de segurança.

Não inclua o ficheiro .npmrc se não estiver a usar repositórios privados, uma vez que pode aumentar o tempo de implementação das suas funções.

Nota: se estiver a usar autorizações personalizadas (como as necessárias para o VPC), certifique-se de que permite explicitamente que as suas funções acedam ao repositório privado de destino.

Formato de ficheiro

Se estiver a usar um ficheiro .npmrc para definir um token de autorização personalizado, este deve incluir a seguinte linha.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Substituir:

• REGISTRY_DOMAIN: o nome de domínio do seu registo npm privado. Se o seu repositório estiver alojado com npmjs.org, defina este campo como registry.npmjs.org.

• AUTH_TOKEN: o token de autorização para o seu registo npm. Pode ser o valor de texto literal do token ou a string de texto ${NPM_TOKEN}, que npm substitui pelo valor real do token do ambiente.

  Pode definir a variável de ambiente $NPM_TOKEN com o argumento --set-build-env-vars para o comando gcloud functions deploy. Consulte o tutorial do NPM sobre módulos privados para ver mais detalhes do token de autorização do NPM.

Crie a sua função com dependências copiadas

As dependências copiadas são aquelas cuja origem está incluída diretamente no pacote de código-fonte e são recompiladas juntamente com o seu próprio código. Cria dependências do Node.js copiadas e ignora a instalação das mesmas durante a implementação através da variável de ambiente de compilação GOOGLE_VENDOR_NPM_DEPENDENCIES.

Pré-requisitos para dependências copiadas

1. Certifique-se de que tem uma função funcional com todas as dependências que quer copiar no seu ficheiro package.json.

2. Instale estas dependências localmente executando:

       npm install
   

3. Remova node_modules do ficheiro .gcloudignore no seu diretório de trabalho.

4. Implemente a função, garantindo que a versão local do Node.js é a mesma que especifica durante a implementação.

5. Implemente a sua função e as dependências copiadas com o seguinte comando:

     gcloud run deploy SERVICE \
       --source . \
       --function FUNCTION_ENTRY_POINT \
       --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true
   

   Substituir:

   • SERVICE: o nome da função do Cloud Run que está a implementar
   • FUNCTION_ENTRY_POINT: com o ponto de entrada da sua função no código fonte.

Se especificar um motor npm no ficheiro package.json, a versão especificada do npm é transferida no momento da compilação. Para suprimir este comportamento, remova-o do ficheiro package.json.