CartoVistaQu’est-ce que l’API REST de CartoVista et dans quel but puis-je l’utiliser ? #
CartoVista dispose d’une API REST qui vous permettra d’automatiser n’importe laquelle de vos actions sur la plateforme, comme le chargement d’un jeu de données, la modification d’un jeu de données ou d’une partie d’un jeu de données, la suppression d’un objet sur la plateforme, etc.
L’API de CartoVista est basée sur les principes REST. Les appels à l’API se font par le biais de requêtes HTTP, en utilisant les méthodes standard suivantes : GET, POST, DELETE, PATCH.
Cette API REST permet l’interopérabilité avec d’autres systèmes et bases de données. Voici quelques exemples d’utilisation :
- mettre à jour quotidiennement une couche à partir d’une source de données publique
- mettre à jour ou ajouter de nouvelles entités dans une couche à partir de triggers dans une base de données
- modifier automatiquement le contenu du panneau Histoire lorsque les données dépassent un certain seuil
- exporter des statistiques hebdomadaires sur l’espace de travail pour suivre l’utilisation des cartes publiques
- importer votre base d’utilisateurs dans CartoVista pour envoyer des invitations automatiquement
Démarrer #
Authentifier votre requête #
Vous aurez besoin d’une clé API pour utiliser l’API REST de CartoVista. Les clés API sont associées à des utilisateurs et héritent de leurs permissions. Vous pouvez utiliser le tutoriel Générer une clé API du Centre de ressources de votre espace de travail pour apprendre à générer votre clé.
Une liste d’adresses IP externes sécurise les clés API. Vous devrez donc effectuer les appels API à partir de l’ordinateur dont vous avez enregistré l’IP. Enregistrez plusieurs adresses IP externes pour une clé API en séparant les IP par un point-virgule.
Si vous ne souhaitez pas utiliser la liste blanche d’adresses IP, vous pouvez générer une clé secrète et supprimer le contenu de la liste blanche d’adresses IP. La clé secrète n’est visible que temporairement sur la plateforme, et vous devrez la régénérer si vous ne la sauvegardez pas ailleurs.
Vous pouvez également combiner les deux méthodes de sécurité pour disposer à la fois d’une clé secrète et d’une liste blanche d’adresses IP. Vous avez besoin d’au moins une méthode de sécurité pour que la clé API fonctionne (liste blanche d’adresses IP ou clé secrète).
Pour générer une clé secrète, cliquez sur l’utilisateur pour lequel vous souhaitez créer une clé dans l’onglet Utilisateurs de la plateforme. Dans le panneau détaillé de l’utilisateur, cliquez sur l’onglet Clé API. Cliquez sur l’icône + pour générer une nouvelle clé.
Entrez une adresse IP pour générer la clé.
Une fois la clé générée, vous pouvez la copier à partir de la plateforme pour l’intégrer dans votre script. Vous pouvez également générer une clé secrète à partir de ce panneau.
Dans vos appels à l’API, vous devrez fournir l’en-tête apiKey et l’en-tête secretKey si vous en avez généré un. L’en-tête secretKey est facultatif.
Veuillez noter que si vous utilisez des services de test d’API en ligne tels que Postman, vous devrez utiliser la clé secrète et supprimer la liste blanche d’adresses IP car l’adresse IP de Postman n’est pas statique.
Identifier la requête dont vous avez besoin #
CartoVista utilise Swagger pour documenter les endpoints de l’API. Dans l’onglet Clé API du panneau de détails d’un utilisateur, vous trouverez le lien vers la page Swagger. Vous pouvez également utiliser le tutoriel Générer une clé API du Centre de ressources de votre espace de travail pour accéder à la page Swagger.
Swagger est utile pour en savoir plus sur l’API, découvrir tous les appels et méthodes disponibles et les essayer en utilisant votre clé API. Cependant, il ne peut pas être utilisé pour automatiser vos tâches.
Swagger vous donne la liste de tous les endpoints, organisés par thème.
Vous pouvez entrer votre clé API pour tester une requête ou vous connecter à votre compte dans un autre onglet pour authentifier vos appels swagger. Veuillez noter que si votre clé API a une clé secrète générée, vous ne pouvez pas authentifier vos appels swagger en entrant votre clé API, et vous devez être connecté à votre espace de travail dans un autre onglet.
Cliquez sur un endpoint pour voir les détails.
Remplissez les paramètres (voir comment obtenir les valeurs des paramètres ci-dessous) et cliquez sur Essayez. La réponse contiendra la requête Curl, le corps de la réponse et le code de la réponse.
✔️ Vous pouvez maintenant utiliser n’importe quel logiciel capable d’envoyer et de recevoir des requêtes HTTP pour utiliser l’API REST de CartoVista et commencer à automatiser vos tâches..
Paramètres #
Lorsque vous utilisez l’API REST pour des cartes ou des données, vous devez transmettre certains paramètres dans l’URL ou le body de la requête :
- le tenantUrlCode: c’est l’identifiant de votre espace de travail. Vous pouvez le trouver dans l’URL de votre espace de travail CartoVista : cloud.cartovista.com/{tenantUrlCode}/maps.
- l’identifiant de votre jeu de données ou carte.
Pour obtenir l’identifiant d’une carte, cliquez sur la partie inférieure d’une carte pour ouvrir le panneau détaillé de la carte. L’onglet Information vous donnera l’URL de la carte. L’identifiant est le code de 5 caractères (chiffres et/ou lettres) entre le nom de l’espace de travail et le nom de la carte :
Pour obtenir l’identifiant d’une couche ou d’une table de données, cliquez sur la partie inférieure d’une carte de données dans la Galerie de données pour ouvrir le panneau détaillé des données. L’onglet Information vous donnera l’identifiant de vos données :
Package pip pour Python #
En plus de la page Swagger, l’API est également disponible sous forme de paquet pip pour Python. Les instructions d’installation, les exemples d’utilisation et la documentation détaillée sont disponibles sur GitHub: https://github.com/cartovista/cartovista-cloud-restapi-python-client.
