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. Opcional: para instalar um pacote particular, autenticar o pacote privado.

Funções exigidas

Para ter as permissões necessárias para importar 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 em um repositório do Dataform

Para instalar um pacote dentro de um repositório do Dataform, você precisa adicione-o como uma dependência no arquivo package.json. O formato da dependência definição no arquivo package.json depende do tipo do pacote. Se você não tem um arquivo package.json porque seu arquivo workflow_settings.yaml especificar seu dataformCoreVersion, remova o dataformCoreVersion de workflow_settings.yaml, depois crie um arquivo package.json e adicione @dataform/core como dependência.

Para instalar um pacote em um repositório do Dataform, siga estas etapas:

  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 envie as 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 envie as 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 envie as 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 envie as 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 envie as 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