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. Os tempos de execução do Node.js das funções do Cloud Run suportam a instalação através do npm, yarn ou pnpm.

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

O Functions Framework é uma dependência obrigatória para todas as funções. Embora o Cloud Run Functions o instale 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.

Usar npm para instalar módulos Node.js localmente

A forma mais fácil de instalar um módulo Node.js localmente é usar o comando npm install na pasta que contém a sua função. Por exemplo, o comando seguinte 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 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. Veja a lista aqui.

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 usando o 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 nenhum script gcp-build em package.json, as funções do Cloud Run instalam apenas 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. Se a sua função usar uma dependência que requer um pacote que não está listado, pode pedir um pacote.

Nota: também pode implementar versões em contentores das suas funções do Cloud Run Node.js no Cloud Run através do Functions Framework.

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 através do 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 tem o nome .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, 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 linha apresentada abaixo.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Substituição:

• 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 de fornecedores

As dependências de fornecedores são aquelas cuja origem está incluída diretamente no pacote de código-fonte e são reconstruídas juntamente com o seu próprio código. Crie dependências do Node.js de fornecedores e ignore 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 de fornecedores

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

2. Instale estas dependências localmente executando:

       npm install
   

3. Remova node_modules do ficheiro .gcloudignore no 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 de fornecedores com o seguinte comando:

     gcloud functions deploy FUNCTION_NAME \
       --runtime RUNTIME_NAME \
       --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true
   

   Substituição:

   • FUNCTION_NAME: o nome da função do Cloud Functions que está a implementar
   • RUNTIME_NAME: o nome do tempo de execução do Node.js para executar a sua função implementada. Tem de ser a mesma versão do Node.js que usou no seu ambiente de desenvolvimento local

O pacote da framework Functions é uma dependência necessária para as funções. Para compilações mais rápidas, recomendamos que use este pacote. Caso contrário, é transferida e instalada quando a função é criada.

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.