Installare un pacchetto in Dataform

Questo documento mostra come installare un pacchetto JavaScript in un repository Dataform e importarlo in un file JavaScript e in un file SQLX per utilizzarlo per sviluppare flussi di lavoro SQL in Dataform.

Per utilizzare un pacchetto in Dataform, devi installarlo nel tuo repository.

In Dataform puoi installare i seguenti tipi di pacchetti:

Poi, per utilizzare il pacchetto in un file JavaScript o SQLX, devi importare nel file i contenuti selezionati del pacchetto. Puoi anche importare un intero pacchetto in un file JavaScript o SQLX anziché nei relativi contenuti selezionati.

Per evitare problemi di installazione del pacchetto nell'ambiente di produzione, consigliamo di procedere nel seguente modo:

  • Specifica esplicitamente la versione del pacchetto in package.json, ad esempio 3.0.0. Non utilizzare altre opzioni dependencies di package.json, ad esempio >version.

  • Testare le nuove versioni del pacchetto in un ambiente non di produzione. Per ulteriori informazioni sulla configurazione di diversi ambienti del ciclo di vita del codice, consulta la sezione Gestire il ciclo di vita del codice.

Prima di iniziare

  1. Nella console Google Cloud, vai alla pagina Dataform.

    Vai alla pagina Dataform

  2. Seleziona o crea un repository.

  3. Seleziona o crea un'area di lavoro di sviluppo.

  4. Se il tuo repository non contiene un file package.json, crea package.json e sposta il pacchetto principale di Dataform.

  5. (Facoltativo) Per installare un pacchetto privato, autentica il pacchetto privato.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per installare un pacchetto, chiedi all'amministratore di concederti il ruolo IAM Editor di Dataform (roles/dataform.editor) negli spazi di lavoro. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Installare un pacchetto

Per installare un pacchetto in un repository Dataform, devi aggiungerlo come dipendenza nel file package.json.

Per aggiungere un pacchetto come dipendenza nel file package.json:

  1. Nella tua area di lavoro, seleziona package.json nel riquadro File.

  2. Aggiungi il pacchetto al blocco dependencies:

    1. Aggiungi un pacchetto NPM pubblico pubblicato nel seguente formato:

      "PACKAGE-NAME": "PACKAGE-VERSION"

      Sostituisci quanto segue:

      • PACKAGE-NAME con il nome del pacchetto.
      • PACKAGE-VERSION con la versione più recente del pacchetto NPM pubblico pubblicato. Per evitare problemi con l'installazione del pacchetto, specifica esplicitamente la versione, ad esempio 3.0.0.

    2. Aggiungi un pacchetto NPM pubblico non pubblicato nel seguente formato:

      "PACKAGE-NAME": "PACKAGE-URL"

      Sostituisci quanto segue:

      • PACKAGE-NAME con il nome del pacchetto.
      • PACKAGE-URL con l'URL tar.gz del repository del pacchetto di terze parti, ad esempio https://github.com/user/sample-package-repository/archive/master.tar.gz.

    3. Aggiungi un pacchetto NPM privato autenticato nel seguente formato:

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

      Sostituisci quanto segue:

      • REGISTRY-SCOPE con il nome del pacchetto. REGISTRY-SCOPE deve corrispondere all'ambito del registry definito nel file .nmprc nel tuo repository.
      • PACKAGE-NAME con il nome del pacchetto.
      • PACKAGE-URL con l'URL tar.gz del repository del pacchetto, ad esempiohttps://github.com/user/sample-package-repository/archive/master.tar.gz.

  3. Fai clic su Installa pacchetti.

  4. Esegui il commit e push le modifiche.

Il seguente esempio di codice mostra il pacchetto di dimensioni in lenta evoluzione open source pubblico aggiunto al file .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"
   }
 }
 ```

Importare una funzione o una costante del pacchetto in un file JavaScript in Dataform

Per utilizzare una funzione o una costante di un pacchetto all'interno di un file JavaScript in Dataform, devi prima importarla nel file.

Per importare una funzione o una costante da un pacchetto in un file JavaScript:

  1. Nel riquadro File dello spazio di lavoro, seleziona un file .js in cui vuoi utilizzare il pacchetto.

  2. Nel file, importa una funzione o una costante nel seguente formato:

    const { EXPORT-NAME } = require("PACKAGE-NAME");
    1. Sostituisci EXPORT-NAME con il nome della funzione o della costante che vuoi utilizzare, dichiarata in module.exports nel file del pacchetto index.js.
    2. Sostituisci PACKAGE-NAME con il nome del package che vuoi utilizzare.

  3. Esegui il commit e push le modifiche.

Il seguente esempio di codice mostra la funzione getDomain del postoffice pacchetto importata e utilizzata in un file JavaScript:

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

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

Importa un intero pacchetto in un file JavaScript in Dataform

Per importare l'intero pacchetto in un file JavaScript anziché alcune funzioni o costanti in un file JavaScript:

  1. Nel riquadro File dello spazio di lavoro, seleziona un file .js in cui vuoi utilizzare il pacchetto.

  2. Nel file, importa il pacchetto nel seguente formato:

    const CONSTANT-NAME = require("PACKAGE-NAME");
    1. Sostituisci CONSTANT-NAME con un nome per la costante.
    2. Sostituisci PACKAGE-NAME con il nome del pacchetto che vuoi utilizzare.

  3. Esegui il commit e push le modifiche.

Il seguente esempio di codice mostra la funzione getDomain del pacchetto postoffice importato utilizzato in un file JavaScript:

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

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

Importa una funzione o una costante del pacchetto in un file SQLX in Dataform

Per utilizzare una funzione o una costante di un pacchetto all'interno di un file SQLX, devi prima importarla nel file.

Per importare una funzione o una costante da un pacchetto in un file SQLX:

  1. Nel riquadro File dello spazio di lavoro, seleziona un file .sqlx in cui vuoi utilizzare il pacchetto.

  2. Nel file, inserisci il seguente blocco js:

    js {
  const { EXPORT-NAME } = require("PACKAGE-NAME");
}
    1. Sostituisci EXPORT-NAME con il nome della funzione o della costante che vuoi utilizzare, dichiarata in module.exports nel file del pacchetto index.js.
    2. Sostituisci PACKAGE-NAME con il nome del pacchetto che vuoi utilizzare.

  3. Esegui il commit e push le modifiche.

Il seguente esempio di codice mostra la funzione getDomain del postoffice pacchetto importata in un blocco js e utilizzata in un SELECT statement in un file SQLX:

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

config {
    type: "table",
}

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

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

Importare un intero pacchetto in un file SQLX in Dataform

Per importare l'intero pacchetto in un file SQLX anziché in un file JavaScript, segui questi passaggi:

  1. Nel riquadro File dello spazio di lavoro, seleziona un file .sqlx in cui vuoi utilizzare il pacchetto.

  2. Nel file, importa il pacchetto nel seguente formato:

    js {
  const CONSTANT-NAME = require("PACKAGE-NAME");
}
    1. Sostituisci CONSTANT-NAME con un nome per la costante.
    2. Sostituisci PACKAGE-NAME con il nome del pacchetto che vuoi utilizzare.

  3. Esegui il commit e push le modifiche.

Il seguente esempio di codice mostra il pacchetto postoffice importato in un blocco js e la relativa funzione getDomain utilizzata in un'istruzione SELECT in un file SQLX:

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

config {
    type: "table",
}

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

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

Passaggi successivi