Créer votre propre connecteur avec Custom Sources
Custom Sources vous permet d'apporter votre propre connecteur pour une API que Data Platform ne couvre pas
Objectif
Custom Sources vous permet d'apporter votre propre connecteur pour une API que Data Platform ne couvre pas. Votre agent de code écrit et teste le connecteur sur votre poste, guidé par un skill que vous téléchargez depuis Data Platform. Vous importez le résultat sous forme de package, Data Platform le vérifie et le publie, et tout membre du projet disposant des droits sur les sources peut ensuite créer des sources à partir de ce connecteur.
Une source construite sur un connecteur personnalisé fonctionne comme n'importe quelle autre source : elle apparaît dans la liste Sources, ses métadonnées sont extraites, et elle alimente les actions Load, les tables et le lineage. Seul le nom de son connecteur la distingue des autres.
Custom Sources ou HTTP REST
Le connecteur HTTP REST couvre déjà les API que vous pouvez décrire dans un formulaire. Utilisez une source personnalisée lorsque l'API demande du Python pour être lue :
- une pagination que HTTP REST ne sait pas suivre ;
- plusieurs appels pour construire un seul enregistrement ;
- des réponses à remettre en forme avant leur chargement ;
- un mode d'authentification que HTTP REST ne prend pas en charge.
Un connecteur personnalisé n'est jamais construit ni modifié dans Data Platform. Le package est le connecteur : son code, ses endpoints et ses champs d'identifiants viennent du package, et ne changent que lorsque vous en importez un nouveau.
Prérequis
- Un agent de code IA sur votre poste, pour construire le connecteur.
- La documentation de l'API, ou un fichier OpenAPI ou des exemples cURL, et des identifiants valides si l'API en demande.
- La permission d'écrire des sources dans le projet (voir Permissions).
Instructions
Télécharger le skill
Dans le service Connectors, ouvrez Custom Sources et cliquez sur Download skill. Le skill est un dossier que vous confiez à votre agent de code. Il contient :
Vous pouvez télécharger à nouveau le skill à tout moment depuis la même page.
Construire et tester le connecteur avec votre agent
Confiez le dossier du skill à votre agent de code et demandez-lui de construire un connecteur pour votre API. En suivant le skill, l'agent :
- Vérifie qu'une source personnalisée est le bon outil, plutôt que HTTP REST.
- Vous demande la documentation de l'API, les données souhaitées et le fonctionnement de l'authentification.
- Écrit le connecteur : un manifeste (
forepaas.json) et un module Python. - Exécute le connecteur sur l'API réelle, avec les identifiants que vous exportez dans des variables d'environnement
CUSTOM_SOURCE_<KEY>. Les valeurs des identifiants ne sont jamais écrites dans un fichier. - Lance les mêmes vérifications que Data Platform à l'import, puis construit le package, un fichier
.tgz. - Vous indique ce que le connecteur extrait, les champs d'identifiants qu'il déclare, les avertissements restants et ce qu'il n'a pas pu exécuter.
Le test s'exécute sur votre poste, avec l'API réelle : Data Platform ne voit jamais vos identifiants pendant la construction du connecteur.
Importer le connecteur
Sur la page Custom Sources, cliquez sur Upload, puis déposez le fichier .tgz dans la fenêtre ou cliquez pour le sélectionner.
Data Platform lance ses vérifications et affiche les endpoints trouvés, avec :
- des erreurs, qui bloquent l'import : corrigez-les avec votre agent et importez le nouveau package ;
- des avertissements, qui ne le bloquent pas : lisez-les, et corrigez-les avec votre agent s'ils vous concernent.
Cliquez sur Add. Le connecteur est publié immédiatement et sa page s'ouvre. Vous pouvez créer une source à partir de ce connecteur tout de suite, ou plus tard depuis la même page.
Un package est refusé s'il déclare une dépendance autre qu'une dépendance Python, s'il contient un script ou un fichier autre que le manifeste, le module Python et l'icône. Son nom technique ne peut pas être celui d'un connecteur intégré à Data Platform.
Consulter et modifier le connecteur
Ouvrez un connecteur depuis la liste Custom Sources. Sa page comporte 2 onglets :
- Definition : le résultat des vérifications, avec les éventuels avertissements restants, puis l'identité du connecteur, sa connexion (URL de base, méthode d'authentification), ses champs d'identifiants et ses endpoints avec leurs paramètres.
- Code : le code Python exécuté dans les jobs d'extraction.
Vous pouvez modifier 3 éléments dans Data Platform : le nom d'affichage (200 caractères au plus), la description (2 000 caractères au plus) et l'icône. Un bouton Save apparaît lorsque vous modifiez l'un d'eux. Tout le reste vient du package et est en lecture seule : pour changer le code, les endpoints, les champs d'identifiants ou l'authentification, mettez à jour le connecteur avec votre agent et importez une nouvelle version.
Le nom technique ne peut pas changer. Il identifie le connecteur, et un import avec le même nom technique le remplace.
Créer une source à partir du connecteur
Sur la page du connecteur, cliquez sur Connect to the source. Vous pouvez aussi cliquer sur New Source dans la liste Sources : les connecteurs personnalisés figurent dans la catégorie Custom Source du store, à côté des connecteurs intégrés.
L'assistant de création de source standard s'ouvre. Nommez la source, renseignez les champs d'identifiants que déclare le connecteur, choisissez les endpoints et leurs paramètres, puis enregistrez. Consultez Configurer votre connecteur pour les étapes suivantes, de l'extraction des métadonnées au chargement.
Mettre à jour un connecteur
- Sur la page du connecteur, cliquez sur Export. Le package se télécharge, sans aucune valeur d'identifiant. Conservez-le comme sauvegarde.
- Confiez le package exporté à votre agent, avec le skill, et demandez la modification. L'agent conserve le nom technique, teste chaque endpoint, lance les vérifications et construit un nouveau package.
- Cliquez sur Upload new version et importez le nouveau package. Il remplace le précédent.
Les sources qui utilisent le connecteur exécutent le nouveau code dès leur prochain job. En cas de problème, importez à nouveau le package exporté à l'étape 1.
Importer un package portant le même nom technique depuis Upload sur la page Custom Sources remplace aussi le connecteur : la fenêtre propose de le remplacer, jamais d'en créer un second. Upload new version refuse un package dont le nom technique est différent.
Partager un connecteur avec un autre projet
Cliquez sur Export sur la page du connecteur, puis importez le package dans l'autre projet avec Upload. Le même connecteur y est publié. Les valeurs des identifiants ne font pas partie du package : chaque source de l'autre projet a besoin des siennes.
Supprimer un connecteur
Cliquez sur Delete dans la liste Custom Sources. La page du connecteur n'a pas de bouton de suppression.
Les sources qui utilisent le connecteur cessent de fonctionner. Lorsque des sources dépendent du connecteur, la confirmation les liste par leur nom. Une fois le connecteur supprimé, ces sources sont conservées comme orphelines, et leur prochain job échoue avec un message qui nomme le connecteur manquant.
Permissions
Custom Sources utilise les permissions existantes sur les sources dans l'Identity Access Manager. Il n'existe pas de rôle dédié.
Sans droits sur les sources, la page Custom Sources et la catégorie Custom Source du store n'apparaissent pas. Avec des droits en lecture seule, la page et les connecteurs sont visibles, et Save, Upload, Upload new version et Delete sont désactivés.
Bon à savoir
- Le code s'exécute uniquement dans les jobs d'extraction de votre projet, comme un connecteur intégré. Il ne s'exécute jamais dans un service partagé de Data Platform.
- Les identifiants sont déclarés comme champs secrets dans le package et renseignés à la création d'une source. Leurs valeurs ne font jamais partie d'un package, y compris d'un package exporté.
- Une nouvelle version s'applique à toutes les sources du connecteur dès leur prochain job. Si le nouveau package supprime un endpoint utilisé par une source, l'import ne vous avertit pas : le prochain job de cette source échoue.
- Data Platform ne conserve pas d'historique des versions. Exportez le connecteur avant d'importer une nouvelle version, pour pouvoir le restaurer.
Dépannage
Aller plus loin
Pour une formation ou une assistance technique sur la mise en œuvre de nos solutions, contactez votre commercial ou consultez la page Professional Services pour obtenir un devis et faire analyser votre projet par nos experts.
Posez vos questions, faites-nous part de vos commentaires et interagissez directement avec l’équipe qui développe la Data Platform sur le canal Discord dédié.
Si vous avez besoin d'une assistance concernant vos services OVHcloud, créez une demande depuis notre centre d'aide.
Rejoignez notre communauté d'utilisateurs.