Usar pacotes JavaScript

Esta página mostra como fazer o seguinte:

Antes de começar

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

    Acesse o Dataform

  2. Faça uma ou as duas ações a seguir:

    1. Para instalar um pacote em um repositório ou autenticar um pacote NPM privado 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 particular, autentique o pacote.
      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. Faça o nome do repositório corresponder ao nome do pacote.
      2. Conecte o repositório a um repositório Git de terceiros que vai hospedar seu pacote.
      3. Crie e inicialize um espaço de trabalho no repositório do Dataform.

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

Funções exigidas

Para conseguir as permissões necessárias a fim de 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 usando papéis personalizados ou outros papéis predefinidos.

Instalar um pacote

Esta seção mostra como instalar e importar um pacote JavaScript para um arquivo JavaScript e um arquivo SQLX. Assim, você pode usar o pacote para desenvolver fluxos de trabalho no Dataform.

Para usar um pacote no Dataform, instale-o 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, importe 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 que você faça o seguinte:

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, no painel Arquivos, 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 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 público do NPM não publicado no seguinte formato:

      "PACKAGE-NAME": "PACKAGE-URL"

      Substitua:

      • 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 particular autenticado no seguinte formato:

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

      Substitua:

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

  3. Clique em Instalar pacotes.

  4. Confirme e envie suas mudanças.

O exemplo de código a seguir mostra o pacote público de código aberto Slowly changing dimensions 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 constante de um pacote em um arquivo JavaScript no Dataform, primeiro importe 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 Arquivos, 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, declarada em module.exports no arquivo do pacote index.js.
    2. Substitua PACKAGE-NAME pelo nome do pacote que você quer usar.

  3. Confirme e envie suas mudanças.

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 espaço de trabalho, no painel Arquivos, 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 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 ou constante de pacote para um arquivo SQLX no Dataform

Para usar uma função ou constante de um pacote em um arquivo SQLX, primeiro importe 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 Arquivos, 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, declarada em module.exports no arquivo do pacote index.js.
    2. Substitua PACKAGE-NAME pelo nome do pacote que você quer usar.

  3. Confirme e envie suas mudanças.

O exemplo de código a seguir 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 {