Instalar um pacote no Dataform

Este documento mostra como instalar um pacote JavaScript em um repositório do Dataform e importá-lo para um arquivo JavaScript e um arquivo SQLX para usar o pacote no desenvolvimento de fluxos de trabalho SQL 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.

Antes de começar

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

    Acesse a página do Dataform

  2. Selecione ou crie um repositório.

  3. Selecione ou crie um espaço de trabalho de desenvolvimento.

  4. Se o repositório não tiver um arquivo package.json, crie package.json e mova o pacote principal do Dataform.

  5. Opcional: para instalar um pacote privado, autenticar o pacote privado.

Funções exigidas

Para receber as permissões necessárias para instalar um pacote, peça ao administrador que conceda a você o papel do IAM Editor de formulários de dados (roles/dataform.editor) nos espaços de trabalho. 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

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

Para adicionar um pacote como dependência no arquivo package.json, faça o seguinte:

  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 abaixo 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

A seguir