Le connecteur Desktop peut être exécuté en ligne de commande. Ce mode de fonctionnement est utile lorsque l'on souhaite relancer un import sans passer par l'ensemble des étapes de l'interface, ou encore pour automatiser l'exécution d'un import.
Le connecteur ne permet pas actuellement d'effectuer une exécution planifiée. Si vous souhaitez planifier une exécution régulière, nous vous recommandons de créer un fichier de script de lancement du connecteur, et de planifier celui ci via le système d'exploitation hôte (tâche planifiée Windows, cron Linux) ou tout autre ordonnanceur disponible dans votre système d'information.
L'exécutable du connecteur en ligne de commande se trouve sous le répertoire /script du connecteur. Il faut exécuter le fichier datagalaxy-cli-connector.sh ou .bat suivant votre système d'exploitation.
Cet exécutable en ligne de commande peut vous être mis à disposition sous la forme d'une image docker. Nous contacter si vous souhaitez avoir plus d'informations à ce sujet.
Paramètres d'exécution
Plusieurs types de paramètres peuvent être utilisés lors de l'exécution en mode ligne de commande :
datagalaxy-cli-connector [options] [command] [command options]
Les options sont les suivantes :
| Option | Description |
|---|---|
| --help | Affiche l'aide du connecteur en mode ligne de commande (liste des options) |
| --version | Retourne la version du connecteur et la listes des plugins |
Les commandes et leurs options sont les suivantes :
| Commande | Option | Obligatoire | Description |
|---|---|---|---|
| plugins | Affiche les manifestes (description) des plugins installés | ||
| plugins | --name | Affiche le manifeste du plugin passé en paramètre | |
| import-api | Importe les métadonnées via API | ||
| import-csv | Extraction des métadonnées au format CSV | ||
| import-api / import-csv | --config | Oui | Chemin vers le fichier de configuration. Ces fichiers sont automatiquement générés dans le répertoire /connection du connecteur lorsque vous enregistrez une connexion via l'interface graphique. Le format de ces fichiers étant différent pour chaque technologie, il peut être complexe de le construire manuellement. Nous vous conseillons donc de les générer en enregistrant une connexion depuis l'interface graphique du connecteur (voir ici pour plus d'informations) |
| import-api / import-csv | --verbose | Non | Active le mode verbeux afin de disposer de plus d'informations sur les actions réalisées et les erreurs d'exécution |
| import-api / import-csv | --mapping | Non | Chemin du fichier de mapping utilisé pour les technologies de type traitement |
| import-api / import-csv | --password | Non | Mots de passe ou secrets à utiliser pour se connecter à la technologie source :
|
| import-csv | --output-directory | Oui | Répertoire de destination des fichiers générés lors d'une extraction au format CSV |
| import-csv | --output-files-suffix | Non | Ajoute un suffixe à tous les fichiers générés lors d'une extraction au format CSV (avant l'extension du fichier) |
| import-api | --server-url | Non | URL du serveur d'API DataGalaxy. Si l'option n'est pas renseignée, la valeur de la propriété datagalaxy.api.url présente dans le fichier /conf/application.properties sera utilisée |
| import-api | --token-value | Oui (une des 2 options doit être renseignée) | Token d'intégration à utiliser pour réaliser l'import via l'API DataGalaxy |
| import-api | --token | Chemin vers le fichier contenant le token d'intégration à utiliser pour réaliser l'import via l'API DataGalaxy. Ces fichiers sont automatiquement générés dans le répertoire /token du connecteur lorsque vous enregistrez un token via l'interface graphique. | |
| import-api | --project-name | Oui | Nom de l'espace de travail DataGalaxy |
| import-api | --version-name | Non | Nom fonctionnel de la version du projet dans lequel seront importées les données si le projet est versionné |
| import-api | --source-id | Uniquement lors d'un import dans le dictionnaire (une seule de ces options devra être renseignée) | Identifiant technique d'une source existante dans le dictionnaire DataGalaxy (voir plus loin plus plus d'information) |
| import-api | --source-name | Nom fonctionnel d'une source existante dans DataGalaxy | |
| import-api | --create-source | Non | Créé la source renseignée à l'aide du paramètre --source-name si elle n'existe pas |
| import-api | --orphaned-objects-handling | Non | Choisissez comment traiter les objets orphelins. Les objets orphelins sont des objets DataGalaxy qui n’existent plus dans la source. Cette option ne fonctionne pas lors de l'utilisation de la fonctionnalité URN. Les valeurs acceptées sont :
|
Exemple de commande
Import API
La ligne de commande suivante fonctionnera sous Windows, et va lire le fichier de connexion model-azuresql-test-connector.properties. Elle effectue un import via API en utilisant le token d'intégration contenu dans le fichier token.properties. La cible de l'import est l'espace de travail Demo. La source de données du dictionnaire qui accueillera le résultat de cet exécution s'appelle DB AzureSQL
datagalaxy-cli-connector.bat import-api --config "model-azuresql-test-connector.properties" --token "token.properties" --project-name Demo --source-name "DB AzureSQL" --password MyPassword
Import CSV
La ligne de commande suivante fonctionnera sous Windows, et va lire le fichier de connexion usage-powerbi-datagalaxy-secret.properties. Elle effectue un export au format CSV dans le répertoire C:\Connector Output Folder\Power BI
datagalaxy-cli-connector.bat import-csv --config "usage-powerbi-datagalaxy-secret.properties" --password "PowerBIClientSecret" --output-directory "C:\Connector Output Folder\Power BI"
Enchaîner plusieurs exécutions du connecteur
Si vous souhaitez enchaîner plusieurs lancements de connecteurs avec des configurations différentes, il est possible de créer un script .bat sous Windows ou .sh sous Linux, qui appellera le .bat/.sh du connecteur.
Sous Windows, attention à bien utiliser la commande call, sinon le script s'arrêtera après l'exécution du premier connecteur.
Par exemple pour lancer trois connecteurs, vous pouvez créer un script .bat comme ceci :
call datagalaxy-cli-connector.bat import-api --config "config1.properties" ... call datagalaxy-cli-connector.bat import-api --config "config2.properties" ... call datagalaxy-cli-connector.bat import-api --config "config3.properties" ...
Récupération des identifiants techniques DataGalaxy
Les identifiants techniques utilisés par certains paramètres (project-id, version-id, source-id) peuvent être récupérées de plusieurs façons
Via des appels API
- La méthode /worskpaces retourne la liste des espaces de travail, leurs identifiants et la version actuellement active sur chacun d'eux
- La méthode /versions retourne la liste des versions d'un espace de travail données, et leurs identifiants
- La méthode /sources retourne la liste des sources déclarées au sein d'un espace de travail, et leurs identifiants
Les résultats de ces appels sont conditionnés par les droits configurés sur le token d'intégration utilisé.
Plus d'information ici sur le fonctionnement de l'API DataGalaxy
En exploitant un fichier de log du connecteur
En effectuant un import en mode verbeux via l'interface graphique, le connecteur génère un fichier de log dans le dossier /logs du connecteur qui contiendra tous les identifiants utilisés.
Auquel cas il vous faudra identifier les appel aux différentes fonctions API listées ci dessus. Ci dessous un exemple pour la récupération du project-id et du version-id par défaut de vos espaces de travail via l'appel à la fonction /workspaces
Sur le même principe, pour la récupération du source-id, il vous faudra identifier l'appel à la fonction /sources
Questions fréquentes
Comment augmenter la mémoire allouée à l'exécution du connecteur ?
Il faut modifier le script "datagalaxy-cli-connector" avec l'extension .bat/.sh (selon votre système d'exploitation) pour rajouter les paramètres "-Xms" (initial heap size) et "-Xmx" (maximum heap size).
Localisation des scripts
Ils peuvent être modifiés dans un éditeur de texte classique type "Bloc-notes"
Exemple de modification pour un script .bat
@echo off title DataGalaxy Connector CLI :: architecture IF "%PROCESSOR_ARCHITECTURE%"=="x86" (set OS=32BIT) else (set OS=64BIT) set dirname=%~dp0 if %OS%==32BIT set java_home="%dirname%..\jre-32" if %OS%==64BIT set java_home="%dirname%..\jre-64" set java_bin="%java_home%\bin\java" "%java_bin%" -classpath "%dirname%/../datagalaxy-cli-connector.jar;%dirname%/../datagalaxy-desktop-connector.jar;%dirname%/../lib/*"^ -Ddatagalaxy.configurationPath="%dirname%/../conf"^ -Dlog4j2.formatMsgNoLookups=true^ -Dlogback.configurationFile="%dirname%/../conf/logback.xml"^ -Xms2048M^ -Xmx2048M^ com.datagalaxy.connector.desktop.cli.Main %*
Exemple de modification pour un script .sh
#!/usr/bin/env bash DIR=$(dirname $0) java -classpath "$DIR/../datagalaxy-cli-connector.jar:$DIR/../datagalaxy-desktop-connector.jar:$DIR/../lib/*" \ -Ddatagalaxy.configurationPath="$DIR/../conf" \ -Dlog4j2.formatMsgNoLookups=true \ -Dlogback.configurationFile="$DIR/../conf/logback.xml" \ -Xms2048M \ -Xmx2048M \ com.datagalaxy.connector.desktop.cli.Main "$@"
Une fois les modifications enregistrées il ne vous reste plus qu'à exécuter de nouveau le connecteur en utilisant les commandes de la partie "Exemple de commande"
Comment sécuriser le mot de passe d'accès à notre système dans le cadre de la planification du connecteur en ligne de commande ?
Le mot de passe de votre système est le seul paramètre qui n'est jamais stocké par le connecteur desktop dans le fichier de configuration de la connexion, pour des raisons de sécurité. Il doit être passé sous la forme de l'argument --password à chaque exécution du connecteur en ligne de commande, comme décrit ci-dessus.
Pour connaître les bonnes pratiques dans votre organisation pour fournir ce paramètre de manière sécurisée à l'exécution, veuillez vous rapprocher de votre équipe infrastructure, ou d'un intégrateur. Les options dépendent de vos politiques de sécurité et des outils dont vous disposez.
Nous ne conseillons pas d'approche particulière sur ce sujet, dans la mesure où les contextes et contraintes de nos clients sont tous différents.
Supportez-vous les vaults ?
Le connecteur n'embarque aucun support natif d'une solution de coffre-fort (vault). Il est bien sûr possible d'intégrer un vault dans votre architecture : le mot de passe devra être extrait du vault à l'exécution et fourni grâce au paramètre --password. Ceci peut être fait par un script, certains ordonnanceurs supportent également de passer les valeurs secrètes d'un vault via des variables.
Le support DataGalaxy ne pourra vous accompagner sur ces choix d'intégration.
Si vous souhaitez suggérer une fonctionnalité du connecteur permettant de gérer ce mot de passe différemment, vous pouvez décrire votre besoin dans une demande d'évolution dans le cadre de notre programme User Voice, notre équipe Produit l'étudiera attentivement.