Usar pacotes JavaScript

Esta página mostra como fazer o seguinte:

Antes de começar

  1. No Console do Google Cloud, acesse a página Dataform.

    Acessar o Dataform

  2. Faça uma ou ambas as seguintes ações:

    1. Para instalar um pacote em um repositório ou autenticar um pacote NPM particular para ativar a instalação, siga estas etapas:
      1. Selecione ou crie um repositório.
      2. Selecione ou crie um espaço de trabalho de desenvolvimento.
      3. Opcional: para instalar um pacote privado, autenticar o pacote privado.
      4. Se o repositório não tiver um arquivo package.json, crie package.json e mova o pacote principal do Dataform.
    2. Para criar um pacote, siga estas etapas:
      1. Crie um repositório do Dataform dedicado ao seu pacote. Combine o nome do repositório com o nome do pacote.
      2. Conecte o repositório a um repositório Git de terceiros que hospedará seu pacote.
      3. Crie e inicialize um espaço de trabalho no repositório do Dataform.

  3. Confira se você tem as permissões necessárias para concluir as tarefas neste documento.

Funções exigidas

Para receber as permissões necessárias para concluir as tarefas neste documento, peça ao administrador para conceder a você os seguintes papéis do IAM:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Instalar um pacote

Esta seção mostra como instalar um pacote JavaScript e importá-lo para um arquivo JavaScript e um arquivo SQLX para que você possa usar o pacote para desenvolver fluxos de trabalho no Dataform.

Para usar um pacote no Dataform, é necessário instalá-lo no repositório.

É possível instalar os seguintes tipos de pacotes no Dataform:

Em seguida, para usar o pacote em um arquivo JavaScript ou SQLX, é necessário importar o conteúdo selecionado do pacote para o arquivo. Também é possível importar um pacote inteiro para um arquivo JavaScript ou SQLX em vez do conteúdo selecionado.

Para evitar problemas com a instalação de pacotes no ambiente de produção, recomendamos o seguinte:

  • Especifique explicitamente a versão do pacote em package.json, por exemplo, 3.0.0. Não use outras opções dependencies de package.json, por exemplo, >version.

  • Teste as novas versões do pacote em um ambiente que não seja de produção. Para mais informações sobre como configurar diferentes ambientes de ciclo de vida do código, consulte Gerenciar o ciclo de vida do código.

Adicionar um pacote como dependência

Para instalar um pacote em um repositório do Dataform, adicione-o como uma dependência no arquivo package.json:

  1. No espaço de trabalho, selecione package.json no painel Files.

  2. Adicione o pacote ao bloco dependencies:

    1. Adicione um pacote público do NPM publicado no seguinte formato:

      "PACKAGE-NAME": "PACKAGE-VERSION"

      Substitua:

      • PACKAGE-NAME pelo nome do pacote.
      • PACKAGE-VERSION com a versão mais recente do pacote público do NPM publicado. Para evitar problemas com a instalação de pacotes, especifique explicitamente a versão, por exemplo, 3.0.0.

    2. Adicione um pacote público não publicado do NPM no seguinte formato:

      "PACKAGE-NAME": "PACKAGE-URL"

      Substitua:

      • PACKAGE-NAME pelo nome do pacote.
      • PACKAGE-URL pelo URL tar.gz do repositório de pacotes de terceiros, por exemplo, https://github.com/user/sample-package-repository/archive/master.tar.gz.

    3. Adicione um pacote NPM particular autenticado no seguinte formato:

      "REGISTRY-SCOPE/PACKAGE-NAME": "PACKAGE-URL"

      Substitua:

      • REGISTRY-SCOPE pelo nome do pacote. REGISTRY-SCOPE precisa corresponder ao escopo de registro definido no arquivo .nmprc do repositório.
      • PACKAGE-NAME pelo nome do pacote.
      • PACKAGE-URL pelo URL tar.gz do repositório do pacote, por exemplo, https://github.com/user/sample-package-repository/archive/master.tar.gz.

  3. Clique em Instalar pacotes.

  4. Confirme e envie suas alterações.

O exemplo de código a seguir mostra o pacote de dimensões de mudança lenta de código aberto público adicionado ao arquivo .package.json:

 ```json
 {
   "name": "repository-name",
   "dependencies": {
     "@dataform/core": "2.0.3",
     "dataform-scd": "https://github.com/dataform-co/dataform-scd/archive/0.3.tar.gz"
   }
 }
 ```

Importar uma função ou constante de pacote para um arquivo JavaScript no Dataform

Para usar uma função ou uma constante de um pacote em um arquivo JavaScript no Dataform, primeiro é necessário importá-la para o arquivo.

Para importar uma função ou uma constante de um pacote para um arquivo JavaScript, siga estas etapas:

  1. No seu espaço de trabalho, no painel Files, selecione um arquivo .js em que você quer usar o pacote.

  2. No arquivo, importe uma função ou uma constante no seguinte formato:

    const { EXPORT-NAME } = require("PACKAGE-NAME");
    1. Substitua EXPORT-NAME pelo nome da função ou constante que você quer usar, declarado em module.exports no arquivo index.js do pacote.
    2. Substitua PACKAGE-NAME pelo nome do pacote que você quer usar.

  3. Confirme e envie suas alterações.

O exemplo de código a seguir mostra a função getDomain do pacote postoffice importada e usada em um arquivo JavaScript:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

const { getDomain } = require("postoffice");
getDomain();

Importar um pacote inteiro para um arquivo JavaScript no Dataform

Para importar o pacote inteiro para um arquivo JavaScript em vez de importar funções ou constantes selecionadas para um arquivo JavaScript, siga estas etapas:

  1. No seu espaço de trabalho, no painel Files, selecione um arquivo .js em que você quer usar o pacote.

  2. No arquivo, importe o pacote no seguinte formato:

    const CONSTANT-NAME = require("PACKAGE-NAME");
    1. Substitua CONSTANT-NAME por um nome para a constante.
    2. Substitua PACKAGE-NAME pelo nome do pacote que você quer usar.

  3. Confirme e envie suas alterações.

O exemplo de código a seguir mostra a função getDomain do pacote postoffice importado usado em um arquivo JavaScript:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

const postoffice = require("postoffice");
postoffice.getDomain();

Importar uma função ou constante de pacote para um arquivo SQLX no Dataform

Para usar uma função ou uma constante de um pacote em um arquivo SQLX, primeiro é necessário importá-la para o arquivo.

Para importar uma função ou uma constante de um pacote para um arquivo SQLX, siga estas etapas:

  1. No seu espaço de trabalho, no painel Files, selecione um arquivo .sqlx em que você quer usar o pacote.

  2. No arquivo, insira o seguinte bloco js:

    js {
  const { EXPORT-NAME } = require("PACKAGE-NAME");
}
    1. Substitua EXPORT-NAME pelo nome da função ou constante que você quer usar, declarado em module.exports no arquivo index.js do pacote.
    2. Substitua PACKAGE-NAME pelo nome do pacote que você quer usar.

  3. Confirme e envie suas alterações.

O exemplo de código abaixo mostra a função getDomain do pacote postoffice importado em um bloco js e usado em uma instrução SELECT em um arquivo SQLX:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

config {
    type: "table",
}

js {
  const { getDomain } = require("postoffice");
}

SELECT ${getDomain("email")} as test

Importar um pacote inteiro para um arquivo SQLX no Dataform

Para importar o pacote inteiro para um arquivo SQLX em vez de importar funções ou constantes selecionadas para um arquivo JavaScript, siga estas etapas:

  1. No seu espaço de trabalho, no painel Files, selecione um arquivo .sqlx em que você quer usar o pacote.

  2. No arquivo, importe o pacote no seguinte formato:

    js {
  const CONSTANT-NAME = require("PACKAGE-NAME");
}
    1. Substitua CONSTANT-NAME por um nome para a constante.
    2. Substitua PACKAGE-NAME pelo nome do pacote que você quer usar.

  3. Confirme e envie suas alterações.

O exemplo de código a seguir mostra o pacote postoffice importado em um bloco js e a função getDomain usada em uma instrução SELECT em um arquivo SQLX:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

config {
    type: "table",
}

js {
  const postoffice = require("postoffice");
}

SELECT ${postoffice.getDomain("email")} as test

Autenticar um pacote particular

Esta seção mostra como autenticar um pacote npm particular no Dataform para permitir a instalação dele em um repositório do Dataform.

Para instalar um pacote NPM particular em um repositório do Dataform e usá-lo para desenvolver seu fluxo de trabalho, você precisa primeiro autenticar o pacote no Dataform. O processo de autenticação é diferente para o primeiro pacote particular em um repositório e um pacote particular subsequente em um repositório.

Autentique o primeiro pacote particular em um repositório do Dataform

Para autenticar pacotes NPM particulares no Dataform, faça o seguinte antes de instalar o primeiro pacote NPM particular em um repositório do Dataform:

  1. Crie um secret do Secret Manager dedicado a armazenar tokens de autenticação de pacotes NPM particulares no repositório do Dataform.

    1. Adicione o token de autenticação do pacote, obtido do registro do NPM, ao segredo.

    É necessário armazenar todos os tokens de autenticação dos pacotes NPM particulares no repositório em um único secret. Você precisa criar um segredo dedicado por repositório do Dataform. O secret precisa estar no formato JSON.

  2. Faça upload do segredo no repositório do Dataform.

  3. Crie um arquivo .npmrc e adicione o token de autenticação do pacote ao arquivo.

    O token de autenticação no arquivo .npmrc precisa corresponder ao token de autenticação no segredo enviado.

Depois de autenticar o pacote NPM particular, você pode instalar o pacote no repositório do Dataform.

Criar um secret para autenticação de pacotes particulares

Para autenticar pacotes NPM particulares em um repositório do Dataform, crie um secret do Secret Manager e defina tokens de autenticação para todos os pacotes particulares que você quer instalar no repositório do Dataform dentro do secret. Defina um token de autenticação para cada pacote privado do NPM e armazene todos os tokens de autenticação em um secret único para cada repositório. O secret precisa estar no formato JSON.

Para criar um segredo com tokens de autenticação para pacotes NPM particulares, siga estas etapas:

  1. No Secret Manager, crie um secret.

    1. No campo Valor do secret, insira um ou vários tokens de autenticação neste formato:
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    Substitua:

    • AUTHENTICATION_TOKEN_NAME: um nome exclusivo para o token que identifica o pacote que ele autentica.
    • TOKEN_VALUE: o valor do token de autenticação, obtido do registro do NPM.

  2. Conceda acesso ao secret à sua conta de serviço do Dataform.

    Sua conta de serviço do Dataform está neste formato:

    service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com
    1. Ao conceder acesso, conceda o papel roles/secretmanager.secretAccessor à sua conta de serviço do Dataform.

Fazer upload do segredo para autenticação de pacotes particulares em um repositório do Dataform

Antes de instalar um pacote NPM particular em um repositório do Dataform pela primeira vez, faça upload do secret que contém o token de autenticação do pacote para o repositório.

Para fazer upload do segredo com tokens de autenticação de pacotes NPM particulares para um repositório do Dataform, siga estas etapas:

  1. No Console do Google Cloud, acesse a página Dataform.

    Acessar o Dataform

  2. Selecione o repositório em que você quer instalar pacotes NPM particulares.

  3. Na página do repositório, clique em Settings > Configure private NPM packages.

  4. No painel Add NPM package secret token, no menu Secret, selecione o secret que contém tokens de autenticação para pacotes NPM particulares.

  5. Clique em Salvar.

Criar um arquivo .npmrc para autenticação de pacotes particulares

Para autenticar pacotes NPM particulares em um repositório do Dataform, crie um arquivo .npmrc de nível superior no repositório. É necessário armazenar tokens de autenticação para que todos os pacotes NPM particulares sejam instalados no repositório dentro do arquivo .npmrc. Os tokens de autenticação no arquivo .npmrc precisam corresponder aos tokens de autenticação no secreto enviado para o repositório. Para mais informações sobre arquivos .npmrc, consulte a documentação do npmrc.

Para criar um arquivo .npmrc de nível superior no repositório, siga estas etapas:

  1. No Console do Google Cloud, acesse a página Dataform.

    Acessar o Dataform

  2. Selecione o repositório em que você quer instalar pacotes NPM particulares e selecione um espaço de trabalho.

  3. No painel Files, clique em More e, em seguida, em Create file.

  4. No painel Criar novo arquivo, faça o seguinte:

    1. No campo Adicionar um caminho de arquivo, insira .npmrc.

    2. Selecione Criar arquivo.

Adicionar um token de autenticação ao arquivo .npmrc em um repositório do Dataform

Para autenticar um pacote NPM particular em um repositório do Dataform que já contém um segredo com tokens de autenticação de pacote e um arquivo .npmrc, é necessário adicionar o token de autenticação do pacote particular ao arquivo .npmrc no repositório.

No arquivo .npmrc, você precisa definir o escopo do registro do NPM e adicionar o token de autenticação para o pacote particular acessado nesse escopo. Para mais informações sobre arquivos .npmrc, consulte a documentação do npmrc.

O token de autenticação no arquivo .npmrc precisa corresponder ao token de autenticação no secreto enviado para o repositório.

Para adicionar um token de autenticação ao arquivo .npmrc em um repositório do Dataform, siga estas etapas:

  1. No Console do Google Cloud, acesse a página Dataform.

    Acessar o Dataform

  2. Selecione o repositório em que você quer instalar pacotes NPM particulares e selecione um espaço de trabalho.

  3. No painel Files, selecione o arquivo .npmrc.

  4. No arquivo .npmrc, defina o escopo do registro do NPM e o token de autenticação para o pacote privado no seguinte formato:

    @REGISTRY-SCOPE:registry=NPM-REGISTRY-URL
NPM-REGISTRY-URL:_authToken=$AUTHENTICATION-TOKEN

    Substitua:

    • REGISTRY-SCOPE: o escopo do registro do npm ao qual você quer aplicar o token de autenticação.
    • NPM-REGISTRY-URL: o URL do registro do NPM, por exemplo, https://npm.pkg.github.com.
    • AUTHENTICATION-TOKEN: o token de autenticação do pacote NPM privado. O token de autenticação no arquivo .npmrc precisa corresponder ao token de autenticação no segredo enviado. O token de autenticação é fornecido como uma variável de ambiente no arquivo .npmrc. Portanto, adicione os colchetes de abertura ${ e fechamento }.

    É possível inserir vários tokens de autenticação.

O exemplo de código abaixo mostra um token de autenticação para um pacote NPM particular adicionado ao arquivo .npmrc em um repositório do Dataform:

@company:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${AUTHENTICATION_TOKEN}

Autentique um pacote particular subsequente em um repositório do Dataform

Para autenticar um pacote NPM particular em um repositório do Dataform que já contém um segredo com tokens de autenticação de pacote e um arquivo .npmrc, siga estas etapas:

  1. No Secret Manager, list secrets e selecione o secret que armazena tokens de autenticação de pacotes NPM privados do repositório.

  2. Adicione uma nova versão ao secret.

    O Dataform usa a versão mais recente do segredo por padrão.

    1. Adicione o token de autenticação do pacote privado ao valor secreto no seguinte formato:
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    Substitua:

    • AUTHENTICATION_TOKEN_NAME: um nome exclusivo para o token que identifica o pacote que ele autentica.
    • TOKEN_VALUE: o valor do token de autenticação, obtido do registro do NPM.

    É possível adicionar vários tokens de autenticação de uma vez.

  3. No Dataform, adicione o token de autenticação ao arquivo .npmrc no repositório.

Depois de autenticar o pacote NPM particular, você pode instalar o pacote no repositório do Dataform.

Criar um pacote

Esta seção mostra como criar um pacote JavaScript personalizado que pode ser usado para desenvolver fluxos de trabalho no Dataform.

Para criar um pacote que possa ser reutilizado em vários repositórios do Dataform, é necessário criar um repositório do Dataform dedicado ao pacote e conectá-lo a um repositório Git de terceiros para disponibilizá-lo a outros repositórios do Dataform.

Em seguida, crie um arquivo index.js de nível superior e adicione o conteúdo do pacote exportável, como funções e constantes, ao arquivo. Para conferir um exemplo de um pacote criado no Dataform, consulte dataform-package-base no GitHub.

Depois de criar o pacote, você pode instalá-lo em um repositório diferente do Dataform e usar o conteúdo exportável no pacote, como constantes e funções, para desenvolver fluxos de trabalho.

Como alternativa à criação de um pacote, é possível reutilizar funções e constantes do JavaScript em um único repositório do Dataform com inclusões. Para mais informações, consulte Reutilizar variáveis e funções com inclusões no Dataform.

Para criar seu próprio pacote com código JavaScript que pode ser reutilizado no Dataform, siga estas etapas no seu espaço de trabalho:

  1. No painel Files, clique em More.

  2. Selecione Criar arquivo.

    1. No painel Criar novo arquivo, faça o seguinte:

    2. No campo Adicionar um caminho de arquivo, insira index.js.

    3. Selecione Criar arquivo.

  3. No arquivo index.js, insira o código JavaScript que você quer que o pacote exporte.

    1. Crie constantes no seguinte formato:

      const CONSTANT_NAME = CONSTANT_VALUE;
module.exports = { CONSTANT_NAME };

      Substitua:

      • CONSTANT_NAME: o nome da constante
      • CONSTANT_VALUE: o valor da constante.

    2. Crie funções no seguinte formato:

      function FUNCTION_NAME(PARAMETERS) { FUNCTION_BODY }

module.exports = { FUNCTION_NAME }

      Substitua:

      • FUNCTION_NAME: o nome da função.
      • PARAMETERS: os parâmetros da função.
      • FUNCTION_BODY: o código que você quer que a função execute.

  4. Opcional: clique em Formato.

  5. Opcional: no diretório definitions, adicione o código do pacote que não será exportado.

  6. Confirme e envie suas alterações.

O exemplo de código de pacote a seguir mostra o arquivo index.js do pacote postoffice que exporta a função getDomain:

// filename index.js
// package name postoffice

const GENERIC_DOMAINS = "('samplemail.com','samplemail.co.uk','examplemailbox.com'";

function getDomain(email) {
  let cleanEmail = `trim(${email})`
  const domain = `substr(${cleanEmail}, strpos(${cleanEmail}, '@') + 1)`;
  return `case
            when ${domain} in ${common.GENERIC_DOMAINS} then ${cleanEmail}
            when ${domain} = "othermailbox.com" then "other.com"
            when ${domain} = "mailbox.com" then "mailbox.global"
            when ${domain} = "support.postman.com" then "postman.com"
            else ${domain}
          end`;
}

module.exports = { getDomain }

A seguir