Instalar um pacote no Dataform

Este documento mostra como instalar um pacote JavaScript em um repositório do Dataform, 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, você precisa instalá-lo no seu 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 conteúdos selecionados do pacote para o arquivo. Também é possível importar um em 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 que você faça o seguinte:

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

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

Antes de começar

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

    Acessar 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 particular, autenticar o pacote privado.

Funções exigidas

Para ter as permissões necessárias para instalar um pacote, peça ao administrador para conceder a você Papel do IAM Editor do Dataform (roles/dataform.editor) em espaços de trabalho. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

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

Instalar um pacote

Para instalar um pacote dentro de um repositório do Dataform, você precisa 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 painel Arquivos do espaço de trabalho, 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:

      • PACKAGE-NAME pelo nome do pacote.
      • PACKAGE-VERSION pela versão mais recente do um pacote público do NPM publicado. Para evitar problemas com a instalação do pacote, 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 terceiro. repositório de pacotes, 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:

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

  3. Clique em Install packages.

  4. Commit e enviar suas mudanças.

O exemplo de código a seguir mostra o código aberto O pacote de dimensões que mudava lentamente foi 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 de pacote ou constante para um arquivo JavaScript no Dataform

Para usar uma função ou uma constante de um pacote dentro de um arquivo JavaScript em o Dataform, primeiro você precisa importá-lo para o arquivo.

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

  1. No painel Arquivos do espaço de trabalho, selecione um arquivo .js em que 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, declarada em module.exports no arquivo index.js do pacote.
    2. Substitua PACKAGE-NAME pelo nome do do pacote que você quer usar.

  3. Commit e enviar suas mudanças.

O exemplo de código a seguir mostra a função getDomain do Pacote postoffice importado e usado 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 painel Arquivos do espaço de trabalho, selecione um arquivo .js em 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. Commit e enviar suas mudanças.

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 de pacote ou constante para um arquivo SQLX no Dataform

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

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

  1. No painel Arquivos do espaço de trabalho, 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 quer usar, declarada em module.exports no arquivo index.js do pacote.
    2. Substitua PACKAGE-NAME pelo nome do pacote. que você quer usar.

  3. Commit e enviar suas mudanças.

O exemplo de código a seguir mostra a função getDomain do O pacote postoffice foi importado em um bloco js e usado em um 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 painel Arquivos do espaço de trabalho, 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. Commit e enviar suas mudanças.

O exemplo de código a seguir mostra o pacote postoffice importado em um bloco js e a função getDomain dele usada em um 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