1. Résumé
Les API permettent aux personnes/développeurs d'interagir avec les services cloud et de gérer les ressources fournies par un fournisseur de cloud (dans notre cas Shelly Cloud).
DOCUMENTATION
2. Fonctionnalités
Avec l'API du nuage Shelly, pour l'instant (19/6/23), vous pouvez faire les choses suivantes :
obtenir l'état actuel de l'appareil
pour les relais : commuter chaque sortie individuellement
pour les couvercles : commandes d'ouverture/fermeture/arrêt et définition d'une position
pour les lumières colorées : marche/arrêt, mise à jour de la couleur, mise à jour du gain pour chaque canal
pour les lumières blanches : marche/arrêt, mise à jour de la luminosité pour chaque canal
groupes (plusieurs relais en même temps/avec une seule demande) : uniquement les relais conformément à la documentation.
Types de requêtes prises en charge :
GET - pour obtenir des informations du serveur (aucune modification de la base de données n'est nécessaire) : pour obtenir l'état de l'appareil.
POST - lors de la modification/du téléchargement de nouvelles données dans la base de données : pour modifier l'état, la couleur ou les paramètres de sortie de l'appareil.
3. Comment utiliser le système
Les demandes peuvent être envoyées par de nombreuses méthodes telles que curl, postman, script python, script exécuté sur le dispositif Shelly, etc.
Comment obtenir le dernier état de l'appareil via l'API Shelly Cloud et curl ?
Chemin d'accès : https://<***server_uri>/device/status
Méthodes prises en charge : GET et POST
Les paramètres sont fournis via la *requête ou avec le **corps de la requête.
Informations requises pour envoyer la requête :
L'ID de l'appareil cible : key = 'id'
Le compte ****clé d'authentification : key = 'auth_key'
Le résultat est un objet JSON avec l'état de l'appareil.
Comment contrôler la sortie d'un relais :
Chemin d'accès : https://<***server_uri>/device/relay/control
Méthodes prises en charge : POST
Les paramètres sont fournis UNIQUEMENT par l'intermédiaire du **corps de la demande.
Informations requises pour l'envoi de la demande :
L'ID de l'appareil cible : key = 'id'
Le compte ****authentication key' : key = 'auth_key'
Le canal qui doit être mis à jour : key = 'channel' (premier canal : 0 (appareils à canal unique), deuxième canal : 1)
L'état mis à jour pour la sortie : key = 'turn' (valeurs prises en charge : on et off)
Le résultat est un JSON avec l'ID de l'appareil cible.
Comment ouvrir/fermer un dispositif de volet roulant :
Chemin d'accès : https://<***server_uri>/device/relay/roller/control
Méthodes prises en charge : POST
Les paramètres sont fournis UNIQUEMENT par l'intermédiaire du **corps de la demande.
Informations requises pour envoyer la demande :
L'identifiant du dispositif cible : key = 'id'
Le compte ****authentication key' : key = 'auth_key'
La commande de direction : key = 'direction' (valeurs supportées : open, close et stop)
Le résultat est un JSON avec l'ID de l'appareil cible.
Comment définir une position pour un dispositif de volet roulant :
Chemin d'accès : https://<***server_uri>/device/relay/roller/control
Méthodes prises en charge : POST
Les paramètres sont fournis UNIQUEMENT par l'intermédiaire du **corps de la demande.
Informations requises pour envoyer la demande :
L'identifiant du dispositif cible : key = 'id'
Le compte ****authentication key' : key = 'auth_key'
La position en pourcentage : key = 'pos' (valeurs supportées : toutes les valeurs complètes de 0 à 100(inclus))
Le résultat est un JSON avec l'ID de l'appareil cible.
Comment mettre à jour la sortie du dispositif de contrôle des couleurs :
Chemin d'accès : https://<***server_uri>/device/light/control
Méthodes prises en charge : POST
Les paramètres sont fournis UNIQUEMENT via le **corps de la requête
Informations requises pour envoyer la requête :
L'ID de l'appareil cible : key = 'id'
Le compte ****authentication key' : key = 'auth_key'
L'état actualisé de la sortie : key = 'turn' (valeurs supportées : on et off)
La valeur du canal blanc : key= 'white' (valeurs prises en charge : toutes les valeurs complètes de 0 à 255 (incluses))
La valeur du canal rouge : key= 'red' (valeurs prises en charge : toutes les valeurs de 0 à 255 (incluses))
La valeur du canal vert : key= 'green' (valeurs prises en charge : toutes les valeurs de 0 à 255 (incluses))
La valeur du canal bleu : key= 'blue' (valeurs prises en charge : toutes les valeurs de 0 à 255 (incluses))
La valeur pour le gain : key= 'gain' (valeurs prises en charge : toutes les valeurs de 0 à 100 (incluses))
Le résultat est un JSON avec l'ID de l'appareil cible.
Comment mettre à jour la sortie d'un variateur de lumière :
Chemin d'accès : https://<***server_uri>/device/light/control
Méthodes prises en charge : POST
Les paramètres sont fournis UNIQUEMENT via le **corps de la requête
Informations requises pour envoyer la demande :
L'ID de l'appareil cible : key = 'id'
Le compte ****authentication key' : key = 'auth_key'
L'état actualisé de la sortie : key = 'turn' (valeurs prises en charge : on et off)
La valeur de luminosité : key= 'brightness' (valeurs prises en charge : toutes les valeurs complètes de 0 à 100 (incluses))
Le résultat est un JSON avec l'ID de l'appareil cible
*query : Les paramètres situés après le point de terminaison commencent par le symbole du point d'interrogation ( ?) et se terminent par le symbole du hashtag ou jusqu'à la fin de la demande. Les données sont formatées sous forme de paires clé=valeur, où la clé se trouve avant le symbole égal (=) (ex. ivan=petyr, la clé est "ivan", et la valeur est "petyr") et la valeur se trouve après. Lorsque plusieurs paires sont nécessaires, elles doivent être séparées par le symbole et (&).
**corps : Il s'agit de la partie de la requête où des informations sensibles peuvent être envoyées, cachées dans l'URL de la requête (pas dans la requête). Si vous utilisez curl pour envoyer la requête, les données du corps sont préfixées par '-d' et les paramètres sont écrits de la même manière que la requête sous forme de paires clé=valeur et séparés par le symbole and.
***server_uri : L'URL du serveur où se trouvent tous les appareils et comptes du client. Vous pouvez l'obtenir à partir de l'application Shelly > Paramètres de l'utilisateur > Clé d'autorisation dans le nuage
****Clé d'authentification : Clé unique dont la génération est basée sur le mot de passe du compte du client. Lorsque le mot de passe est modifié, la clé d'authentification est également modifiée.