Routing a request to an ECLYPSE controller through the Cloud Relay can be acheived in 3 simple steps:
/path[?query][#fragment]
as a custom header named Remote-Query
which becomes the URL that will be executed by the ECLYPSE Rest API.https://{cloudRelayHostname}/api/v1/devices/{deviceId}/request
where {deviceId}
is the unique ID used when creating the IoT Device registration in IoT Hub.Authorization
header by the Bearer authentication scheme.
NOTE: Routing a request to a custom device is also achieved using the same authentication scheme, request URL and
Remote-Query
custom header which can contain any information relevant to the device.
Examples below are intended to show the differences between a standard REST API call to an Eclypse controller and the same call through the Cloud Relay.
Example Request:
GET https://10.0.0.1/api/rest/v1/info HTTP/1.1
Authorization: Basic bmljZTp0cnk=
Host: 10.0.0.1
Example Response:
HTTP/1.1 200 OK
Server: nginx/1.12.2
Date: Wed, 06 Nov 2019 17:23:41 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 428
Connection: keep-alive
Set-Cookie: ECLYPSERESTSESSIONID=1vc4erhbezswk1u7n13x9wnpki;Path=/;Secure;HttpOnly
Expires: Thu, 01 Jan 1970 00:00:00 GMT
{"device":{"href":"\/api\/rest\/v1\/info\/device","name":"device"},"apiRevision":"8.0","bacnet":{"href":"\/api\/rest\/v1\/info\/bacnet","name":"bacnet"},"extensionManagement":{"href":"\/api\/rest\/v1\/info\/extension-management","name":"extensionManagement"},"supportedServices":{"href":"\/api\/rest\/v1\/info\/supported-services","name":"supportedServices"},"network":{"href":"\/api\/rest\/v1\/info\/network","name":"network"}}
Example Request:
GET https://{cloudRelayHostname}/api/v1/devices/ECY-S1000-CD4058/request HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1hdfgthYJhbGciOiJSUzI1NiIsIng1dCIr6IkhsdQzB...
Remote-Query: /api/rest/v1/info
Host: {cloudRelayHostname}
Example Response:
HTTP/1.1 200 OK
Content-Length: 368
Content-Type: application/json
Server: Kestrel
Request-Context: appId=cid-v1:71ac2cd5-1f7a-4782-b09c-fc85c32d447b
Strict-Transport-Security: max-age=2592000
X-Powered-By: ASP.NET
Date: Wed, 06 Nov 2019 17:24:21 GMT
{"device":{"href":"\/api\/rest\/v1\/info\/device","name":"device"},"apiRevision":"8.0","bacnet":{"href":"\/api\/rest\/v1\/info\/bacnet","name":"bacnet"},"extensionManagement":{"href":"\/api\/rest\/v1\/info\/extension-management","name":"extensionManagement"},"supportedServices":{"href":"\/api\/rest\/v1\/info\/supported-services","name":"supportedServices"},"network":{"href":"\/api\/rest\/v1\/info\/network","name":"network"}}
Only a subset of the request headers are actually routed to the device, all others are being discarded. Here are the headers currently supported:
Accept
Content-Type
The Cloud Relay makes use of OAuth 2.0 Bearer tokens to authenticate/authorize incoming requests. Not providing this token will result in a 401 Unauthorized
error.
The following example demonstrates how to redeem a Cloud Relay API access token using the identity of the previously registered Cloud Relay client application (client credentials flow). For more information about authorization flows, see the Microsoft identity platform documentation.
Example Request:
POST https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: login.microsoftonline.com
grant_type=client_credentials&client_id={cloudRelayClientAppId}&client_secret=S0meHardT0GuessPassw0rd&scope={cloudRelayApiAppId}/.default
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 1128
Strict-Transport-Security: max-age=31536000; includeSubDomains
Date: Fri, 21 Feb 2020 20:40:38 GMT
{
"token_type": "Bearer",
"expires_in": 3599,
"ext_expires_in": 3599,
"access_token": "{the access token to use}"
}
NOTE: Consider using the Microsoft Authentication Library (MSAL) to easily acquire tokens from the Microsoft Identity Platform with consistent APIs for a number of languages and frameworks.
Here's the list of custom errors that can be generated by the Cloud Relay API:
Error code | Value | HTTP Status Code | Description |
---|---|---|---|
InvalidResponseTimeout | 100 | 400 | responseTimeout specified in the request URL is invalid. |
DeviceNotFound | 1000 | 404 | deviceId specified in the request URL does not exist. |
DeviceOperationError | 1001 | 504 | The device operation timed out. |
InvalidResult | 1002 | 502 | Invalid response payload received from the device. |
CommunicationError | 5000 | 503 | An error occured while communicating with the gateway. |
GatewayError | 5001 | 503 | An error occured in the gateway which prevents communication with the device. |