Utiliser des packages JavaScript

Ce document vous explique comment :

Avant de commencer

  1. Dans la console Google Cloud , accédez à la page Dataform.

    Accéder à Dataform

  2. Effectuez l'une des opérations suivantes ou les deux :

    1. Pour installer un package dans un dépôt ou authentifier un package NPM privé afin de permettre son installation, procédez comme suit :
      1. Sélectionnez ou créez un dépôt.
      2. Sélectionnez ou créez un espace de travail de développement.
      3. Facultatif : Pour installer un package privé, authentifiez-le.
      4. Si votre dépôt ne contient pas de fichier package.json, créez package.json et déplacez le package Dataform Core.
    2. Pour créer un package, procédez comme suit :
      1. Créez un dépôt Dataform dédié à votre package. Faites correspondre le nom du dépôt à celui de votre package.
      2. Connectez le dépôt à un dépôt Git tiers qui hébergera votre package.
      3. Créez et initialisez un espace de travail dans le dépôt Dataform.

  3. Assurez-vous de disposer des autorisations nécessaires pour effectuer les tâches décrites dans ce document.

Rôles requis

Pour obtenir les autorisations nécessaires pour effectuer les tâches décrites dans ce document, demandez à votre administrateur de vous accorder les rôles IAM suivants :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Installer un package

Cette section vous explique comment installer un package JavaScript et l'importer dans un fichier JavaScript et un fichier SQLX afin de pouvoir utiliser le package pour développer des workflows dans Dataform.

Pour utiliser un package dans Dataform, vous devez l'installer dans votre dépôt.

Vous pouvez installer les types de packages suivants dans Dataform :

Ensuite, pour utiliser le package dans un fichier JavaScript ou SQLX, vous devez importer le contenu sélectionné du package dans le fichier. Vous pouvez également importer un package entier dans un fichier JavaScript ou SQLX au lieu de son contenu sélectionné.

Pour éviter tout problème d'installation de packages dans votre environnement de production, nous vous recommandons de procéder comme suit :

  • Spécifiez explicitement la version du package dans package.json, par exemple 3.0.0. N'utilisez pas d'autres options dependencies de package.json, par exemple >version.

  • Testez les nouvelles versions de package dans un environnement hors production. Pour en savoir plus sur la configuration de différents environnements de cycle de vie de workflow, consultez Bonnes pratiques pour le cycle de vie des workflows.

Ajouter un package en tant que dépendance

Pour installer un package dans un dépôt Dataform, vous devez l'ajouter en tant que dépendance dans le fichier package.json :

  1. Dans votre espace de travail, dans le volet Fichiers, sélectionnez package.json.

  2. Ajoutez le package au bloc dependencies :

    1. Ajoutez un package NPM public publié au format suivant :

      "PACKAGE-NAME": "PACKAGE-VERSION"

      Remplacez les éléments suivants :

      • PACKAGE-NAME par le nom du package.
      • PACKAGE-VERSION avec la dernière version du package NPM public publié. Pour éviter les problèmes d'installation des packages, spécifiez explicitement la version, par exemple 3.0.0.

    2. Ajoutez un package NPM public non publié au format suivant :

      "PACKAGE-NAME": "PACKAGE-URL"

      Remplacez les éléments suivants :

      • PACKAGE-NAME par le nom du package.
      • PACKAGE-URL par l'URL tar.gz du dépôt de packages tiers, par exemple https://github.com/user/sample-package-repository/archive/master.tar.gz.

    3. Ajoutez un package NPM privé authentifié au format suivant :

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

      Remplacez les éléments suivants :

      • REGISTRY-SCOPE par le nom du package. REGISTRY-SCOPE doit correspondre au champ d'application du registre défini dans le fichier .nmprc de votre dépôt.
      • PACKAGE-NAME par le nom du package.
      • PACKAGE-URL par l'URL tar.gz du dépôt de packages, par exemple https://github.com/user/sample-package-repository/archive/master.tar.gz.

  3. Cliquez sur Installer les packages.

  4. Validez et transférez vos modifications.

L'exemple de code suivant montre le package de dimensions à évolution lente open source public ajouté au fichier .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"
   }
 }
 ```

Importer une fonction ou une constante de package dans un fichier JavaScript dans Dataform

Pour utiliser une fonction ou une constante d'un package dans un fichier JavaScript dans Dataform, vous devez d'abord l'importer dans le fichier.

Pour importer une fonction ou une constante d'un package dans un fichier JavaScript, procédez comme suit :

  1. Dans votre espace de travail, dans le volet Fichiers, sélectionnez un fichier .js dans lequel vous souhaitez utiliser le package.

  2. Dans le fichier, importez une fonction ou une constante au format suivant :

    const { EXPORT-NAME } = require("PACKAGE-NAME");
    1. Remplacez EXPORT-NAME par le nom de la fonction ou de la constante que vous souhaitez utiliser, déclarée dans module.exports dans le fichier de package index.js.
    2. Remplacez PACKAGE-NAME par le nom du package que vous souhaitez utiliser.

  3. Validez et transférez vos modifications.

L'exemple de code suivant montre la fonction getDomain du package postoffice importée et utilisée dans un fichier JavaScript :

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

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

Importer un package entier dans un fichier JavaScript dans Dataform

Pour importer l'intégralité du package dans un fichier JavaScript au lieu d'importer des fonctions ou des constantes sélectionnées dans un fichier JavaScript, procédez comme suit :

  1. Dans votre espace de travail, dans le volet Fichiers, sélectionnez un fichier .js dans lequel vous souhaitez utiliser le package.

  2. Dans le fichier, importez le package au format suivant :

    const CONSTANT-NAME = require("PACKAGE-NAME");
    1. Remplacez CONSTANT-NAME par le nom de la constante.
    2. Remplacez PACKAGE-NAME par le nom du package que vous souhaitez utiliser.

  3. Validez et transférez vos modifications.

L'exemple de code suivant montre la fonction getDomain du package postoffice importé utilisé dans un fichier JavaScript :

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

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

Importer une fonction ou une constante de package dans un fichier SQLX dans Dataform

Pour utiliser une fonction ou une constante d'un package dans un fichier SQLX, vous devez d'abord l'importer dans le fichier.

Pour importer une fonction ou une constante d'un package dans un fichier SQLX, procédez comme suit :

  1. Dans votre espace de travail, dans le volet Fichiers, sélectionnez un fichier .sqlx dans lequel vous souhaitez utiliser le package.

  2. Dans le fichier, saisissez le bloc js suivant :

    js {
  const { EXPORT-NAME } = require("PACKAGE-NAME");
}
    1. Remplacez EXPORT-NAME par le nom de la fonction ou de la constante que vous souhaitez utiliser, déclarée dans module.exports dans le fichier de package index.js.
    2. Remplacez PACKAGE-NAME par le nom du package que vous souhaitez utiliser.

  3. Validez et transférez vos modifications.

L'exemple de code suivant montre la fonction getDomain du package postoffice importée dans un bloc js et utilisée dans une instruction SELECT dans un fichier SQLX :

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

config {
    type: "table",
}

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

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

Importer un package entier dans un fichier SQLX dans Dataform

Pour importer l'intégralité du package dans un fichier SQLX au lieu d'importer des fonctions ou des constantes sélectionnées dans un fichier JavaScript, procédez comme suit :

  1. Dans votre espace de travail, dans le volet Fichiers, sélectionnez un fichier .sqlx dans lequel vous souhaitez utiliser le package.

  2. Dans le fichier, importez le package au format suivant :

    js {
  const CONSTANT-NAME = require("PACKAGE-NAME");
}
    1. Remplacez CONSTANT-NAME par le nom de la constante.
    2. Remplacez PACKAGE-NAME par le nom du package que vous souhaitez utiliser.

  3. Validez et transférez vos modifications.

L'exemple de code suivant montre le package postoffice importé dans un bloc js et sa fonction getDomain utilisée dans une instruction SELECT d'un fichier SQLX :

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

config {
    type: "table",
}

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

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

Authentifier un package privé

Cette section explique comment authentifier un package npm privé dans Dataform pour permettre son installation dans un dépôt Dataform.

Pour installer un package npm privé dans un dépôt Dataform et l'utiliser pour développer votre workflow, vous devez d'abord authentifier le package dans Dataform. Le processus d'authentification est différent pour le premier package privé d'un dépôt et pour un package privé ultérieur d'un dépôt.

Authentifier le premier package privé dans un dépôt Dataform

Pour authentifier des packages NPM privés dans Dataform, vous devez effectuer les opérations suivantes avant d'installer le premier package NPM privé dans un dépôt Dataform :

  1. Créez un secret Secret Manager dédié au stockage des jetons d'authentification des packages NPM privés dans le dépôt Dataform.

    1. Ajoutez le jeton d'authentification du package, obtenu à partir de votre registre NPM, au secret.

    Vous devez stocker tous les jetons d'authentification des packages npm privés de votre dépôt dans un seul secret. Vous devez créer un secret dédié par dépôt Dataform. Le secret doit être au format JSON.

  2. Importez le secret dans le dépôt Dataform.

  3. Créez un fichier .npmrc et ajoutez-y le jeton d'authentification du package.

    Le jeton d'authentification du fichier .npmrc doit correspondre à celui du secret importé.

Une fois le package NPM privé authentifié, vous pouvez l'installer dans le dépôt Dataform.

Créer un secret pour l'authentification des packages privés

Pour authentifier des packages npm privés dans un dépôt Dataform, vous devez créer un secret Secret Manager et définir des jetons d'authentification pour tous les packages privés que vous souhaitez installer dans le dépôt Dataform à l'intérieur du secret. Définissez un jeton d'authentification pour chaque package NPM privé et stockez tous les jetons d'authentification dans un seul secret pour chaque dépôt. Le secret doit être au format JSON.

Pour créer un secret avec des jetons d'authentification pour les packages NPM privés, procédez comme suit :

  1. Dans Secret Manager, créez un secret.

    1. Dans le champ Valeur du secret, saisissez un ou plusieurs jetons d'authentification au format suivant :
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    Remplacez les éléments suivants :

    • AUTHENTICATION_TOKEN_NAME : nom unique du jeton qui identifie le package qu'il authentifie.
    • TOKEN_VALUE : valeur du jeton d'authentification obtenu auprès de votre registre NPM.

  2. Accordez l'accès au secret à votre compte de service Dataform.

    Votre compte de service Dataform est au format suivant :

    service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com
    1. Lorsque vous accordez l'accès, assurez-vous d'attribuer le rôle roles/secretmanager.secretAccessor à votre compte de service Dataform.

Importer le secret pour l'authentification des packages privés dans un dépôt Dataform

Avant d'installer un package NPM privé dans un dépôt Dataform pour la première fois, importez dans le dépôt votre secret contenant le jeton d'authentification du package.

Pour importer le secret contenant les jetons d'authentification des packages npm privés dans un dépôt Dataform, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Dataform.

    Accéder à Dataform

  2. Sélectionnez le dépôt dans lequel vous souhaitez installer les packages NPM privés.

  3. Sur la page du dépôt, cliquez sur Paramètres > Configurer les packages NPM privés.

  4. Dans le volet Ajouter un jeton secret pour les packages npm, dans le menu Secret, sélectionnez votre secret contenant les jetons d'authentification pour les packages npm privés.

  5. Cliquez sur Enregistrer.

Créer un fichier .npmrc pour l'authentification des packages privés

Pour authentifier des packages NPM privés dans un dépôt Dataform, vous devez créer un fichier .npmrc de premier niveau dans le dépôt. Vous devez stocker les jetons d'authentification de tous les packages NPM privés à installer dans le dépôt à l'intérieur du fichier .npmrc. Les jetons d'authentification du fichier .npmrc doivent correspondre à ceux du secret importé dans le dépôt. Pour en savoir plus sur les fichiers .npmrc, consultez la documentation npmrc.

Pour créer un fichier .npmrc de premier niveau dans votre dépôt, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Dataform.

    Accéder à Dataform

  2. Sélectionnez le dépôt dans lequel vous souhaitez installer les packages NPM privés, puis sélectionnez un espace de travail.

  3. Dans le volet Fichiers, cliquez sur Plus, puis sur Créer un fichier.

  4. Dans le volet Créer un fichier, procédez comme suit :

    1. Dans le champ Ajouter un chemin d'accès au fichier, saisissez .npmrc.

    2. Cliquez sur Créer un fichier.

Ajouter un jeton d'authentification au fichier .npmrc dans un dépôt Dataform

Pour authentifier un package npm privé dans un dépôt Dataform qui contient déjà un secret avec des jetons d'authentification de package et un fichier .npmrc, vous devez ajouter le jeton d'authentification du package privé au fichier .npmrc du dépôt.

Dans le fichier .npmrc, vous devez définir le champ d'application de votre registre NPM et ajouter le jeton d'authentification pour le package privé accessible dans ce champ d'application. Pour en savoir plus sur les fichiers .npmrc, consultez la documentation npmrc.

Le jeton d'authentification du fichier .npmrc doit correspondre à celui du secret importé dans le dépôt.

Pour ajouter un jeton d'authentification au fichier .npmrc dans un dépôt Dataform, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Dataform.

    Accéder à Dataform

  2. Sélectionnez le dépôt dans lequel vous souhaitez installer les packages NPM privés, puis sélectionnez un espace de travail.

  3. Dans le volet Fichiers, sélectionnez le fichier .npmrc.

  4. Dans le fichier .npmrc, définissez le champ d'application du registre NPM et le jeton d'authentification pour le package privé au format suivant :

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

    Remplacez les éléments suivants :

    • REGISTRY-SCOPE : champ d'application du registre NPM auquel vous souhaitez appliquer le jeton d'authentification.
    • NPM-REGISTRY-URL : URL de votre registre NPM, par exemple https://npm.pkg.github.com.
    • AUTHENTICATION-TOKEN : jeton d'authentification pour le package NPM privé. Le jeton d'authentification du fichier .npmrc doit correspondre à celui du secret importé. Le jeton d'authentification est fourni en tant que variable d'environnement dans le fichier .npmrc. Veillez donc à ajouter les crochets d'ouverture ${ et de fermeture }.

    Vous pouvez saisir plusieurs jetons d'authentification.

L'exemple de code suivant montre un jeton d'authentification pour un package NPM privé ajouté au fichier .npmrc d'un dépôt Dataform :

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

Authentifier un package privé ultérieur dans un dépôt Dataform

Pour authentifier un package NPM privé dans un dépôt Dataform qui contient déjà un secret avec des jetons d'authentification de package et un fichier .npmrc, procédez comme suit :

  1. Dans Secret Manager, listez les secrets et sélectionnez celui qui stocke les jetons d'authentification des packages NPM privés de votre dépôt.

  2. Ajoutez une version au secret.

    Dataform utilise la dernière version du secret par défaut.

    1. Ajoutez le jeton d'authentification pour le package privé à la valeur secrète au format suivant :
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    Remplacez les éléments suivants :

    • AUTHENTICATION_TOKEN_NAME : nom unique du jeton qui identifie le package qu'il authentifie.
    • TOKEN_VALUE : valeur du jeton d'authentification obtenu auprès de votre registre NPM.

    Vous pouvez ajouter plusieurs jetons d'authentification à la fois.

  3. Dans Dataform, ajoutez le jeton d'authentification au fichier .npmrc de votre dépôt.

Une fois le package NPM privé authentifié, vous pouvez l'installer dans le dépôt Dataform.

Créer un package

Cette section explique comment créer un package JavaScript personnalisé que vous pouvez utiliser pour développer des workflows dans Dataform.

Pour créer un package réutilisable dans plusieurs dépôts Dataform, vous devez créer un dépôt Dataform dédié au package et le connecter à un dépôt Git tiers pour le rendre disponible aux autres dépôts Dataform.

Vous devez ensuite créer un fichier index.js de premier niveau et y ajouter le contenu de votre package exportable, tel que des fonctions et des constantes. Pour obtenir un exemple de package créé dans Dataform, consultez dataform-package-base sur GitHub.

Une fois le package créé, vous pouvez l'installer dans un autre dépôt Dataform et utiliser le contenu exportable du package, tel que les constantes et les fonctions, pour développer des workflows.

Au lieu de créer un package, vous pouvez réutiliser des fonctions et des constantes JavaScript dans un même dépôt Dataform à l'aide d'inclusions. Pour en savoir plus, consultez Réutiliser des variables et des fonctions avec des inclusions dans Dataform.

Pour créer votre propre package avec du code JavaScript que vous pouvez réutiliser dans Dataform, procédez comme suit dans votre espace de travail :

  1. Dans le volet Fichiers, cliquez sur Plus.

  2. Cliquez sur Créer un fichier.

    1. Dans le volet Créer un fichier, procédez comme suit :

    2. Dans le champ Ajouter un chemin d'accès au fichier, saisissez index.js.

    3. Cliquez sur Créer un fichier.

  3. Dans le fichier index.js, saisissez le code JavaScript que vous souhaitez exporter dans votre package.

    1. Créez des constantes au format suivant :

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

      Remplacez les éléments suivants :

      • CONSTANT_NAME : nom de votre constante
      • CONSTANT_VALUE : valeur de votre constante

    2. Créez des fonctions au format suivant :

      function FUNCTION_NAME(PARAMETERS) { FUNCTION_BODY }

module.exports = { FUNCTION_NAME }

      Remplacez les éléments suivants :

      • FUNCTION_NAME : nom de votre fonction.
      • PARAMETERS : paramètres de votre fonction.
      • FUNCTION_BODY : code que vous souhaitez que la fonction exécute.

  4. Facultatif : Cliquez sur Format.

  5. Facultatif : Dans le répertoire definitions, ajoutez le code de votre package qui ne sera pas exporté.

  6. Validez et transférez vos modifications.

L'exemple de code de package suivant montre le fichier index.js du package postoffice qui exporte la fonction 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 }

Étapes suivantes