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:
- Publication de packages NPM publics
- 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é 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 liés à l'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 optionsdependencies
depackage.json
, par exemple>version
.Testez de nouvelles versions de package dans un environnement hors production. Pour en savoir plus sur la configuration des 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.
Sélectionnez ou créez un dépôt.
Sélectionnez ou créez un espace de travail de développement.
Facultatif: Pour installer un package privé, authentifiez-le.
Rôles requis
Pour obtenir les autorisations nécessaires pour importer un package, demandez à votre administrateur de vous attribuer 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 section Gérer les accès.
Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.
Installer un package dans un dépôt Dataform
Pour installer un package dans un dépôt Dataform, vous devez l'ajouter en tant que dépendance dans le fichier package.json
. Le format de la définition de dépendance dans le fichier package.json
dépend du type de package. Si vous n'avez pas de fichier package.json
, car votre fichier workflow_settings.yaml
spécifie votre dataformCoreVersion
, supprimez le dataformCoreVersion
de workflow_settings.yaml
, puis créez un fichier package.json
et ajoutez @dataform/core
en tant que dépendance.
Pour installer un package dans un dépôt Dataform, procédez comme suit:
- Dans votre espace de travail, dans le volet Fichiers, sélectionnez
package.json
. Ajoutez le package au bloc
dependencies
: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 par la dernière version du package NPM public publié. Pour éviter les problèmes liés à l'installation du package, spécifiez explicitement la version, par exemple
3.0.0
.
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 exemplehttps://github.com/user/sample-package-repository/archive/master.tar.gz
.
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 exemplehttps://github.com/user/sample-package-repository/archive/master.tar.gz
.
- REGISTRY-SCOPE par le nom du package.
REGISTRY-SCOPE doit correspondre au champ d'application du registre défini dans le fichier
Cliquez sur Install packages (Installer les packages).
L'exemple de code suivant montre le package Open Source public Open Source du package de dimensions à modification lente 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:
- Dans le volet Fichiers de votre espace de travail, 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");
- Remplacez EXPORT-NAME par le nom de la fonction ou de la constante que vous souhaitez utiliser, déclaré dans
module.exports
dans le fichierindex.js
du package. - Remplacez PACKAGE-NAME par le nom du package que vous souhaitez utiliser.
- Remplacez EXPORT-NAME par le nom de la fonction ou de la constante que vous souhaitez utiliser, déclaré dans
L'exemple de code suivant montre la fonction getDomain
du package postoffice
importé et utilisé 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 les fonctions ou les constantes sélectionnées dans un fichier JavaScript, procédez comme suit:
- Dans le volet Fichiers de votre espace de travail, 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");
- Remplacez CONSTANT-NAME par le nom de la constante.
- Remplacez PACKAGE-NAME par le nom du package que vous souhaitez utiliser.
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:
- Dans le volet Files (Fichiers) de votre espace de travail, 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"); }
- Remplacez EXPORT-NAME par le nom de la fonction ou de la constante que vous souhaitez utiliser, déclaré dans
module.exports
dans le fichierindex.js
du package. - Remplacez PACKAGE-NAME par le nom du package que vous souhaitez utiliser.
- Remplacez EXPORT-NAME par le nom de la fonction ou de la constante que vous souhaitez utiliser, déclaré dans
L'exemple de code suivant montre la fonction getDomain
du package postoffice
importé dans un bloc js
et utilisée dans une instruction SELECT
d'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 les fonctions ou constantes sélectionnées dans un fichier JavaScript, procédez comme suit:
- Dans le volet Files (Fichiers) de votre espace de travail, 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"); }
- Remplacez CONSTANT-NAME par le nom de la constante.
- Remplacez PACKAGE-NAME par le nom du package que vous souhaitez utiliser.
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
Étapes suivantes
- Pour savoir comment authentifier un package NPM privé dans Dataform, consultez la section Authentifier un package privé dans Dataform.
- Pour en savoir plus sur les packages dans Dataform, consultez Réutiliser du code dans plusieurs dépôts avec des packages.
- Pour savoir comment créer votre propre package dans Dataform, consultez la page Créer un package dans Dataform.
- Pour savoir comment utiliser un package Open Source dans Dataform, consultez Utiliser des dimensions à évolution lente dans Dataform.