Como lidar com dependências


Uma função pode usar módulos externos do Node.js, bem como dados locais. As dependências no Node.js são gerenciadas com npm e expressas em um arquivo de metadados chamado package.json . Os ambientes de execução do Cloud Functions Node.js são compatíveis com a instalação usando npm , yarn ou pnpm .

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

Neste exemplo, uma dependência está listada no arquivo package.json :

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

A dependência é então importada na função:

JavaScript Texto datilografado
const escapeHtml = require('escape-html');

// Return a greeting with the input HTML-escaped.
exports.hello = functions.https.onRequest((req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});
import * as escapeHtml from 'escape-html';

// Return a greeting with the input HTML-escaped.
export let hello = functions.https.onRequest((req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
}

Incluindo módulos Node.js locais

Você também pode incluir módulos Node.js locais como parte de sua função. Você pode conseguir isso declarando seu módulo em package.json usando o file: prefix . No exemplo a seguir, mymodule refere-se ao nome do seu módulo e mymoduledir é o diretório que contém o seu módulo:

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

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

Etapas adicionais para TypeScript

O TypeScript ajuda mais quando você usa bibliotecas que possuem informações de tipo. Isso permite que o TypeScript detecte erros de sintaxe e permite que os editores forneçam melhores sugestões de preenchimento automático. Algumas bibliotecas, como firebase-admin e firebase-functions , vêm com definições TypeScript incluídas.

Muitas bibliotecas não fornecem sua própria definição de TypeScript. O projeto DefinitelyTyped fornece definições mantidas pela comunidade para as bibliotecas de nós mais populares. DefinitelyTyped publica essas definições sob o mesmo nome de pacote NPM, mas dentro da organização "@types". Por exemplo, você pode instalar as informações de tipo da biblioteca uuid com o seguinte:

npm install @types/uuid

À medida que você se familiarizar mais com o TypeScript, poderá combinar as duas instalações:

npm install uuid @types/uuid

As dependências de tipo devem ser do mesmo tipo que a dependência da biblioteca. Por exemplo, você não deve salvar uuid como uma dependência normal e @types/uuid como uma dependência dev ou peer.

Carregando módulos Node.js

Use a função require() do Node.js para carregar qualquer módulo Node.js que você tenha instalado. Você também pode usar a função require() para importar arquivos locais implantados junto com sua função.

Se você estiver escrevendo funções em TypeScript, use a instrução import da mesma maneira para carregar qualquer módulo Node.js instalado.

Usando módulos privados

Você pode usar um módulo npm privado fornecendo configurações para autenticação com o registro em um arquivo .npmrc no diretório da função. Se você estiver usando o Yarn v2 ou superior como gerenciador de pacotes, esse arquivo será denominado .yarnrc.yml .

Módulos privados do Artifact Registry

Um repositório de pacotes Node.js do Artifact Registry pode hospedar módulos privados para sua função. Quando você implanta uma função do Google Cloud Functions, o processo de compilação gera automaticamente credenciais do Artifact Registry para a conta de serviço do Cloud Build . Você só precisa listar o repositório do Artifact Registry em 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

Essa abordagem também funciona para o gerenciador de pacotes Yarn v1. Se estiver usando o Yarn v2 ou superior, você só precisará listar o repositório do Artifact Registry em 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 somente leitura personalizados. Não recomendamos o uso do arquivo .npmrc criado no diretório inicial porque ele contém um token de leitura e gravação. As permissões de gravação não são necessárias durante a implantação e podem representar um risco à segurança.

Não inclua o arquivo .npmrc se não estiver usando repositórios privados, pois isso pode aumentar o tempo de implantação de suas funções.

Formato de arquivo

Se você estiver usando um arquivo .npmrc para definir um token de autenticação personalizado, ele deverá incluir a linha mostrada abaixo.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Substituir:

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

  • AUTH_TOKEN : o token de autorização para seu registro 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.

    Você 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 obter mais detalhes sobre o token de autenticação do NPM.

Crie sua função com dependências de fornecedores

Dependências de fornecedor são aquelas cuja fonte está incluída diretamente em seu pacote de código-fonte e reconstruída junto com seu próprio código. Você cria dependências do Node.js vendidas e ignora a instalação delas durante a implantação usando a variável de ambiente de compilação GOOGLE_VENDOR_NPM_DEPENDENCIES.

Pré-requisitos para dependências de fornecedores

  1. Certifique-se de ter uma função funcional com todas as dependências que deseja fornecer ao fornecedor definidas em seu arquivo package.json .

  2. Instale essas dependências localmente executando

        npm install

  3. Remova node_modules do arquivo .gcloudignore em seu diretório de trabalho.

  4. Implante a função, garantindo que sua versão local do Node.js seja a mesma que você especificou durante a implantação.

  5. Implante sua função e as dependências vendidas com o seguinte comando:

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

    Substituir:

    • FUNCTION_NAME : o nome da função do Cloud Functions que você está implantando
    • RUNTIME_NAME : o nome do tempo de execução do Node.js no qual executar sua função implantada. Esta deve ser a mesma versão do Node.js que você usou em seu ambiente de desenvolvimento local

O pacote da estrutura Functions é uma dependência necessária para funções. Para compilações mais rápidas, recomendamos vender este pacote. Caso contrário, ele será baixado e instalado quando sua função for criada.

Se você especificar um mecanismo npm no arquivo package.json, a versão especificada do npm será baixada no momento da construção. Para suprimir esse comportamento, remova-o do arquivo package.json.