Utilizzare i pacchetti JavaScript

Questo documento illustra 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 consentirne l'installazione:
      1. Seleziona o crea un repository.
      2. Seleziona o crea un'area di lavoro di sviluppo.
      3. (Facoltativo) Per installare un pacchetto privato, autentica il pacchetto privato.
      4. Se il tuo repository non contiene un file package.json, crea package.json e sposta il pacchetto Dataform core.
    2. Per creare un pacchetto:
      1. Crea un repository Dataform dedicato al tuo pacchetto. Abbina il nome del repository al nome del pacchetto.
      2. Collega il repository a un repository Git di terze parti che ospiterà il tuo pacchetto.
      3. Crea e inizializza uno spazio di lavoro 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à in questo documento, chiedi all'amministratore di concederti i seguenti ruoli IAM:

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

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.

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.

Aggiungere un pacchetto come dipendenza

Per installare un pacchetto in un repository Dataform, devi aggiungerlo 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

Autentica 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 tuo 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 quanto segue prima di installare il primo pacchetto npm privato in un repository Dataform:

  1. Crea un secret di Secret Manager dedicato allo stoccaggio dei token di autenticazione dei pacchetti NPM privati nel repository Dataform.

    1. Aggiungi al secret il token di autenticazione del pacchetto, ottenuto dal registry NPM.

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

  2. Carica il secret nel repository Dataform.

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

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

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

Crea un segreto per l'autenticazione dei pacchetti privati

Per autenticare i pacchetti NPM privati in un repository Dataform, devi creare un secret di 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 singolo segreto per ogni repository. Il secret deve essere in formato JSON.

Per creare un secret con token di autenticazione per i 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 registry NPM.

  2. Concedi l'accesso al secret al tuo account di servizio Dataform.

    Il tuo 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 nel repository il secret contenente il token di autenticazione del pacchetto.

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 i 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.

Creare 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 memorizzare i token di autenticazione per tutti i pacchetti NPM privati da installare nel repository all'interno del file .npmrc. I token di autenticazione nel .npmrc file devono corrispondere ai token di autenticazione nel secret caricato nel repository. Per ulteriori informazioni sui file .npmrc, consulta la documentazione di 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, quindi 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 del pacchetto privato al file .npmrc nel repository.

Nel file .npmrc, devi definire l'ambito del tuo registry NPM e aggiungere il token di autenticazione per il pacchetto privato a cui hai eseguito l'accesso in quell'ambito. Per ulteriori informazioni sui file .npmrc, consulta la documentazione 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, quindi seleziona uno spazio di lavoro.

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

  4. Nel file .npmrc, definisci l'ambito del registry 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 registry NPM a cui vuoi applicare il token di autenticazione.
    • NPM-REGISTRY-URL: l'URL del registry 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 memorizza i token di autenticazione dei pacchetti NPM privati del tuo repository.

  2. Aggiungi una nuova versione al secret.

    Per impostazione predefinita, Dataform utilizza la versione più recente del secret.

    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 registry NPM.

    Puoi aggiungere più token di autenticazione contemporaneamente.

  3. In Dataform, aggiungi il token di autenticazione al file .npmrc nel tuo 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 da utilizzare per sviluppare flussi di lavoro in Dataform.

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

Poi, devi creare un file index.js di primo livello e aggiungere i contenuti del pacchetto esportabili, come funzioni e costanti. Per un esempio di un 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 unico repository Dataform con gli include. Per ulteriori informazioni, consulta Riutilizzare variabili e funzioni con gli include in Dataform.

Per creare il tuo pacchetto con codice JavaScript che puoi riutilizzare in Dataform, segui questi passaggi nella tua area di lavoro:

  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 nel pacchetto.

    1. Crea le 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 le 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 push le modifiche.

Il seguente esempio di codice del pacchetto mostra il file index.js del postoffice pacchetto 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