Utiliser des packages JavaScript

Ce document vous explique comment :

Avant de commencer

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

    Accéder à Dataform

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

    1. Pour installer un package dans un dépôt ou authentifier un package NPM privé pour 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 de base Dataform.
    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 au nom 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 la page Gérer l'accès aux projets, aux dossiers et aux organisations.

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

Installer un package

Cette section explique comment installer un package JavaScript et l'importer dans un fichier JavaScript et un fichier SQLX afin de pouvoir l'utiliser 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 les problèmes d'installation de paquets 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 packages dans un environnement hors production. Pour en savoir plus sur la configuration de différents environnements de cycle de vie du code, consultez la section Gérer le cycle de vie du code.

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 paquets 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 à la portée du Registre définie 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 paquets, 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 vers 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 index.js du package.
    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'ensemble 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 vers 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 index.js du package.
    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'ensemble 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 dans 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é dans un dépôt et un package privé ultérieur dans 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 procéder comme suit 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 dans 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 le jeton d'authentification du package au fichier.

    Le jeton d'authentification du fichier .npmrc doit correspondre au jeton d'authentification 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 dans le 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, obtenue à partir 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 d'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 votre secret contenant le jeton d'authentification du package dans le dépôt.

Pour importer le secret avec 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 page.

    Accéder à Dataform

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

  3. Sur la page du dépôt, cliquez sur Settings > Configure Private NPM Packages (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 niveau supérieur 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 dans le fichier .npmrc. Les jetons d'authentification du fichier .npmrc doivent correspondre aux jetons d'authentification 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 niveau supérieur dans votre dépôt, procédez comme suit:

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

    Accéder à Dataform

  2. Sélectionnez le dépôt dans lequel vous souhaitez installer des paquets NPM privés, puis 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 d'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 la portée de votre registre npm et ajouter le jeton d'authentification du package privé auquel vous accédez dans cette portée. Pour en savoir plus sur les fichiers .npmrc, consultez la documentation npmrc.

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

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

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

    Accéder à Dataform

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

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

  4. Dans le fichier .npmrc, définissez la portée du registre NPM et le jeton d'authentification du package privé au format suivant:

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

    Remplacez les éléments suivants :

    • REGISTRY-SCOPE: portée du registre NPM à laquelle 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 du package NPM privé. Le jeton d'authentification du fichier .npmrc doit correspondre au jeton d'authentification du secret importé. Le jeton d'authentification est fourni en tant que variable d'environnement dans le fichier .npmrc. Assurez-vous donc d'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 le secret qui stocke les jetons d'authentification des paquets NPM privés de votre dépôt.

  2. Ajoutez une nouvelle version au secret.

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

    1. Ajoutez le jeton d'authentification du 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, obtenue à partir 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 que vous pouvez réutiliser 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 mettre à la disposition d'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, comme les fonctions et les 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 les contenus exportables du package, tels 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 seul dépôt Dataform avec des inclusions. Pour en savoir plus, consultez la section 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.

    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 }

Étape suivante