Comment utiliser notre API
1
.
Qu'est-ce qu'une API ?
Le terme API signifie Application Programming Interface (interface de programmation d'applications). Il s'agit d'un protocole de communication conçu pour simplifier l'échange de données entre un client et un serveur. La communication se fera dans un format strict, ou initiera une action particulière, de manière à ce qu'ils se complètent parfaitement.
Une clé API est un identifiant unique utilisé pour authentifier un utilisateur ou un programme qui invoque l'API.
2
.
Que signifie l'API pour les utilisateurs de notre plateforme ?
Cela signifie que vous pouvez utiliser l'API pour facilement envoyer des données à notre plateforme ou en extraire.
Envoie vos propres données pour les combiner avec les données déjà présentes sur notre plateforme. Il peut s'agir de données provenant d'un système ERP ou CRM, ou de capteurs et de systèmes de mesure. Vous pouvez également demander des données pour les utiliser dans votre propre application.
3
.
Comment utiliser notre API et notre clé API ?
1. Créez une clé API
L'API étant en version bêta publique, la clé API doit être demandée par courriel à help@calculus.group. Vous pouvez nous contacter en envoyant un courrier électronique, avec objet "Request API key for Calculus". Dans cet e-mail, veuillez nous indiquer pour quelle entreprise vous avez besoin de la clé API et à quelles fins vous l'utiliserez.
Veuillez noter!Si la clé API serait compromise, veuillez nous envoyer un courriel à la même adresse pour révoquer la clé.
2. Utilise l'API pour obtenir des données
Grâce à l'API, vous pouvez récupérer les données de tous les actifs associés à l'entreprise à laquelle appartient la clé API. Le point de terminaison pour récupérer les données est "https://api.calculus.group/asset/{key}". Remplace {key} par l'identifiant unique de l'actif. Les appels sont effectués avec l'action HTTP "GET".
Paramètres
|
epochStart
|
Le début de la série temporelle pour laquelle vous avez besoin de données. Le format de date et d'heure utilisé est "Epoch", le code temporel d'UNIX. Pour les outils de conversion de et vers Epoch, vois https://www.epochconverter.com/. Si vous utilisez ce paramètre, il doit toujours être utilisé avec le paramètre "epochEnd". Si elle n'est pas utilisée, la valeur par défaut est celle des dernières 24 heures. |
|
epochEnd
|
La fin de la série temporelle pour laquelle vous avez besoin de données. Le format de date et d'heure utilisé est "Epoch", le code temporel d'UNIX. Pour les outils de conversion de et vers Epoch, vois https://www.epochconverter.com/. Si vous utilisez ce paramètre, il doit toujours être utilisé avec le paramètre "epochEnd". Si elle n'est pas utilisée, la valeur par défaut est celle des dernières 24 heures. |
Headers
Dans les en-têtes, vous envoyez la clé API à la plateforme Calculus pour authentifier votre appareil.
|
CalculusApiKey |
Utilise la clé API que vous avez obtenue à l'étape 1 pour vous authentifier auprès de l'API. |
Modèle JSON
Le cœur de la demande est toujours au format JSON.
3. Utilise l'API pour publier des données
Le point de terminaison de l'API pour l'envoi de données à notre plateforme est "https://api.calculus.group/General/PostData". Les appels sont effectués avec l'action HTTP "POST".
Paramètres
|
version de l'api
|
La version de l'API que vous souhaitez appeler. La version 1.0 est obsolète, la version 2.0 est actuellement préférée. Utilise "api-version=2.0". |
Un appel typique serait un POST : "https://api.calculus.group/General/PostData?api-version=2.0".
Headers
Dans les en-têtes, vous envoyez la clé API à la plateforme Calculus pour authentifier votre appareil.
|
CalculusApiKey |
Utilise la clé API que vous avez obtenue à l'étape 1 pour vous authentifier auprès de l'API. |
4
.
Modèle JSON
Le cœur de la demande est toujours au format JSON. L'utilisation de "check-deltas" et "reset-deltas" est utilisée lorsque les valeurs peuvent déborder et être remises à 0. Si vous souhaitez obtenir les valeurs cumulées correctes, ceci peut être utilisé pour les calculer dans notre backend. Veuillez nous contacter pour plus d'informations sur la méthode de exécution à help@calculus.group.
Les valeurs suivantes peuvent être définies :
|
device |
Nom de l'appareil de la passerelle à laquelle vous souhaitez ajouter des données. S'il n'existe pas, la passerelle sera ajoutée automatiquement. Utilise le préfixe avec la clé API de l'appareil que vous avez choisi, dans le format suivant: "prefix_gateway". |
||||||
|
timestamp (horodatage) |
Secondes depuis le Jan. 1, 1970 (époque). |
||||||
|
check-delta
|
Actuellement disponible uniquement après avoir marqué un chemin de mesure comme delta. Veuillez nous contacter pour plus d'informations à l'adresse help@calculus.group. |
||||||
|
reset deltas (réinitialise les deltas) |
Actuellement disponible uniquement après avoir marqué un chemin de mesure comme delta. Veuillez nous contacter pour plus d'informations à l'adresse help@calculus.group. |
||||||
|
measurements (mesures) |
Un tableau de valeurs de mesure que vous souhaitez ajouter. Il peut s'agir d'une valeur, d'une une chaîne de caractères, ou les deux.
|
Exemple d'un corps JSON
{
"device": "prefix_TestDevice",
"check-deltas": true,
"reset-deltas": true,
"timestamp":1573206752,
"measurements:
[
{
"path": "measurement_1",
"value": 1
},
{
"path": "measurement-2",
"stringValue": "OFF"
},
{
"path": "temp|measurement.3",
"value": 9.4,
"stringValue": "BROKEN"
},
{
"path": "temp|measurement.4",
"value": 11.4,
"stringValue": "OVERLOAD"
}
]
}