API MyFox - gestion en PowerShell

Bonjour tout le monde,

Ardent utilisateur de PowerShell, j'ai créé un petit module pour utiliser les API de MyFox.

API MyFox existante | Description | Gérée par le module | Nom du cmdlet

authentification
post /oauth2/token | Get an application token | OUI | Get_MyFoxToken (pas de paramètre | sortie : objet contenant le token, et le refresh token)
post /oauth2/token | Get a refreshed token | OUI | Get_MyFoxRefreshedToken (paramètre : $refresh_token | sortie : objet contenant le nouveau token)

client | site
get /client/site/items | List available sites for the current user | OUI | Get_MyFoxSites (paramètre : $token | sortie : tableau d'objets site - contient le siteID)


site | device | camera
get /site/{siteId}/device/camera/items | List camera devices | OUI | Get_MyFoxCameras (paramètres : $token, $siteID | sortie : tableau d'objets caméra)
post /site/{siteId}/device/{cameraId}/camera/live/extend | Add 30 seconds to live streaming | NON
post /site/{siteId}/device/{cameraId}/camera/live/start/{protocol} | Start live streaming from a camera | NON
post /site/{siteId}/device/{cameraId}/camera/live/stop /Stop live streaming from a camera | NON
post /site/{siteId}/device/{cameraId}/camera/preview/take | Get a volatile preview from a camera | OUI | Get_MyFoxCameraPreview (paramètres : $token, $siteID, $camID, $picturepath (chemin où sera sauvegardée le fichier JPEG) | sortie : $true si OK, erreur sinon)
post /site/{siteId}/device/{cameraId}/camera/recording/start | Start recording from a camera | OUI | Start_MyFoxCameraRecording (paramètres : $token, $siteID, $camID | sortie : $videoID)
post /site/{siteId}/device/{cameraId}/camera/recording/stop | Stop recording from a camera | OUI | Stop_MyFoxCameraRecording (paramètres : $token, $siteID, $camID | sortie : $true si OK, erreur sinon)
post /site/{siteId}/device/{cameraId}/camera/snapshot/take | Take a snapshot from a camera and save it in the library | OUI | Get_MyFoxCameraSnapshot (paramètres : $token, $siteID, $camID | sortie : $imageID)

site | device | data | state
get /site/{siteId}/device/data/state/items | List devices with state data | OUI | Get_MyFoxDeviceState (paramètres : $token, $siteID | sortie : tableau d'objets "State Device") - NON TESTE
get /site/{siteId}/device/{deviceId}/data/state | Get device state | OUI | Get_MyFoxDeviceStateData (paramètres : $token, $siteID, $deviceID | sortie : objet "State Device") - NON TESTE

site | device | data | temperature
get /site/{siteId}/device/data/temperature/items | List all temperature sensor featured devices | OUI | Get_MyFoxDeviceTemp (paramètres : $token, $siteID | sortie : tableau d'objets "Capteur de température") - NON TESTE
get /site/{siteId}/device/{deviceId}/data/temperature | Get temperature measures | OUI | Get_MyFoxDeviceTempData (paramètres : $token, $siteID, $deviceID, [$datefrom], [$dateto] | sortie : tableau des relevés entre $datefrom et $dateto si spécifiés, sinon, tableau des relevés des 7 derniers jours) - NON TESTE


site | device | gate
get /site/{siteId}/device/gate/items | List gate devices | OUI | Get_MyFoxDeviceGate (paramètres : $token, $siteID | sortie : tableau d'objets "Module portail") - NON TESTE
post /site/{siteId}/device/{deviceId}/gate/perform/one | Perform action #1 | OUI | Start_MyFoxDeviceGateOne (paramètres : $token, $siteID, $deviceID | sortie : OK ou erreur) - NON TESTE
post /site/{siteId}/device/{deviceId}/gate/perform/two | Perform action #2 | OUI | Start_MyFoxDeviceGateTwo (paramètres : $token, $siteID, $deviceID | sortie : OK ou erreur) - NON TESTE

site | device | heater
get /site/{siteId}/device/heater/items | List heater devices | OUI | Get_MyFoxDeviceHeater (paramètres $token, $siteID | sortie : tableau d'objets "Module chauffage") - NON TESTE
post /site/{siteId}/device/{deviceId}/heater/eco | Set a heater to 'eco' mode | OUI | Set_MyFoxDeviceHeaterEco (paramètres : $token, $siteID, $deviceID | sortie : OK ou erreur) - NON TESTE
post /site/{siteId}/device/{deviceId}/heater/frost | Set a heater to 'frost' mode | OUI | Set_MyFoxDeviceHeaterFrost (paramètres : $token, $siteID, $deviceID | sortie : OK ou erreur) - NON TESTE
post /site/{siteId}/device/{deviceId}/heater/off | Set a heater to 'off' mode | OUI | Set_MyFoxDeviceHeaterOff (paramètres : $token, $siteID, $deviceID | sortie : OK ou erreur) - NON TESTE
post /site/{siteId}/device/{deviceId}/heater/on | Set a heater to 'on' mode | OUI | Set_MyFoxDeviceHeaterOn (paramètres : $token, $siteID, $deviceID | sortie : OK ou erreur) - NON TESTE

site | device | shutter
get /site/{siteId}/device/shutter/items | List shutter devices | OUI | Get_MyFoxDeviceShutter (paramètres : $token, $siteID | sortie : tableau d'objets "Module volet")
post /site/{siteId}/device/{deviceId}/shutter/close | Close shutter | OUI | Set_MyFoxDeviceShutterClose (paramètres : $token, $siteID, $deviceID | sortie : OK ou erreur)
post /site/{siteId}/device/{deviceId}/shutter/open | Open shutter | OUI | Set_MyFoxDeviceShutterOpen (paramètres : $token, $siteID, $deviceID | sortie : OK ou erreur)

site | device | socket
get /site/{siteId}/device/socket/items | List socket devices | OUI | Get_MyFoxDeviceSocket (paramètres : $token, $siteID | sortie : tableau d'objets "Prise télécommandée") - NON TESTE
post /site/{siteId}/device/{deviceId}/socket/off | Turn off a device | OUI | Set_MyFoxDeviceSocketOff (paramètres : $token, $siteID, $deviceID | sortie : OK ou erreur) - NON TESTE
post /site/{siteId}/device/{deviceId}/socket/on | Turn on a device | OUI | Set_MyFoxDeviceSocketOn (paramètres : $token, $siteID, $deviceID | sortie : OK ou erreur) - NON TESTE

site | group | electric
get /site/{siteId}/group/electric/items | List groups of type electric | OUI | Get_MyFoxGroupElectric (paramètres : $token, $siteID | sortie : tableau de groupes d'appareils électriques) - NON TESTE
post /site/{siteId}/group/{groupId}/electric/off | Turn off all electric devices from a group | OUI | Set_MyFoxGroupElectricOff (paramètres : $token, $siteID, $groupID | sortie : OK ou erreur) - NON TESTE
post /site/{siteId}/group/{groupId}/electric/on | Turn on all electric devices from a group | OUI | Set_MyFoxGroupElectricOn (paramètres : $token, $siteID, $groupID | sortie : OK ou erreur) - NON TESTE

site | group | shutter
get /site/{siteId}/group/shutter/items | List groups of type shutter | OUI | Get_MyFoxGroupShutter (paramètres : $token,$siteID | sortie : tableau de groupe de volets)
post /site/{siteId}/group/{groupId}/shutter/close | Close all shutters from a group | OUI | Set_MyFoxGroupShutterClose (paramètres : $token, $siteID, $groupID | sortie : OK ou erreur)
post /site/{siteId}/group/{groupId}/shutter/open | Open all shutters from a group | OUI | Set_MyFoxGroupShutterOpen(paramètres : $token, $siteID, $groupID | sortie : OK ou erreur)

site | history
get /site/{siteId}/history | Get site history | OUI | Get_MyFoxHistory (paramètres : $token, $siteID, [$datefrom], [$dateto], [$dateorder], [$type] | sortie : tableau des historiques triés via $dateorder - du plus vieux au plus récent par défaut), de telle à telle date (si $datefrom et $dateto renseignés) et du tel type (si $type est renseigné) - ne renvoie que 300 lignes)

site | library
get /site/{siteId}/library/image/items | Get all images taken from a site's cameras | OUI | Get_MyFoxLibraryImages (paramètres : $token, $siteID | sortie : tableau d'objets "Image")
get /site/{siteId}/library/video/items | Get all videos taken from a site's cameras | OUI | Get_MyFoxLibraryVideos (paramètres : $token,$siteID | sortie : tableau d'objets "Video")
get /site/{siteId}/library/video/{videoId}/play | Get video informations for HLS playing | NON

site | scenario
get /site/{siteId}/scenario/items | List available scenarios | OUI | Get_MyFoxScenarii (paramètres : $token, $siteID | sortie : tableau d'objets "Scénario")
post /site/{siteId}/scenario/{scenarioId}/disable | Disable a scenario | OUI | Disable_MyFoxScenario (paramètres : $token,$siteID,$scenarioID | sortie : $true ou erreur)
post /site/{siteId}/scenario/{scenarioId}/enable | Enable a scenario | OUI | Enable_MyFoxScenario (paramètres : $token,$siteID,$scenarioID | sortie : $true ou erreur)
post /site/{siteId}/scenario/{scenarioId}/play | Play a scenario | OUI | Start_MyFoxScenario (paramètres : $token,$siteID,$scenarioID | sortie : $true ou erreur)

site | security
get /site/{siteId}/security | Get site security level | OUI | Get_MyFoxSecurityLevel (paramètres : $token, $siteID | sortie : niveau de security actuel)
post /site/{siteId}/security/set/{securityLevel} | Set site security level | OUI | Set_MyFoxSecurityLevel (paramètres : $token, $siteID, $securitylevel | sortie : OK ou erreur)


Bonus :
Get_MyFoxLibraryImage (paramètres : $token, $siteID, $imageID, $picturepath | sortie : fichier image au format JPEG)
Get_MyFoxLibraryVideo (paramètres : $token, $siteID, $videoID, $videopath | sortie : fichier vidéo au format MP4)


Comme vous pouvez le voir, un certain nombre de commandes ne sont pas testées, dû au fait que je n'ai pas les équipements pour pouvoir les essayer... Si MyFox veut m'en fournir pour valider mes CMDLETs, je suis évidemment à l'écoute ...


Pour utiliser le module, l'ouvrir avec le bloc-note et compléter les variables globales en haut du fichier (ClientID, ClientSecret, Username et Password).

/!\ ATTENTION, il s'agit d'une v0.1, toute fraîche, ou aucun test d'erreur n'est effectué : les cmdlets peuvent crasher.

Je reste à disposition pour toute question

ça s'utilise comment?
sur PC....

je peu presque tous tester, sauf le module chauffage

Sur PC oui, avec Powershell v3 (de "série" sur Windows 8 ).

Tu remplis les informations nécessaires dans le module (via les données récupérées sur api.myfox.me)

Ensuite, tu crées un script powershell, et tu importes mon module :

Code:

import-module <chemin vers le fichier psm1>

Ensuite, première chose à faire est récupérer le token et le stocker

Code:

$mytoken = get_myfoxtoken

Après, tu récupères tes sites :

Code:

$mysites = get_myfoxsites $mytoken

Ce qui te donne un tableau de sites. Plus qu'à récupérer l'ID du site que tu veux...
Ex :

Code:

$mysites[0].siteID

Et tu as les deux plus importantes

j'obtiens le message ci dessous lors de l'import :

PS C:\WINDOWS\system32> set-executionPolicy RemoteSigned
PS C:\WINDOWS\system32> cd c:
PS C:\WINDOWS\system32> cd c:\
PS C:\> cd module_myfox
PS C:\module_myfox> Import-Module module_myfox.psm1
Import-Module : Le module «module_myfox.psm1» spécifié n'a pas été chargé, car aucun fichier de module valide n'a été
trouvé dans un répertoire de module.
Au caractère Ligne:1 : 1
+ Import-Module module_myfox.psm1
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : ResourceUnavailable: (module_myfox.psm1:String) [Import-Module], FileNotFoundException
+ FullyQualifiedErrorId : Modules_ModuleNotFound,Microsoft.PowerShell.Commands.ImportModuleCommand

PS C:\module_myfox>

Module mis à jour

j'ai un message d'erreur lorsque je souhaite récupérer mes sites :

PS C:\module_myfox\v2> Import-Module c:\module_myfox\v2\module_myfox.psm1
PS C:\module_myfox\v2> $mytoken = get_myfoxtoken
PS C:\module_myfox\v2> $mysites = get_myfoxsites $mytoken
Invoke-RestMethod : Le serveur distant a retourné une erreur : (401) Non autorisé.
Au caractère C:\module_myfox\v2\module_myfox.psm1:44 : 13
+ $data = Invoke-RestMethod -Uri $url -Body $body -Method Get
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidOperation : (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-RestMethod], WebEx
ception
+ FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeRestMethodCommand

PS C:\module_myfox\v2>

OK, my bad !

il faut faire :

$mysites = Get_MyFoxSites $mytoken.access_token

Désolé,
Toujours la même erreur...

Qu'obtiens tu quand tu tapes juste $mytoken suivi de entrée ?

voici le résultat de la commande :
PS C:\module_myfox\v2> $mytoken

error error_description
----- -----------------
invalid_grant A personal account can only be used by its owner

Ah ben voila le problème
As-tu bien rempli le fichier de module avec tes identifiants ?

oui en fin je pense :
$Global:CLIENTID = "7b87XXXXXX....." ID récupérer sur l'interface de l'API ->Client ID
$Global:CLIENTSECRET = "9xUtXXXX...." Idem ->Client Secret
$Global:USERNAME = mon@mail pour se connecter à l'API : https://api.myfox.me/
$Global:PASSWORD = mot de passe pour se connecter à l'API

C'est bien ça qu'il faut renseigner ?

Merci

Ca y ressemble bien oui ! C'est étrange, l'erreur que tu as dans $mytoken signifie que tu essaies de te connecter sur un compte qui t'appartient pas :/

voilà ce que j'ai dans l'interface:
Name Client ID Client Secret Redirect URL Status Control
Personal application 7b8700XXXXXX 9xUtXXXXXXXXX N/A Active
No application currently created.

Je ne suis pas chez moi jusqu'a demain pour pouvoir avancer... Je te dis des que je rentre !

Ok merci.
Bonne soirée

Concernant les variables $Global:USERNAME et $Global:PASSWORD, tu as bien mis les valeurs entre " " ?

Oui. Pour toutes les variables j'ai mis des " ".

j'ai essayé de supprimer la clé de l'API et d'en créer une autre, toujours le même résultat.

ca fonctionne chez toi ?

Oui, sans problème !
Alors là... C'est étrange !

@Myfox25

Pour juste tester ce que donne l'API la solution la plus simple est d'aller sur le site de l'API Myfox, page authentification (ICI en bas de cette page cliquer sur le bouton "Authorize", selon le cas :

• soit cela va sur la page d'authentication de Myfox (donc mettre les informations de connexion utilisées pour se connecter à l'interface WEB) puis on passe au point suivant,
  
• soit on est déjà authentifié et cela demande si l'on accepte que l'application "Demo" se connecte sur notre compte, bien entendu il faut accepter
  

Après validation cela revient sur la page de l'API, en bas le bouton a disparu et à la place il y a un texte semblable à

Code:

{"access_token":"6XXXXXXX40c74d6XXXXXX9aXXXXXXX606XXXXXXX","expires_in":3600,
"token_type":"Bearer","scope":null,"refresh_token":"8XXXXXXXeXXXXXXXaedXXXXXXX86XXXXXXX16899"}

Là copier le texte après "access_token" (sans les guillemets, dans mon example ce serait 6XXXXXXX40c74d6XXXXXX9aXXXXXXX606XXXXXXX), aller sur la page "Documentation" via le menu sur la gauche, vers le milieu du premier écran (selon votre résolution) il y a une boite avec marqué "Paste your token here" dedans, y coller le token copié précédemment puis cliquer sur le bouton "Authorize".

Si tout est ok, en dessous du bouton "Authorize" il y a maintenant un texte du style "Current token : 6XXXXXXX40c74d6XXXXXX9aXXXXXXX606XXXXXXX".

Maintenant il ne vous reste plus qu'à essayer chaque fonction, par exemple pour avoir la liste de ses sites, il faut cliquer sur le texte "client / site" puis sur "/client/site/items" puis sur le bouton "Try it out".

Noter que le SiteId est demandé pour toutes les autres fonctions, par exemple "site / security", il y a un champ dans lequel il est nécessaire de coller le SiteId pour lequel on souhaite connaitre l'état de protection avant de cliquer sur "Try it out".

Merci pour cette explication détaillée.
Cela fonctionne est j'arrive à me connecter et à tester l'API.

Par contre site / device / data / state, par exemple ne ma ramène pas l'ensemble de mes équipements avec leur états. Ne devrait il pas le faire ?
exemple :
site / device / data / state Show/Hide List Operations Expand Operations Raw
GET /site/{siteId}/device/data/state/items List devices with state data
Response Class
ModelModel Schema
DeviceWithStateCollection {
items (array[DeviceWithState]): List of objects
}
DeviceWithState {
deviceId (integer): The device identifier,
label (string): The device label,
stateLabel (string, null) = ['opened' or 'closed']: Current state,
modelId (string): The device model identifier,
modelLabel (string): The device model label
}

Response Content Type
Parameters
Parameter Value Description Parameter Type Data Type
siteId ID of user's site path integer
Hide Response
Request URL
https://api.myfox.me:443/v2/site/10346/device/data/state/items?access_token=754XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Response Body
{
"status": "OK",
"timestamp": 1408366698,
"payload": {
"items": []
}
}

Je devrais au moins retrouver mon module de détection d'ouverture enocean avec son état ?
Merci

Myfox25 a écrit:Merci pour cette explication détaillée.
Cela fonctionne est j'arrive à me connecter et à tester l'API.

De rien ça permet déjà de faire des tests rapides sans avoir à rien installer/développer sur sa machine ;-)

Myfox25 a écrit:Par contre site / device / data / state, par exemple ne ma ramène pas l'ensemble de mes équipements avec leur états. Ne devrait il pas le faire ?
exemple :
{
 "status": "OK",
 "timestamp": 1408366698,
 "payload": {
   "items": []
 }
}

Je devrais au moins retrouver mon module de détection d'ouverture enocean avec son état ?
Merci

Ben disons que maintenant on est fixés : pour le moment l'état courant des modules EnOcean n'est pas accessible depuis l'API... En effet le status de ta réponse est à "OK" mais avec un payload vide ce qui signifie que le serveur considère qu'il n'y a aucun équipement donnant son état présent sur ton système.

Great script, lpaso
Sorry, but I don't parlent français...
I am able to get access_token and SiteId, but when I try to get my shutters, I get a 401 Unauthorized. Do you know why?
Thanks you for your script.

Salut

Je viens de tester en partie ton script, ça fonctionne très bien, c'est exactement ce que je cherchais.

Par contre, il m'a fallu quelques minutes pour comprendre la syntaxe des commandes, voici ce que j'ai utilisé, si ça peut faire gagner 2 minutes de recherche :

$mytoken = get_myfoxtoken
$mysites = Get_MyFoxSites $mytoken.access_token

Get_MyFoxDeviceState $mytoken.access_token $mysites[0].siteID
Get_MyFoxScenarii $mytoken.access_token $mysites[0].siteID
Get_MyFoxGroupElectric $mytoken.access_token $mysites[0].siteID
Get_MyFoxDeviceSocket $mytoken.access_token $mysites[0].siteID

Mise en variable d'un équipement (manuellement pour les tests ):
$deviceID = 173717

Puis allumage de l'équipement via cette commande :
Set_MyFoxDeviceSocketOn $mytoken.access_token $mysites[0].siteID $deviceID

Extinction de l'équipement :
Set_MyFoxDeviceSocketOff $mytoken.access_token $mysites[0].siteID $deviceID

Tu peux modifier tes lignes "NON TESTE" par "TESTE OK" ;-)

Je vais continuer à tester ce que je peux, en tout cas merci pour ce partage.

Cdt
Franck

Testé et approuvé :
Get_MyFoxDeviceHeater $mytoken.access_token $mysites[0].siteID
$deviceID = 172658
Set_MyFoxDeviceHeaterEco $mytoken.access_token $mysites[0].siteID $deviceID
Set_MyFoxDeviceHeaterFrost $mytoken.access_token $mysites[0].siteID $deviceID
Set_MyFoxDeviceHeaterOn $mytoken.access_token $mysites[0].siteID $deviceID
Set_MyFoxDeviceHeaterOff $mytoken.access_token $mysites[0].siteID $deviceID