IoTHub Manager Devices API

Query devices (GET mode)

GET /v1/devices?query=<query>

Two types of query supported:

1. Serialized Clause list in JSON. Each clause includes three parts: key, operator and value. The operator could be one of values below: EQ, NE, LT, LE, GT, GE and IN. Example:

• [{"key": "tags.Floor", "operator": "NE", "value": "10F"}]
• [{'key': 'deviceId', 'operator': 'IN', 'value': ['devic001', 'device002']}]

1. The "Where" clause of official IoTHub query string, except keyword WHERE. Examples:

• tags.Floor != "10F"
• deviceId in ['device001', 'device002']

Response

Returns 200 OK and list of device objects:

{
  "items": [
    ...
  ],
  "$metadata": {
    "$type": "DeviceList;1",
    "$uri": "/v1/devices"
  }
}

Please check API Get single device for detail of the device object

Query devices (POST mode)

POST /v1/devices/query

Body should be same as the query for the GET mode

Response

Same as the GET mode

Get single device

GET /v1/devices/{id}

Response

Return 200 OK and the device object:

{
  "Id": <device ID>,
  "Etag": <etag>,
  "C2DMessageCount": 0,
  "LastActivity": "2017-07-27T11:26:39.5250408",
  "Connected": true,
  "Enabled": true,
  "LastStatusUpdated": "0001-01-01T00:00:00",
  "IoTHubHostName": <IoTHub host name>,
  "Properties": {
    "Reported": { ... },
    "Desired": { ... }
  },
  "Tags": { ... },
  "IsSimulated": false,
  "Authentication": {
    "AuthenticationType": <authentication type>,
    "PrimaryKey": <primary key>,
    "SecondaryKey": <secondary key>,
    "PrimaryThumbprint": <thumbprint of the primary certificate>,
    "SecondaryThumbprint": <thumbprint of the secondary certificate>
  },
  "$metadata": {
    "$type": "Device;1",
    "$uri": "/v1/devices/...",
    "$twin_uri": "/v1/devices/..."
  }
}

Reminders:

1. The AuthenticationType could be any values below:

• 0 - Shared Access Key
• 1 - Self-signed certificate
• 2 - Certificate Authority

2. The PrimaryKey and SecondaryKey will only be available if the AuthenticationType is 0
3. The PrimaryThumbprint and SecondaryThumbprint will only be available if the AuthenticationType is 1 or 2

Create device

POST /v1/devices

The body should be in form below:

{
  "Id": <device ID>,
  "Authentication": {
    "AuthenticationType": <authentication type>,
    "PrimaryKey": <primary key>,
    "SecondaryKey": <secondary key>,
    "PrimaryThumbprint": <thumbprint of the primary certificate>,
    "SecondaryThumbprint": <thumbprint of the secondary certificate>
  }
  "Properties": {
    "Desired": { ... }        
  },
  "Tags": { ... }
}

Reminder:

1. The Authentication, Properties or Tags parts are optional
2. The PrimaryKey and SecondaryKey are required only if the AuthenticationType is 0
3. The PrimaryThumbprint and SecondaryThumbprint are required only if the AuthenticationType is 1 or 2
4. Reported properties is not changable from service side

Response

Returns 200 OK and created device, in form same to the get device API

Update device

PUT /v1/devices/{id}

The body should be in form below:

{
  "Id": <device ID>,
  "Etag": <etag>,
  "Properties": {
    "Desired": { ... }
  },
  "Tags": { ... }
}

Reminder:

1. The Properties or Tags parts are optional
2. Reported properties is not changable from service side

Response

Returns 200 OK and updated device, in form same to the get device API

Delete device

DELETE /v1/devices/{id}

Response

Returns 200 OK

Invoke device method

POST /v1/devices/{id}/methods

The body should be in form below:

{
  "name": <method name>,
  "jsonPayload": <parameters in JSON>,
  "responseTimeout": <response timeout>,
  "connectionTimeout": <connection timeout>
}

Reminder: name is the only one mandatory field

Response

Returns 200 OK and the method result object:

{
  "status": <method specified status code>,
  "jsonPayload": <method result in JSON>
}

Get device properties

GET /v1/deviceProperties

Response

Returns 200 OK and the definition object

{
    "Tags": [
        "IsSimulated"
    ],
    "Reported": [
        "Protocol",
        "SupportedMethods",
        "DeviceMethodStatus",
        "FirmwareUpdateStatus",
        "Type",
        "Location",
        "Latitude",
        "Longitude",
        "Firmware",
        "Model"
    ],
    "$metadata": {
        "$type": "DeviceProperties;1",
        "$url": "/v1/deviceProperties"
    }
}```