Utilizzare i pacchetti JavaScript

Questo documento mostra come:

Prima di iniziare

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

    Vai a Dataform

  2. Esegui una o entrambe le seguenti operazioni:

    1. Per installare un pacchetto in un repository o autenticare un pacchetto NPM privato per abilitarne l'installazione, segui questi passaggi:
      1. Seleziona o crea un repository.
      2. Seleziona o crea un workspace di sviluppo.
      3. (Facoltativo) Per installare un pacchetto privato, autentica il pacchetto privato.
      4. Se il repository non contiene un file package.json, crea package.json e sposta il pacchetto principale Dataform.
      2. Per creare un pacchetto:
      1. Crea un repository Dataform dedicato al tuo pacchetto. Il nome del repository deve corrispondere al nome del pacchetto.
      2. Connetti il repository a un repository Git di terze parti che ospiterà il pacchetto.
      3. Crea e inizializza un workspace nel repository Dataform.

  3. Assicurati di disporre delle autorizzazioni necessarie per completare le attività descritte in questo documento.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per completare le attività descritte in questo documento, chiedi all'amministratore di concederti i seguenti ruoli IAM:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci 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

Questa sezione mostra come installare un pacchetto JavaScript e importarlo in un file JavaScript e in un file SQLX in modo da poter utilizzare il pacchetto per sviluppare flussi di lavoro in Dataform.

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

Puoi installare i seguenti tipi di pacchetti in Dataform:

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

Per evitare problemi con l'installazione dei pacchetti nell'ambiente di produzione, ti consigliamo di procedere nel seguente modo:

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

  • Testare le nuove versioni dei pacchetti in un ambiente non di produzione. Per maggiori informazioni sulla configurazione di diversi ambienti del ciclo di vita del flusso di lavoro, consulta Best practice per il ciclo di vita del flusso di lavoro.

Aggiungere un pacchetto come dipendenza

Per installare un pacchetto all'interno di un repository Dataform, devi aggiungerlo come dipendenza nel file package.json:

  1. Nel workspace, nel riquadro File, seleziona package.json.

  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 l'ultima versione 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 di pacchetti 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 registro definito nel file .nmprc del repository.
      • PACKAGE-NAME con il nome del pacchetto.
      • PACKAGE-URL con l'URL tar.gz del repository del pacchetto, ad esempio https://github.com/user/sample-package-repository/archive/master.tar.gz.

  3. Fai clic su Installa pacchetti.

  4. Esegui il commit e il push delle modifiche.

Il seguente esempio di codice mostra il pacchetto open source pubblico Slowly changing dimensions package 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, segui questi passaggi:

  1. Nello spazio di lavoro, nel riquadro File, 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 pacchetto che vuoi utilizzare.

  3. Esegui il commit e il push delle modifiche.

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

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

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

Importare un intero pacchetto in un file JavaScript in Dataform

Per importare l'intero pacchetto in un file JavaScript anziché importare funzioni o costanti selezionate in un file JavaScript, segui questi passaggi:

  1. Nello spazio di lavoro, nel riquadro File, 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 il push delle 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();

Importare 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, segui questi passaggi:

  1. Nello spazio di lavoro, nel riquadro File, 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 il push delle modifiche.

Il seguente esempio di codice mostra la funzione getDomain del pacchetto postoffice importata in un blocco js e utilizzata in un'istruzione SELECT 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é importare funzioni o costanti selezionate in un file JavaScript, segui questi passaggi:

  1. Nello spazio di lavoro, nel riquadro File, 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 il push delle 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

Autenticare un pacchetto privato

Questa sezione mostra come autenticare un pacchetto npm privato in Dataform per consentirne l'installazione in un repository Dataform.

Per installare un pacchetto npm privato in un repository Dataform e utilizzarlo per sviluppare il flusso di lavoro, devi prima autenticare il pacchetto in Dataform. La procedura di autenticazione è diversa per il primo pacchetto privato in un repository e per un pacchetto privato successivo in un repository.

Autenticare il primo pacchetto privato in un repository Dataform

Per autenticare i pacchetti npm privati in Dataform, devi eseguire le seguenti operazioni prima di installare il primo pacchetto npm privato in un repository Dataform:

  1. Crea un secret di Secret Manager dedicato all'archiviazione dei token di autenticazione dei pacchetti NPM privati nel repository Dataform.

    1. Aggiungi al secret il token di autenticazione del pacchetto ottenuto dal tuo registro NPM.

    Devi archiviare tutti i token di autenticazione dei pacchetti NPM privati in un unico secret nel repository. Devi creare un secret dedicato per ogni repository Dataform. Il secret deve essere in formato JSON.

  2. Carica il secret nel repository Dataform.

  3. Crea un file .npmrc e aggiungi il token di autenticazione del pacchetto al file.

    Il token di autenticazione nel file .npmrc deve corrispondere al token di autenticazione nel secret caricato.

Dopo aver autenticato il pacchetto NPM privato, puoi installarlo nel repository Dataform.

Crea un secret per l'autenticazione di pacchetti privati

Per autenticare i pacchetti npm privati in un repository Dataform, devi creare un secret Secret Manager e definire i token di autenticazione per tutti i pacchetti privati che vuoi installare nel repository Dataform all'interno del secret. Definisci un token di autenticazione per ogni pacchetto NPM privato e memorizza tutti i token di autenticazione in un unico secret per ogni repository. Il secret deve essere in formato JSON.

Per creare un secret con token di autenticazione per pacchetti NPM privati, segui questi passaggi:

  1. In Secret Manager, crea un secret.

    1. Nel campo Valore secret, inserisci uno o più token di autenticazione nel seguente formato:
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    Sostituisci quanto segue:

    • AUTHENTICATION_TOKEN_NAME: un nome univoco per il token che identifica il pacchetto che autentica.
    • TOKEN_VALUE: il valore del token di autenticazione ottenuto dal tuo registro NPM.

  2. Concedi l'accesso al secret al service account Dataform.

    Il account di servizio Dataform ha il seguente formato:

    service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com
    1. Quando concedi l'accesso, assicurati di concedere il ruolo roles/secretmanager.secretAccessor al tuo account di servizio Dataform.

Carica il secret per l'autenticazione dei pacchetti privati in un repository Dataform

Prima di installare un pacchetto NPM privato in un repository Dataform per la prima volta, carica il secret contenente il token di autenticazione del pacchetto nel repository.

Per caricare il secret con i token di autenticazione dei pacchetti NPM privati in un repository Dataform:

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

    Vai a Dataform

  2. Seleziona il repository in cui vuoi installare i pacchetti NPM privati.

  3. Nella pagina del repository, fai clic su Impostazioni > Configura pacchetti NPM privati.

  4. Nel riquadro Aggiungi token del secret del pacchetto di Gestione dei partner di rete, nel menu Secret, seleziona il secret contenente i token di autenticazione per i pacchetti di Gestione dei partner di rete privati.

  5. Fai clic su Salva.

Crea un file .npmrc per l'autenticazione dei pacchetti privati

Per autenticare i pacchetti NPM privati in un repository Dataform, devi creare un file .npmrc di primo livello nel repository. Devi archiviare i token di autenticazione per tutti i pacchetti NPM privati da installare nel repository all'interno del file .npmrc. I token di autenticazione nel file .npmrc devono corrispondere a quelli del secret caricato nel repository. Per saperne di più sui file .npmrc, consulta la documentazione npmrc.

Per creare un file .npmrc di primo livello nel repository:

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

    Vai a Dataform

  2. Seleziona il repository in cui vuoi installare i pacchetti NPM privati e poi seleziona uno spazio di lavoro.

  3. Nel riquadro File, fai clic su Altro e poi su Crea file.

  4. Nel riquadro Crea nuovo file:

    1. Nel campo Aggiungi un percorso del file, inserisci .npmrc.

    2. Fai clic su Crea file.

Aggiungere un token di autenticazione al file .npmrc in un repository Dataform

Per autenticare un pacchetto NPM privato in un repository Dataform che contiene già un secret con token di autenticazione del pacchetto e un file .npmrc, devi aggiungere il token di autenticazione per il pacchetto privato al file .npmrc nel repository.

Nel file .npmrc devi definire l'ambito del tuo registro NPM e aggiungere il token di autenticazione per il pacchetto privato a cui si accede in questo ambito. Per ulteriori informazioni sui file .npmrc, consulta la documentazione di npmrc.

Il token di autenticazione nel file .npmrc deve corrispondere al token di autenticazione nel secret caricato nel repository.

Per aggiungere un token di autenticazione al file .npmrc in un repository Dataform:

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

    Vai a Dataform

  2. Seleziona il repository in cui vuoi installare i pacchetti NPM privati e poi seleziona uno spazio di lavoro.

  3. Nel riquadro File, seleziona il file .npmrc.

  4. Nel file .npmrc, definisci l'ambito del registro NPM e il token di autenticazione per il pacchetto privato nel seguente formato:

    @REGISTRY-SCOPE:registry=NPM-REGISTRY-URL
NPM-REGISTRY-URL:_authToken=$AUTHENTICATION-TOKEN

    Sostituisci quanto segue:

    • REGISTRY-SCOPE: l'ambito del registro NPM a cui vuoi applicare il token di autenticazione.
    • NPM-REGISTRY-URL: l'URL del registro NPM, ad esempio https://npm.pkg.github.com.
    • AUTHENTICATION-TOKEN: il token di autenticazione per il pacchetto NPM privato. Il token di autenticazione nel file .npmrc deve corrispondere al token di autenticazione nel segreto caricato. Il token di autenticazione viene fornito come variabile di ambiente nel file .npmrc, quindi assicurati di aggiungere le parentesi di apertura ${ e di chiusura }.

    Puoi inserire più token di autenticazione.

Il seguente esempio di codice mostra un token di autenticazione per un pacchetto NPM privato aggiunto al file .npmrc in un repository Dataform:

@company:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${AUTHENTICATION_TOKEN}

Autenticare un pacchetto privato successivo in un repository Dataform

Per autenticare un pacchetto npm privato in un repository Dataform che contiene già un secret con token di autenticazione del pacchetto e un file .npmrc, segui questi passaggi:

  1. In Secret Manager, elenca i secret e seleziona il secret che archivia i token di autenticazione dei pacchetti NPM privati del tuo repository.

  2. Aggiungi una nuova versione al secret.

    Dataform utilizza l'ultima versione del secret per impostazione predefinita.

    1. Aggiungi il token di autenticazione per il pacchetto privato al valore del secret nel seguente formato:
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    Sostituisci quanto segue:

    • AUTHENTICATION_TOKEN_NAME: un nome univoco per il token che identifica il pacchetto che autentica.
    • TOKEN_VALUE: il valore del token di autenticazione ottenuto dal tuo registro NPM.

    Puoi aggiungere più token di autenticazione contemporaneamente.

  3. In Dataform, aggiungi il token di autenticazione al file .npmrc nel repository.

Dopo aver autenticato il pacchetto NPM privato, puoi installarlo nel repository Dataform.

Creare un pacchetto

Questa sezione mostra come creare un pacchetto JavaScript personalizzato che puoi utilizzare per sviluppare flussi di lavoro in Dataform.

Per creare un pacchetto riutilizzabile in più repository Dataform, devi creare un repository Dataform dedicato al pacchetto e collegarlo a un repository Git di terze parti per renderlo disponibile ad altri repository Dataform.

Quindi, devi creare un file index.js di primo livello e aggiungere i contenuti del pacchetto esportabile, come funzioni e costanti, al file. Per un esempio di pacchetto creato in Dataform, consulta dataform-package-base su GitHub.

Dopo aver creato il pacchetto, puoi installarlo in un altro repository Dataform e utilizzare i contenuti esportabili del pacchetto, come costanti e funzioni, per sviluppare flussi di lavoro.

In alternativa alla creazione di un pacchetto, puoi riutilizzare le funzioni e le costanti JavaScript in un singolo repository Dataform con gli include. Per saperne di più, vedi Riutilizzare variabili e funzioni con gli include in Dataform.

Per creare un pacchetto personalizzato con codice JavaScript riutilizzabile in Dataform, segui questi passaggi nel tuo workspace:

  1. Nel riquadro File, fai clic su Altro.

  2. Fai clic su Crea file.

    1. Nel riquadro Crea nuovo file:

    2. Nel campo Aggiungi un percorso del file, inserisci index.js.

    3. Fai clic su Crea file.

  3. Nel file index.js, inserisci il codice JavaScript che vuoi esportare dal pacchetto.

    1. Crea costanti nel seguente formato:

      const CONSTANT_NAME = CONSTANT_VALUE;
module.exports = { CONSTANT_NAME };

      Sostituisci quanto segue:

      • CONSTANT_NAME: il nome della costante
      • CONSTANT_VALUE: il valore della costante

    2. Crea funzioni nel seguente formato:

      function FUNCTION_NAME(PARAMETERS) { FUNCTION_BODY }

module.exports = { FUNCTION_NAME }

      Sostituisci quanto segue:

      • FUNCTION_NAME: il nome della funzione.
      • PARAMETERS: i parametri della funzione.
      • FUNCTION_BODY: il codice che vuoi che la funzione esegua.

  4. (Facoltativo) Fai clic su Formato.

  5. (Facoltativo) Nella directory definitions, aggiungi il codice del pacchetto che non verrà esportato.

  6. Esegui il commit e il push delle modifiche.

Il seguente esempio di codice del pacchetto mostra il file index.js del pacchetto postoffice che esporta la funzione getDomain:

// filename index.js
// package name postoffice

const GENERIC_DOMAINS = "('samplemail.com','samplemail.co.uk','examplemailbox.com'";

function getDomain(email) {
  let cleanEmail = `trim(${email})`
  const domain = `substr(${cleanEmail}, strpos(${cleanEmail}, '@') + 1)`;
  return `case
            when ${domain} in ${common.GENERIC_DOMAINS} then ${cleanEmail}
            when ${domain} = "othermailbox.com" then "other.com"
            when ${domain} = "mailbox.com" then "mailbox.global"
            when ${domain} = "support.postman.com" then "postman.com"
            else ${domain}
          end`;
}

module.exports = { getDomain }

Passaggi successivi