Cortex WebAPI using PowerShell

Collapse
X
 
  • Filter
  • Time
  • Show
Clear All
new posts
  • Paul_B
    Automated Home Legend
    • Jul 2006
    • 608

    Cortex WebAPI using PowerShell

    Microsoft PowerShell is a 'bash' like shell and scripting language that is native to Windows 10 and installable as an addition / upgrade to versions of Windows back to 7. It is worth upgrading to the latest version which is currently 5.1 and is part of the Windows Management Framework - https://www.microsoft.com/en-us/down...190a24fa6=True

    Cortex has a WebAPI that, licensing permitting, provides a RESTful interface.

    WebAPI.jpg

    You'll need to check and if necessary enable the following
    • Web Server - Enabled
    • Add a user - Web Site Mode : Control - Enabled, Allow Control - Enabled, Web API : Allow Access - Enabled.


    N.B. - If you know the IP address of the workstation accessing the WebAPI of Cortex and this address is static then you can set Sender : Enable Verification, set the IP of the accessing workstation and check 'This IP Address does not require logon'. Doing so makes the PowerShell interaction much simpler. I'll cover constructing headers to pass user credentials at the end.

    In PowerShell commands are called cmdlets and everything that is returned is an object with properties and methods. Well use the Invoke-RestMethod cmdlet

    Code:
    $CortexIP = '192.168.10.13'
    $APIURI = 'api/v1/json/Ports/BedRm1-Master-Temperature/Temperature Output'
    $APIresponse = Invoke-RestMethod -Method Get -Uri "http://$cortexIP/$APIuri" 
    $APIResponse.CortexAPI.PortEvent.Value
    Let's analyse what the script is doing:
    • The first line, $CortexIP, creates a constant for the IP address of the machine running Cortex, in this case 192.168.10.13
    • The next line, $APIURI, creates a constant with the construct of the API call from Cortex documentation 'api/v1/json/Ports/' instead of ports you can have Objects or Properties. The next element, BedRm1-Master-Temperature, is the name of sensor in my Cortex database (you can also use objectID but this is not obvious [it is not the node ID as I had originally assumed]). Finally, we want the Port Name, this can be the Port Index or the Port Name, in my example I am using the Port Name.
    • Now we are actually going to do something, $APIResonse, is a variable that will content the output of the Invoke-RestMethod cmdlet. The parameters we pass to the cmdlet are the Rest Method to use, Get, and the URI, which is the RESTful endpoint
    • As mentioned previously everything in PowerShell is an object so using dot notation I can traverse the objects, $APIResponse, properties to return the value. The value being the current temperature.


    Screenshot shows dot notation traversal:
    CortexAPITraversal.jpg

    The example is a Get, to Set something you need to use the POST method but we'll do that another time.

    Authentication
    The example above works because in Cortex we set the "This IP Address does not require logon". In order to authenticate we have to do a bit more as Cortex expects a basic authentication in the initial call. Unlike CURL, from Linux, Powershell expects a 401 error and then authenticates. To get around this we can create an authentication header, the code becomes:

    Code:
    $user = '[I]user[/I]'
    $pass = '[I]password[/I]'
    $pair = "$($user):$($pass)"
    $encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
    $basicAuthValue = "Basic $encodedCreds"
    
    $Headers = @{
        Authorization = $basicAuthValue
    }
    
    $CortexIP = '192.168.10.13'
    $APIURI = 'api/v1/json/Ports/BedRm1-Master-Temperature/Temperature Output'
    $APIresponse = Invoke-RestMethod -Method Get -Uri "http://$cortexIP/$APIuri" -Headers $Headers
    $APIResponse.CortexAPI.PortEvent.Value
    See the following Stackoverflow article for a detailed discussion - https://stackoverflow.com/questions/...ntication-on-t

    Hope this may be of use to others

    Paul
    Last edited by Paul_B; 26 September 2017, 09:02 PM.
  • chris_j_hunter
    Automated Home Legend
    • Dec 2007
    • 1713

    #2
    Paul -

    many thanks, brilliant ...

    Chris
    Our self-build - going further with HA...

    Comment

    Working...
    X