Skip to main content

Guide connecteur système API

Introduction

Le connecteur système permet d’exploiter l’API Stockage Entreprise de Shadline sans avoir à développer son propre code. Avec cet outil vous pouvez envoyer et récupérer facilement tout type de fichiers dans les espaces de stockage sécurisés.

Il est nécessaire de disposer du service Stockage Entreprise Shadline pour utiliser cet outil. La souscription à ce service vous permet d’obtenir le certificat et la clé API requis pour se connecter.

Le Stockage Entreprise Shadline peut être cloisonné en conteneurs qui correspondent à des espaces de stockage isolés. Chaque instance du connecteur système peut interagir avec un seul conteneur. Vous pouvez exécuter plusieurs instances de l’outil pour vous connecter à différents conteneurs.

Note : Les noms des fichiers locaux ne doivent pas contenir les caractères : ’(apostrophe), &, ?, |, *, :,  /, \, <, >

Installation

Le connecteur Shadline est compatible avec les systèmes d’exploitation Windows, Linux et macOS ; en 64 bits. Il peut être utilisé sur des serveurs ou stations de travail.

L’exécution du connecteur ne nécessite aucune installation de composants tiers. Tous les pré-requis sont intégrés à l’outil.

Le fichier ‘shadline-connector.zip’ est mis à disposition des clients ayant souscrit à ce service par l’équipe Shadline. Il contient les exécutables pour Linux, macOS et Windows. Dézippez le fichier et copiez l’exécutable sur la machine depuis laquelle sera faite l’opération de synchronisation.

Note : Pour une machine Windows, il faut copier le fichier “shadline-connector.exe” ainsi que le répertoire “notifier”.

Il est également nécessaire d’autoriser un flux sortant vers le domaine shadline.com sur le port 4435 (par défaut) pour permettre la communication avec le service.

Configuration

Les paramètres nécessaires au fonctionnement du connecteur sont définis dans le fichier de configuration nommé config.json. Le fichier de configuration par défaut est situé dans le même dossier que l’outil.

Il existe 2 méthodes pour configurer l’outil :

  • Compléter les paramètres dans le fichier de configuration config.json
  • Exécuter l’outil sans arguments en entrée et répondre aux questions

Voici la liste des paramètres à renseigner dans le fichier de configuration config.json :

Paramètre Explication
certFilePath Fichier .crt du certificat utilisé pour se connecter au serveur Shadline.
certKeyPath Fichier .key contenant la clé du certificat utilisé pour se connecter au serveur Shadline.
xApiKey Identifiant de l’entreprise, au format UUIDv4, généré par le service Shadline et délivré au client lors de l’activation du service. Cet identifiant est commun aux différents conteneurs utilisés par l’entreprise.
xUserKey Identifiant du conteneur auquel le connecteur doit accéder, au format UUIDv4, généré par le service Shadline. Il est obtenu directement par les administrateurs du client qui ont accès au back-office Shadline (ou communiqué par Shadline lors de l’initialisation de l’instance API).
hPassword Mot de passe hashé en SHA512 du conteneur auquel le connecteur doit accéder.
localPassword Chaîne de caractères délivrée par le serveur Shadline suite à la première connexion à l’API.
sourcePath Répertoire local racine à partir duquel les fichiers sont envoyés au stockage Shadline lors de l’exécution du connecteur via la commande push (y compris les dossiers et sous-dossiers contenus dans ce répertoire).
destPath Répertoire local racine à partir duquel les fichiers sont reçus du stockage Shadline lors de l’exécution du connecteur via la commande pull (y compris les dossiers et sous-dossiers contenus dans ce répertoire).

Note : Il faut toujours saisir les chemins absolus pour les répertoires à renseigner.

Voici un exemple de fichier config.json :

config_exemple_json

 

Note : Sous Windows les chemins d’accès sont renseignés avec le séparateur « \\ ». Sous Linux et macOS, ils le sont avec le séparateur « / ».

Vous pouvez télécharger ce fichier d’exemple pour l’adapter à votre configuration : config_exemple.json.

 

Les répertoires sourcePath et destPath peuvent être le même répertoire.

Exécution

L’outil est exécuté au moyen de la commande suivante :

shadline-connector.exe [commande] [options]

Commandes :

  • push : Upload les fichiers depuis le répertoire « sourcePath » local vers le Stockage Entreprise Shadline.
    • Tout nouveau fichier ajouté ou modifié (*) depuis la dernière exécution du connecteur est importé sur Shadline.
    • Si un fichier portant le même nom est déjà présent dans le conteneur du Stockage Entreprise Shadline, ce fichier est effacé et le fichier présent localement est uploadé.
    • Le connecteur ne supprime pas dans le conteneur du Stockage Entreprise Shadline les fichiers supprimés localement.

(*) : Après la première synchronisation, si un fichier a été supprimé du stockage Entreprise, il ne sera pas automatiquement renvoyé au serveur. Un message dans le fichier journal .log (ou dans la console) vous indique que le fichier a été supprimé du conteneur dans le stockage Entreprise. Afin de remettre ces fichiers supprimés dans le conteneur, il est nécessaire d’utiliser l’option -f (–force) :

shadline-connector.exe push -f
  • pull : Télécharge les fichiers depuis le Stockage Entreprise Shadline vers le répertoire « destPath » local.
    • Tout nouveau fichier ajouté ou modifié sur le Stockage Entreprise Shadline depuis la dernière exécution du connecteur est synchronisé sur le répertoire local.
    • Si un fichier portant le même nom est déjà présent sur le répertoire local, ce fichier est effacé (*) et le fichier présent sur le Stockage Entreprise Shadline est téléchargé.

(*) Si un fichier a été modifié localement depuis le dernier téléchargement, il ne sera pas automatiquement re-téléchargé depuis le Stockage Entreprise Shadline pour éviter d’écraser par défaut le fichier local plus récent. Un message dans le fichier journal .log vous indique que le fichier a été mis à jour localement. Afin de récupérer les fichiers du conteneur Shadline, il est nécessaire d’utiliser l’option -f (–force) :

shadline-connector.exe pull -f

Options :

  • –version : Affiche le numéro de version
  • –config, -c : Chemin vers un fichier de configuration
  • –source,-s : Chemin vers le répertoire servant à envoyer les données au Stockage Entreprise Shadline. Remplace celui spécifié dans le fichier config.json sous l’identifiant sourcePath.
  • –dest, -d : Chemin vers le répertoire servant à recevoir les données du Stockage Entreprise Shadline. Remplace celui spécifié dans le fichier config.json sous l’identifiant destPath
  • –force, -f : Si un fichier précédemment envoyé par la commande push a été supprimé du Stockage Entreprise Shadline, cette option permet de le renvoyer de nouveau.
  • –help, -h : Affiche l’aide

Notes :

  • Si l’option —config est utilisée, le fichier de configuration config.json déjà existant est ignoré et celui fourni en argument est utilisé.
  • Si l’option –-source est utilisée, le paramètre “sourcePath” du fichier de configuration config.json est ignoré et celui fourni en argument est utilisé.
  • Si l’option —dest est utilisée, le paramètre “destPath” du fichier de configuration config.json est ignoré et celui fourni en argument est utilisé.
  • Il est nécessaire d’autoriser un flux sortant vers le domaine shadline.com sur le port 4435 (par défaut) pour permettre la communication avec le service Shadline.

Exemples :

Envoi des fichiers ajoutés ou modifiés localement depuis la dernière exécution du connecteur et situés à partir  du répertoire local de référence, dans le conteneur du Stockage Entreprise Shadline :

shadline-connector.exe push

Pour Windows :

Vous avez la possibilité de créer un raccourci pour vous simplifier la tâche de la manière suivante :

  1. Clic droit > Nouveau raccourci
  2. Insérer, en remplaçant par les bonnes valeurs :
    C:\Windows\System32\cmd.exe /k “C:\CHEMIN-VERS-L-EXECUTABLE\shadline-connector.exe push -c C:\Users\CHEMIN-VERS-VOTRE-CONFIGURATION\config.json”

Notifications :

Sous Windows, une notification système informe l’utilisateur lorsqu’un upload ou téléchargement de fichiers a été effectué.

Première exécution sous macOS :

Lors du 1er lancement sous macOS, un message d’avertissement peut-être présenté à l’écran (captures ci-dessous). Il faut choisir « Annuler » sur la 1ère fenêtre et « Ouvrir » sur la 2nde pour exécuter l’outil.

1_lancement du connecteur_macos 2_lancement du connecteur_macos

Logs

Les opérations effectuées par le connecteur sont journalisées dans le répertoire cible dans un fichier .log au format json.

Voici un exemple de fichier de log :

{"name":"uploader","hostname":"DARYL","pid":34257,"level":30,"msg ":" Config file found","time":"2021-08-16T09:28:17.658Z","v":0}
{"name":"uploader","hostname":"DARYL","pid":34257,"level":30,"msg ":" Config file loaded","time":"2021-08-16T09:28:17.659Z","v":0}
{"name":"uploader","hostname":"DARYL","pid":34257,"level":30,"msg ":" '/text.md' created","time":"2021-08-16T09:28:18.477Z","v":0}
{"name":"uploader","hostname":"DARYL","pid":34257,"level":30,"msg ":" '/tux.png' created","time":"2021-08-16T09:28:18.991Z","v":0} 
{"name":"uploader","hostname":"DARYL","pid":34257,"level":30,"msg ":" 2 new entries created","time":"2021-08-16T09:28:23.493Z","v":0}
{"name":"uploader","hostname":"DARYL","pid":34257,"level":30,"msg ":" No updated entry","time":"2021-08-16T09:28:23.493Z","v":0}

Conteneurs de stockage

Pour gérer les conteneurs de stockage auxquels le connecteur accède, nous vous invitons à vous référer à la page suivante de notre documentation :

Guide administrateur

Cette page explique notamment comment récupérer la valeur du paramètre “x-user-key” de chaque conteneur.