Webhook et différences API

Il existe deux façons d’obtenir les données de périphérique de nos serveurs: Utiliser le Webhook ou le REST.

La différence entre un webhook et REST est que le webhook est événementiel.

Par exemple, chaque fois qu’un message d’appareil est reçu par le serveur, un webhook appelle l’URL configurée.

L’API REST n’est pas événementielle, ce qui signifie que vous devez faire un sondage auprès du serveur pour obtenir les données.

Le plus souvent, l’utilisation de webhook est préférée, mais dans ce guide les deux méthodes seront expliquées.

Webhook (HTTP push API) Guide

Il s’agit d’un processus en deux étapes, d’abord vous devez configurer l’URL Webhook, puis créer un script pour recevoir les données du webhook.

En utilisant cela, vous aurez un POST sur cette URL, le corps du POST contiendra les informations sur le message / l’événement.

1. Configuration de l’URL Webhook

IFTTT API Configuration
Dans votre page Hidnseek, à gauche, développez la liste de vos périphériques et sélectionnez la balise souhaité.

Cliquez sur le bouton “IFTTT/API Configuration”.

Choisissez si vous voulez un webhook pour les messages ou pour les alertes. Choisissez des messages si vous souhaitez recevoir des webhooks pour chaque message que le message envoie (GPS, Motion, etc.), ou choisissez les alertes si vous désirez des webhooks pour chaque alerte (zone entrée dans le périphérique), vous pouvez configurer des alertes dans la page principale du périphérique sous Lien “Règles”.

Enregistrez dans la ou les zones souhaitées le lien vers votre serveur/script qui traitera le webhook.
IFTTT Webhook Configuration

2. Format du message webhook

Le message envoyé par le webhook est formaté par JSON. Les champs suivants sont disponibles:

 

2.1 Message Webhook

Champ Description
id ID interne du message
device_id Sigfox/LoRa ID de l’appareil
lat Latitude de l’appareil (nulle si non connu)
lon Longitude de l’appareil (nulle si non connu)
battery Valeur de la batterie
cap Direction en degrés
snr Le rapport signal / bruit du message, en dB
speed La vitesse du tracker au moment du message
altitude Altitude de l’appareil
temp Température en degrés (nulle si non connu)
press Pression (nulle si non connu)
timestamp Horodatage format UNIX du message
recorded_at Horodatage décodé
sat Nombre de satellites GPS trouvés
seq_number Numéro du message de l’appareil. Notez que dans la version Sigfox, ce numéro se réinitialise à 4096 et également lorsque vous redémarrez la version LoRa
type_event Type d’événement, qui sont: Motion, No Motion, GPS, Pas de GPS, Bouton, Batterie faible
tower Antenne qui a reçu le message
extra Des informations supplémentaires, lorsque “Enregistré” est ici, cela signifie que ce point a été enregistré plus tôt (au moment de l’horodatage) mais n’a été envoyé que maintenant

Un exemple de message reçu:

{
"id" : 596697,
"lat" : 48.8362617492676,
"lon" : 2.29410195350647,
"battery" : 86.0,
"cap" : 270.0,
"snr" : 11.82,
"speed" : 0.0,
"timestamp" : 1469184107,
"device_id" : "746B4",
"recorded_at" : "2016-07-22T10:41:47.000Z",
"altitude" : 0.0,
"sat" : 0,
"type_event" : "Motion",
"temp" : null,
"press" : null,
"seq_number" : 665,
"extra" : null
}

2.2 Alerte Webhook

Champ Description
activated_at La date du début de l’alerte
active False/true si l’alerte est toujours active ou terminée
desactivated_at Heure de la fin de l’alerte
msg Une chaîne lisible sur le message
rule_type Le type de règle qui a généré l’alerte (“MotionRule”, “PolyRule”, “CircleRule”, “BatteryRule”)
rule_name Le nom de la règle qui a généré l’alerte
event_start L’événement qui a déclenché le début de l’alerte, avec le même format que dans le message API push
event_end Si l’alerte s’est terminée, ce champ contient l’événement qui a généré la fin de l’alerte, dans le même format que dans le message API Push
device Le périphérique sur lequel s’applique l’événement

Un exemple d’alerte Webhook reçu:

{
"alert" : {
"activated_at" : "2016-10-11T18:54:31.435Z",
"active" : false,
"alert_id" : null,
"desactivated_at" : "2016-10-12T08:27:46.033Z",
"event" : null,
"msg" : "Alert, tracker is not moving",
"rule_type" : "MotionRule",
"rule_name" : "Motion",
"event_start" : {
"id" : 818803,
"lat" : 43.490119934082,
"lon" : 3.71486306190491,
"battery" : 41.0,
"cap" : 270.0,
"snr" : 8.37,
"speed" : 0.0,
"timestamp" : 1476212070,
"device_id" : "73918",
"recorded_at" : "2016-10-11T18:54:30.000Z",
"altitude" : 0.0,
"sat" : 0,
"type_event" : "No motion",
"temp" : 15.6,
"press" : 1012.0,
"seq_number" : 1419,
"extra" : null
},
"event_end" : {
...
},
"device" : {
"id" : "999",
"name" : "Dummy"
}
}
}

 

3. Exemple de configuration d’un script

Puisque le webhook envoie un POST à ​​l’URL, le script pointu doit gérer le POST.

Un exemple simple en PHP qui sauvegarde les données dans un fichier:

<!--?php // Getting data from webhook $data = json_encode($_POST); // Saving data to a file file_put_contents("webhook.log",$data . "\n", FILE_APPEND); ?-->

Un autre exemple en PHP qui envoi les données par courrier électronique:

<!--?php // Get necessary data from POST $dev_id = $_POST["device_id"]; $event = $_POST["type_event"]; $lat = $_POST["lat"]; $lon = $_POST["lon"]; $to = 'example@hidnseek.fr'; $subject = "New message from device {$dev_id}"; $message = "Device {$dev_id} sent a {$event} message at location: Latitude = {$lat} Longitude = {$lon} "; $headers = 'From: contact@hidnseek.com' . "\r\n" . 'Reply-To: contact@hidnseek.com' . "\r\n" . 'X-Mailer: PHP/' . phpversion(); mail($to, $subject, $message, $headers); ?-->

Remarque: si le type de message est différent du GPS, lat et lon contiennent des informations du dernier GPS qu’il a obtenu, ce n’est pas la position actuelle de l’appareil.

 

Guide REST (HTTP Pull API)

Cette section vous guidera en utilisant notre API HTTP Pull pour obtenir des données de suivi de nos serveurs.

Il s’agit d’un processus en deux étapes. Le premier consistant à obtenir votre jeton d’authentification et le second à tirer les données de nos serveurs au format JSON.

1. Obtenir votre jeton d’authentification

Pour obtenir votre jeton d’authentification, vous devrez appeler la fonction users / sign_in

Par exemple, on peut générer une demande POST en utilisant cURL vers notre HTTP Pull API, en utilisant le terminal, PHP ou toute autre méthode disponible.

Vous devrez envoyer une demande POST avec les champs suivants:

user[email]: Registered email address
user[password]: Password

À l’URL suivante:

https://api.hidnseek.fr/users/sign_in.json

1.1 Exemple en utilisant cURL et le terminal

C’est la façon privilégiée de faire cela.
Dans un émulateur de terminal avec CURL, tapez:

curl -i -X POST -F "user[email]=EMAIL" -F "user[password]=PASSWORD" 'https://api.hidnseek.fr/users/sign_in.json'

Le shell retournera votre jeton

1.2 Exemple en utilisant PHP

En PHP, vous pouvez utiliser le code suivant:

<!--?php // Login Data $login_data = array( 'user[email]' =&gt; 'EMAIL', 'user[password]' =&gt; 'PASSWD' ); // Start cURL $ch = curl_init(); // to authenticate use this url curl_setopt($ch, CURLOPT_URL, 'https://api.hidnseek.fr/users/sign_in.json'); // Make curl_exec return result curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Tell cURL we have POST data curl_setopt($ch, CURLOPT_POST, 1); // Tell cURL which data to POST curl_setopt($ch, CURLOPT_POSTFIELDS, $login_data); // Execute $output = curl_exec($ch); // Close cURL curl_close($ch); // Decode JSON $out = json_decode($output, true); // Get authentication token $auth = $out['authentication_token']; echo $auth; ?-->

Vous aurez votre jeton d’authentification dans la variable $auth.

2. Récupérer les données des périphériques depuis le serveur

Maintenant que nous avons le jeton d’authentification, nous pouvons procéder de deux façons:

2.1 Authentification dans l’URL

Avec l’adresse e-mail et le jeton d’authentification, utilisez l’URL suivante:

Pour plusieurs appareils Pour un appareil
https://api.hidnseek.fr/devices.json?user_email=EMAIL&amp;user_token=TOKEN https://api.hidnseek.fr/device/DEVICEID.json?user_email=EMAIL&amp;user_token=TOKEN

Cela renverra une chaîne codée JSON avec les données de l’appareil(s).

2.1.1 Exemple PHP: Authentification dans l’URL

Voici un exemple tirant des données de l’API en utilisant PHP et CURL.

<!--?php $email = 'your@email.com'; $auth = 'your_token'; // URLs $URL_all_devices = "https://api.hidnseek.fr/devices.json?user_email=" . $email . "&user_token=" . $auth; $URL_one_device = "https://api.hidnseek.fr/devices/DEVICEID.json?user_email=" . $email . "&user_token=" . $auth; // Init cURL $ch = curl_init(); // Set URL: either $URL_all_devices or $URL_one_device curl_setopt($ch, CURLOPT_URL, $url); // Store response in variable $output curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Execute cURL and save response to $output $output = curl_exec($ch); // Check output print_r($output); ?-->

Les données sont obtenues dans une chaîne formatée JSON.

2.2 Authentification dans les en-têtes

Alternativement, il est possible de s’authentifier dans les en-têtes, en envoyant les informations suivantes dans les en-têtes:

X-User-Email your@email.com
X-User-Token your_token

2.2.1 Exemple PHP: Authentification dans les en-têtes

Voici un exemple de récupération des données en utilisant PHP et CURL.

<!--?php $email = 'your@email.com'; $auth = 'your_token'; $url = "https://api.hidnseek.fr/devices/deviceID.json"; // for one device $url = "https://api.hidnseek.fr/devices.json"; // for all devices $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); // Authentication in header curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'X-User-Email: ' . $email, 'X-User-Token: ' . $auth )); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $output = curl_exec($ch); print_r($output); ?-->

3. Récupérer les données d’un seul appareil du serveur

C’est la façon la plus simple de faire cela.
Dans un émulateur de terminal avec CURL, tapez:

curl -X GET -F "key=495KLTD1" -F "num=1" -F "type_event=GPS" 'https://api.hidnseek.fr/devices/1AEF8/positions.json'

ou

curl "https://api.hidnseek.fr/devices/1AEF8/positions.json?key=495KLTD1&num=1&type_event=GPS"

Le shell retournera votre position au format json

Les Type_event peut être “GPS”, “No GPS”, “Motion”, “No motion”, “Button”, “all”