Cette page a été traduite par l'API Cloud Translation.

Installer un package dans Dataform
Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Ce document explique comment installer un package JavaScript dans un dépôt Dataform, puis l'importer dans un fichier JavaScript et un fichier SQLX pour l'utiliser afin de développer des workflows SQL 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:

Packages NPM publics publiés.
Packages NPM publics non publiés
Packages NPM privés authentifiés

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

Avant de commencer

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

Accéder à la page Dataform
Sélectionnez ou créez un dépôt.
Sélectionnez ou créez un espace de travail de développement.
Si votre dépôt ne contient pas de fichier package.json, créez package.json et déplacez le package de base Dataform.
Facultatif: Pour installer un package privé, authentifiez-le.

Rôles requis

Pour obtenir les autorisations nécessaires pour installer un package, demandez à votre administrateur de vous accorder le rôle IAM Éditeur Dataform (roles/dataform.editor) sur les espaces de travail. 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

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

Pour ajouter un package en tant que dépendance dans le fichier package.json, procédez comme suit:

Dans votre espace de travail, dans le volet Fichiers (Fichiers), sélectionnez package.json.
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.
Cliquez sur Installer les packages.
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:

Dans votre espace de travail, dans le volet Fichiers, sélectionnez un fichier .js dans lequel vous souhaitez utiliser le package.
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.
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:

Dans votre espace de travail, dans le volet Fichiers, sélectionnez un fichier .js dans lequel vous souhaitez utiliser le package.
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.
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:

Dans votre espace de travail, dans le volet Fichiers, sélectionnez un fichier .sqlx dans lequel vous souhaitez utiliser le package.
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.
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:

Dans votre espace de travail, dans le volet Fichiers, sélectionnez un fichier .sqlx dans lequel vous souhaitez utiliser le package.
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.
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

Étape suivante

Pour savoir comment authentifier un package npm privé dans Dataform, consultez la section Authentifier un package privé dans Dataform.
Pour savoir comment gérer le package de base Dataform requis, consultez la section Gérer le package de base Dataform.
Pour savoir comment créer votre propre package dans Dataform, consultez la section Créer un package dans Dataform.
Pour savoir comment utiliser un package Open Source dans Dataform, consultez Utiliser des dimensions à évolution lente dans Dataform.

Installer un package dans Dataform Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.