L'API Web Samsara permet d'accéder à toutes vos données dans le Cloud Samsara à l'aide d'une API de type RPC basée sur HTTPS. Utilisez l'API pour accéder :
Des données en temps réel et historiques pour n'importe quelle période et fréquence d'échantillonnage peuvent être demandées
Données de température, d'humidité, de puissance et de module d'entrée disponibles
L'accès à l'API est activé pour tous les clients
La sécurité de l'authentification est assurée par un système de jeton API et de clé secrète
Données livrées en toute sécurité au format JSON via TLS
Les versions de l'API sont publiées périodiquement.
Pour des informations détaillées sur l'API Samsara, consultez le portail des développeurs à l'adresse développeurs.samsara.com.
Vous pouvez gérer les jetons d'API pour un accès sécurisé à l'API sur le Jetons d'API page des paramètres. Pour des informations détaillées sur les jetons d'API, consultez le Guide d'authentification.
Pour créer un jeton d'API, vous devez disposer d'un rôle d'administrateur complet ou d'administrateur standard ou d'un Rôles personnalisés avec les autorisations suivantes.
Modifier les autorisations pour voir et modifier les jetons d'API
Modifier les autorisations pour créer, modifier et supprimer des utilisateurs, des rôles, des balises
Dans les deux cas, votre rôle doit avoir accès à la gestion de l'ensemble de l'organisation. Les rôles qui utilisent des balises pour une portée réduite (également appelés administrateurs au niveau de la balise) ne sont pas suffisants.
Vous pouvez demander et supprimer autant de jetons API que nécessaire.
Pour configurer un jeton d'API :
Sélectionnez l'icône Paramètres (
) au bas de votre Samsara dashboard pour afficher les paramètres du tableau de bord.
-
Sélectionner Clé API.
Cliquez sur + Ajouter un jeton API.
-
Définissez les propriétés du jeton :
Entrez un descriptif Nom pour votre jeton d'API qui décrit l'objectif principal.
Sélectionnez le niveau de Accès aux balises pour votre jeton. Pour plus d'informations sur les balises, voir Mots clés.
-
Sélectionnez une autorisation Portée pour votre jeton API :
Sauvegarder vos modifications.
-
Après avoir créé le jeton, copiez-le comme indiqué ci-dessous. Le jeton deviendra illisible après l'actualisation de la page, assurez-vous donc d'enregistrer la chaîne du jeton dans un emplacement sécurisé.
Si vous oubliez de copier ou perdez un jeton d'API, vous pouvez générer une nouvelle chaîne de jeton.
Note
Si une intégration utilise activement un jeton d'API, elle s'arrêtera lorsque vous régénérerez ce jeton d'API. En effet, la clé précédente sera supprimée et remplacée par une nouvelle clé. Prenez les précautions appropriées avant de confirmer.
Sélectionnez l'icône Paramètres (
Sélectionner Clé API.
-
Dans le menu Plus d'actions ( ... ), sélectionner Regenerate (Régénérer).
Cliquez sur Copy to Clipboard (Copier dans le presse-papier) pour copier le nouveau code et l'enregistrer.
Remplacez le jeton d'API partout où il est utilisé.
Vous pouvez mettre à niveau la version du jeton d'API dans votre console d'administration. Samsara n'incrémente la version de l'API que lorsqu'il y a une modification avec rupture de l'API.
Voici des exemples de modifications avec rupture :
Ajout d'un paramètre de requête obligatoire aux méthodes d'API existantes
Suppression de propriétés des réponses d'API existantes
Pour les modifications sans rupture, celles-ci seront accessibles dans toutes les versions de l'API.
Voici des exemples de modifications ininterrompues :
Ajout de nouvelles ressources API
Ajout de nouveaux paramètres de requête facultatifs aux méthodes d'API existantes
Ajout de nouvelles propriétés aux réponses d'API existantes
Modification de l'ordre des propriétés dans les réponses d'API existantes
Modification de la longueur ou du format des ID d'objet ou d'autres chaînes opaques
Vous pouvez trouver la version sur la page API Tokens du tableau de bord :
La mise à niveau de votre version d'API affectera les appels d'API que vous effectuez sans en-tête Samsara-Version : les paramètres que vous pouvez envoyer et la structure des objets renvoyés.
Vous pouvez tester une version plus récente pour un appel d'API en définissant l'en-tête Samsara-Version. Dans l'exemple de code ci-dessous, un utilisateur avec le <2018-01-01 jeton> pourrait faire un unique demande pour le 2019-02-22 version en passant un Version X-Samsara En-tête HTTP avec la version d'horodatage souhaitée :
GET -H "X-Samsara-Version: 2019-02-22" https://api.samsara.com/v1/fleet/list?access_token=<2018-01-01 token>
Une fois que vous êtes sûr que votre code peut gérer la dernière version, cliquez sur Mise à niveau dans votre tableau de bord Samsara. Cela change la version utilisée par les appels d'API sans en-tête Samsara-Version.
