Use pacotes JavaScript

Este documento mostra como fazer o seguinte:

Antes de começar

  1. Na Google Cloud consola, aceda à página Dataform.

    Aceder ao Dataform

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

    1. Para instalar um pacote num repositório ou autenticar um pacote NPM privado para permitir a respetiva instalação, siga estes passos:
      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, autentique o pacote privado.
      4. Se o seu repositório não contiver um ficheiro package.json, crie um ficheiro package.json e mova o pacote principal do Dataform.
    2. Para criar um pacote, siga estes passos:
      1. Crie um repositório do Dataform dedicado ao seu pacote. Faça corresponder o nome do repositório ao nome do seu pacote.
      2. Associe o repositório a um repositório Git de terceiros que vai alojar o seu pacote.
      3. Crie e inicialize um espaço de trabalho no repositório do Dataform.

  3. Certifique-se de que tem as autorizações necessárias para concluir as tarefas neste documento.

Funções necessárias

Para receber as autorizações de que precisa para concluir as tarefas neste documento, peça ao seu administrador que lhe conceda as seguintes funções da IAM:

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Instale um pacote

Esta secção mostra como instalar um pacote JavaScript e importá-lo para um ficheiro JavaScript e um ficheiro SQLX, para que possa usar o pacote para desenvolver fluxos de trabalho no Dataform.

Para usar um pacote no Dataform, tem de o instalar no seu repositório.

Pode instalar os seguintes tipos de pacotes no Dataform:

Em seguida, para usar o pacote num ficheiro JavaScript ou SQLX, tem de importar o conteúdo selecionado do pacote para o ficheiro. Também pode importar um pacote completo para um ficheiro JavaScript ou SQLX em vez dos respetivos conteúdos selecionados.

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

Adicione um pacote como dependência

Para instalar um pacote num repositório do Dataform, tem de o adicionar como uma dependência no ficheiro package.json:

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

  2. Adicione o pacote ao bloco dependencies:

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

      "PACKAGE-NAME": "PACKAGE-VERSION"

      Substitua o seguinte:

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

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

      "PACKAGE-NAME": "PACKAGE-URL"

      Substitua o seguinte:

      • PACKAGE-NAME com o nome do pacote.
      • PACKAGE-URL com o 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 privado autenticado no seguinte formato:

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

      Substitua o seguinte:

      • REGISTRY-SCOPE com o nome do pacote. REGISTRY-SCOPE tem de corresponder ao âmbito do registo definido no ficheiro .nmprc no seu repositório.
      • PACKAGE-NAME com o nome do pacote.
      • PACKAGE-URL com o URL do repositório de pacotes tar.gz, por exemplo, https://github.com/user/sample-package-repository/archive/master.tar.gz.

  3. Clique em Instalar pacotes.

  4. Confirme e envie as alterações.

O exemplo de código seguinte mostra o pacote de dimensões que mudam lentamente de código aberto público adicionado ao ficheiro .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"
   }
 }
 ```

Importe uma função ou uma constante de pacote para um ficheiro JavaScript no Dataform

Para usar uma função ou uma constante de um pacote num ficheiro JavaScript no Dataform, primeiro tem de a importar para o ficheiro.

Para importar uma função ou uma constante de um pacote para um ficheiro JavaScript, siga estes passos:

  1. No espaço de trabalho, no painel Ficheiros, selecione um ficheiro .js no qual quer usar o pacote.

  2. No ficheiro, 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 da constante que quer usar, declarada em module.exports no ficheiro index.js do pacote.
    2. Substitua PACKAGE-NAME pelo nome do pacote que quer usar.

  3. Confirme e envie as alterações.

O exemplo de código seguinte mostra a função getDomain do pacote postoffice importada e usada num ficheiro JavaScript:

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

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

Importe um pacote completo para um ficheiro JavaScript no Dataform

Para importar todo o pacote para um ficheiro JavaScript em vez de importar funções ou constantes selecionadas para um ficheiro JavaScript, siga estes passos:

  1. No espaço de trabalho, no painel Ficheiros, selecione um ficheiro .js no qual quer usar o pacote.

  2. No ficheiro, 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 quer usar.

  3. Confirme e envie as alterações.

O exemplo de código seguinte mostra a função getDomain do pacote postoffice importado usado num ficheiro JavaScript:

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

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

Importe uma função ou uma constante de pacote para um ficheiro SQLX no Dataform

Para usar uma função ou uma constante de um pacote num ficheiro SQLX, primeiro tem de a importar para o ficheiro.

Para importar uma função ou uma constante de um pacote para um ficheiro SQLX, siga estes passos:

  1. No seu espaço de trabalho, no painel Ficheiros, selecione um ficheiro .sqlx no qual quer usar o pacote.

  2. No ficheiro, introduza o seguinte bloco js:

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

  3. Confirme e envie as alterações.

O exemplo de código seguinte mostra a função getDomain do pacote postoffice importado num bloco js e usado numa declaração SELECT num ficheiro SQLX:

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

config {
    type: "table",
}

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

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

Importe um pacote completo para um ficheiro SQLX no Dataform

Para importar todo o pacote para um ficheiro SQLX em vez de importar funções ou constantes selecionadas para um ficheiro JavaScript, siga estes passos:

  1. No seu espaço de trabalho, no painel Ficheiros, selecione um ficheiro .sqlx no qual quer usar o pacote.

  2. No ficheiro, 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 quer usar.

  3. Confirme e envie as alterações.

O exemplo de código seguinte mostra o pacote postoffice importado num bloco js e a respetiva função getDomain usada numa declaração SELECT num ficheiro SQLX:

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

config {
    type: "table",
}

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

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

Autentique um pacote privado

Esta secção mostra como autenticar um pacote NPM privado no Dataform para permitir a respetiva instalação num repositório do Dataform.

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

Autentique o primeiro pacote privado num repositório do Dataform

Para autenticar pacotes NPM privados no Dataform, tem de fazer o seguinte antes de instalar o primeiro pacote NPM privado num repositório do Dataform:

  1. Crie um Secret do Secret Manager dedicado ao armazenamento de tokens de autenticação de pacotes NPM privados no repositório do Dataform.

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

    Tem de armazenar todos os tokens de autenticação dos pacotes NPM privados no seu repositório num único segredo. Tem de criar um segredo dedicado por repositório do Dataform. O segredo tem de estar no formato JSON.

  2. Carregue o segredo para o repositório do Dataform.

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

    O token de autenticação no ficheiro .npmrc tem de corresponder ao token de autenticação no segredo carregado.

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

Crie um segredo para a autenticação de pacotes privados

Para autenticar pacotes NPM privados num repositório do Dataform, tem de criar um segredo do Secret Manager e definir tokens de autenticação para todos os pacotes privados que quer instalar no repositório do Dataform no segredo. Defina um símbolo de autenticação para cada pacote NPM privado e armazene todos os símbolos de autenticação num único segredo para cada repositório. O segredo tem de estar no formato JSON.

Para criar um segredo com tokens de autenticação para pacotes NPM privados, siga estes passos:

  1. No Secret Manager, crie um segredo.

    1. No campo Valor secreto, introduza um ou vários tokens de autenticação no seguinte formato:
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    Substitua o seguinte:

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

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

    A sua conta de serviço do Dataform está no seguinte formato:

    service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com
    1. Ao conceder acesso, certifique-se de que concede a função roles/secretmanager.secretAccessor à sua conta de serviço do Dataform.

Carregue o segredo para a autenticação de pacotes privados num repositório do Dataform

Antes de instalar um pacote NPM privado num repositório do Dataform pela primeira vez, carregue o seu segredo que contém o token de autenticação do pacote para o repositório.

Para carregar o segredo com tokens de autenticação de pacotes NPM privados para um repositório do Dataform, siga estes passos:

  1. Na Google Cloud consola, aceda à página Dataform.

    Aceder ao Dataform

  2. Selecione o repositório no qual quer instalar pacotes NPM privados.

  3. Na página do repositório, clique em Definições > Configurar pacotes NPM privados.

  4. No painel Adicionar token secreto do pacote NPM, no menu Secreto, selecione o seu segredo que contém tokens de autenticação para pacotes NPM privados.

  5. Clique em Guardar.

Crie um ficheiro .npmrc para a autenticação de pacotes privados

Para autenticar pacotes NPM privados num repositório do Dataform, tem de criar um ficheiro .npmrc de nível superior no repositório. Tem de armazenar tokens de autenticação para todos os pacotes NPM privados a serem instalados no repositório no ficheiro .npmrc. Os tokens de autenticação no ficheiro .npmrc têm de corresponder aos tokens de autenticação no segredo carregado para o repositório. Para mais informações acerca dos ficheiros .npmrc, consulte a documentação npmrc.

Para criar um ficheiro de nível superior .npmrc no seu repositório, siga estes passos:

  1. Na Google Cloud consola, aceda à página Dataform.

    Aceder ao Dataform

  2. Selecione o repositório no qual quer instalar pacotes NPM privados e, em seguida, selecione um espaço de trabalho.

  3. No painel Ficheiros, clique em Mais e, de seguida, clique em Criar ficheiro.

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

    1. No campo Adicionar um caminho de ficheiro, introduza .npmrc.

    2. Clique em Criar ficheiro.

Adicione um token de autenticação ao ficheiro .npmrc num repositório do Dataform

Para autenticar um pacote NPM privado num repositório do Dataform que já contenha um segredo com tokens de autenticação de pacotes e um ficheiro .npmrc, tem de adicionar o token de autenticação do pacote privado ao ficheiro .npmrc no repositório.

No ficheiro .npmrc, tem de definir o âmbito do seu registo do NPM e adicionar o token de autenticação para o pacote privado acedido nesse âmbito. Para mais informações sobre os ficheiros .npmrc, consulte a documentação npmrc.

O token de autenticação no ficheiro .npmrc tem de corresponder ao token de autenticação no segredo carregado para o repositório.

Para adicionar um token de autenticação ao ficheiro .npmrc num repositório do Dataform, siga estes passos:

  1. Na Google Cloud consola, aceda à página Dataform.

    Aceder ao Dataform

  2. Selecione o repositório no qual quer instalar pacotes NPM privados e, em seguida, selecione um espaço de trabalho.

  3. No painel Ficheiros, selecione o ficheiro .npmrc.

  4. No ficheiro .npmrc, defina o âmbito do registo 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 o seguinte:

    • REGISTRY-SCOPE: o âmbito do registo do NPM ao qual quer aplicar o token de autenticação.
    • NPM-REGISTRY-URL: o URL do seu registo do NPM, por exemplo, https://npm.pkg.github.com.
    • AUTHENTICATION-TOKEN: o token de autenticação para o pacote NPM privado. O token de autenticação no ficheiro .npmrc tem de corresponder ao token de autenticação no segredo carregado. O token de autenticação é fornecido como uma variável de ambiente no ficheiro .npmrc, por isso, certifique-se de que adiciona os parênteses de abertura ${ e de fecho }.

    Pode introduzir vários tokens de autenticação.

O exemplo de código seguinte mostra um token de autenticação para um pacote NPM privado adicionado ao ficheiro .npmrc num repositório do Dataform:

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

Autentique um pacote privado subsequente num repositório do Dataform

Para autenticar um pacote NPM privado num repositório do Dataform que já contém um segredo com tokens de autenticação de pacotes e um ficheiro .npmrc, siga estes passos:

  1. No Secret Manager, liste os segredos e selecione o segredo que armazena tokens de autenticação de pacotes NPM privados do seu repositório.

  2. Adicione uma nova versão ao segredo.

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

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

    Substitua o seguinte:

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

    Pode adicionar vários tokens de autenticação em simultâneo.

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

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

Crie um pacote

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

Para criar um pacote que possa reutilizar em vários repositórios do Dataform, tem de criar um repositório do Dataform dedicado ao pacote e associá-lo a um repositório Git de terceiros para o disponibilizar a outros repositórios do Dataform.

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

Depois de criar o pacote, pode instalá-lo num repositório do Dataform diferente e usar os conteúdos exportáveis no pacote, como constantes e funções, para desenvolver fluxos de trabalho.

Em alternativa à criação de um pacote, pode reutilizar funções e constantes JavaScript num único repositório do Dataform com inclusões. Para mais informações, consulte o artigo Reutilize variáveis e funções com inclusões no Dataform.

Para criar o seu próprio pacote com código JavaScript que pode reutilizar no Dataform, siga estes passos no seu espaço de trabalho:

  1. No painel Ficheiros, clique em Mais.

  2. Clique em Criar ficheiro.

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

    2. No campo Adicionar um caminho de ficheiro, introduza index.js.

    3. Clique em Criar ficheiro.

  3. No ficheiro index.js, introduza o código JavaScript que quer que o seu pacote exporte.

    1. Crie constantes no seguinte formato:

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

      Substitua o seguinte:

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

    2. Crie funções no seguinte formato:

      function FUNCTION_NAME(PARAMETERS) { FUNCTION_BODY }

module.exports = { FUNCTION_NAME }

      Substitua o seguinte:

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

  4. Opcional: clique em Formatar.

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

  6. Confirme e envie as alterações.

O seguinte exemplo de código do pacote mostra o ficheiro 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 }

O que se segue?