The thing.list command is used to find and return a list of things.
Initial TR50 Request with useSearch and iterator
The following example shows a request using useSearch and iterator parameter:
{
"cmd": {
"command": "thing.list",
"params": {
"useSearch": true,
"iterator": "new",
"limit": "50"
}
}
}TR50 Response gets the iterator value
When the initial request is made, the parameter iterator should be assigned new. The returned result will then include an additional parameter of iterator containing a temporary unique value related to the initial query made. Example response for the above request:
{
"cmd": {
"success": true,
"params": {
"count": 100,
"fields": [
{list of field keys}
],
"iterator": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAADZtEFkFKQmlqRHZWUk5hb1ZHalRua1RKeEEAAAAAABErWxZjR3ZfNzZpbFJPdWZDUVBkdVdVQ0NBAAAAAAANm0MWQUpCaWpEdlZSTmFvVkdqVG5rVEp4QQAAAAAAEStcFmNHdl83NmlsUk91ZkNRUGR1V1VDQ0EAAAAAABErXRZjR3ZfNzZpbFJPdWZDUVBkdVdVQ0NB",
"result": [
{list of result objects}
]
}
}
} TR50 Request with iterator value
This value should be passed on to the iterator parameter for the subsequent requests to iterate through the result set until the entire result set has been returned. A subsequent request after the initial response is shown below:
{
"cmd": {
"command": "thing.list",
"params": {
"useSearch": true,
"iterator": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAADZtEFkFKQmlqRHZWUk5hb1ZHalRua1RKeEEAAAAAABErWxZjR3ZfNzZpbFJPdWZDUVBkdVdVQ0NBAAAAAAANm0MWQUpCaWpEdlZSTmFvVkdqVG5rVEp4QQAAAAAAEStcFmNHdl83NmlsUk91ZkNRUGR1V1VDQ0EAAAAAABErXRZjR3ZfNzZpbFJPdWZDUVBkdVdVQ0NB",
"limit": "50"
}
}
}When there is no more data to iterate through you will get the following response:
{
"cmd": {
"success": false,
"errorMessages": [
"Search has reached end of results."
],
"errorCodes": [
-90058
]
}
} TR50 Request without iterator
{
"cmd": {
"command": "thing.list",
"params": {
"show": [
"key",
"name"
],
"offset": 0,
"limit": 10,
"sort": "+name",
"tags": ["tag1", "tag2"],
"keys": ["thingkey1", "thingkey2"],
"hasLoc": true
}
}
}Request Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| show | Array | An array of field names of the data columns to return. | |
| useSearch | Boolean | When useSearch is set to true, it will improve the performance of the operation. In some cases there is a delay between making changes and when they will be visible to the search database, this delay is typically less than 5 seconds. As such, if you perform an update call, and subsequently call a list, you may not see the results of your operation. |
|
| iterator | String | iterator is used in conjunction with the useSearch to iterate through the returned results. Initial request should be given the value new. Further requests should be given the value got in from the response. For more information, see the example below at the end of this section with the iterator and useSearch. | |
| offset | Integer | The starting list offset, used for pagination. Defaults to 0, if not specified. | |
| limit | Integer | Limits the number of results returned. The maximum limit you can set is 2000. Defaults to 2000. | |
| showCount | Boolean | By default, it is set to true. If set to false, the response will not include the count. Setting it to false will improve the response time but you will not know the total size of the result set. | |
| sort | String | sort is an optional parameter that defines the sort order of the result set. It allows to arrange the list in either ascending(+) or descending(-) order. It is possible to sort thing.list in the following categories:id, name, key, defId, iccid, esn, meid, imei, imsi, msisdn, defName, defKey, lastSeen, loc.updated, loc.lat, loc.lng, createdOn, updatedOn, apiCounts.daily, apiCounts.monthToDate, apiCounts.total, firmware.currentVersion, firmware.targetVersion, firmware.state, varBillingPlanCode, and varVasPackageCode | |
| tags | Array | If specified, the command will only return things that have all tags in this parameter. | |
| keys | Array | If specified, the command will only return things that have the keys specified in this parameter. | |
| hasLoc | Boolean | Only return things that have a location. Defaults to false. | |
| hideFields | Boolean | If set to true, the response will not include the fields in the response parameters. | |
| boundTo | String | The ID of a thing. When this is specified, the command will only return things that are bound to the thing identified by the boundTo parameter. | |
| showLwm2m | Boolean | If set to true, things that are LwM2M devices will include LwM2M details in the results. |
TR50 Response
If the command is sent successfully a success message and the thing is returned. Otherwise, an error and error message will be returned.
{
"cmd": {
"success": true,
"params": {
"count": 42,
"fields": [
"id",
"key",
"name",
"ownerOrgId",
"permission",
"defKey",
"defName",
"gateway",
"iccid",
"esn",
"meid",
"imei",
"imsi",
"msisdn",
"smsc",
"connected",
"lastSeen",
"lastCommunication",
"loc",
"proto",
"remoteAddr",
"data",
"properties",
"alarms",
"attrs",
"createdOn",
"updatedOn",
"firmware.id",
"firmware.currentVersion",
"firmware.targetVersion",
"firmware.state",
"apiCounts.daily",
"apiCounts.monthToDate",
"apiCounts.total",
"sharedWith",
"varBillingPlanCode",
"varVasPackageCode"
],
"result": [
{
"alarms": {
"connected": {
"ts": "2019-04-05T13:46:58.678Z",
"since": "2019-04-05T13:46:58.678Z",
"state": 0
}
},
"apiCounts": {
"daily": 2,
"monthToDate": 183,
"total": 16705
},
"attrs": {
"firmware_version": {
"ts": "2019-04-16T02:45:48.084Z",
"since": "2019-03-13T17:08:27.491Z",
"value": "XDK-2.0.1"
},
"serial_number": {
"ts": "2017-08-02T20:48:20.735Z",
"since": "2017-08-02T20:48:20.735Z",
"value": "248CE70556961211"
}
},
"id": "531c907b5d80f1330c238757",
"key": "mything",
"name": "My Thing",
"defName": "A Thing",
"connected": true,
"connectedId": "53404db65d80f12689016ed3",
"connectedKey": "myconnectedthing",
"lastCommunication": "2018-12-05T15:34:43.937Z",
"lastSeen": "2018-12-05T13:46:58.736Z",
"gateway": {
"make": "unknown",
"model": "unknown",
"dwProduct": "DW-Gateway.Linux",
"dwPlatform": "Linux-X86-Generic",
"dwVersion": "14.1.0-014",
"appVersion": "2.0",
"remShell": true
},
"proto": "mqtt",
"remoteAddr": "127.0.0.1:60709",
"locWithin": {
"": ""
},
"locUpdated": "2019-04-10T20:37:53.887Z",
"ownerOrgId": "534c36e5310f460721120051",
"permission": "rw",
"loc": {
"lat": 30.455,
"lng": -84.253333,
"since": "2019-04-10T20:36:59.839Z",
"acc": 0,
"fixType": "unknown",
"addr": {
"streetNumber": "",
"street": "1113 Buckingham Dr",
"city": "Tallahassee",
"state": "FL",
"zipCode": "32308-5212",
"country": "US"
}
}
},
...
]
}
}
}Response Parameters
| Name | Type | Description |
|---|---|---|
| count | Integer | The total number of matching things. |
| fields | Array | An array of field names of data columns capable of being returned. |
| result | Array | The array of thing objects. |
Result Array Object
| Name | Type | Description |
|---|---|---|
| alarms | Object | Current alarm values. Since indicates the date/time this alarm had the current state |
| apiCounts.daily | Integer | The number of API calls for the current day, since the beginning of the month, and total |
| apiCounts.monthToDate | Integer | The number of API calls for since the beginning of the month. |
| apiCounts.total | Integer | The total number of API calls. |
| attrs | Object | Lists the attribute key-value pairs with the timestamps. Since indicates the date/time this alarm had the current state. For more information on attributes, see Defining Attributes. |
| id | String | The id of the thing. |
| key | String | The key of the thing. |
| name | String | The name of the thing. |
| ownerOrgid | String | If the thing is shared, then the ownerOrgid displays the id of the organization to which it belongs to. If a thing is not shared then the orgid and the ownerOrgid are the same. For more information on sharing a thing, see Sharing Things and Connections. |
| permission | String | The permissions for the thing in the current organization. |
| defName | String | The thing definition name. |
| defId | String | The thing definition Id of the thing. |
| connected | Bool | Connection state of the thing |
| connectedId | String | If connected through a proxy, this field will contain the thing ID of the proxy. |
| connectedKey | String | If connected through a proxy, this field will contain the thing key of the proxy. |
| lastSeen | String | The last time the thing got connected. |
| lastCommunication | String | The last time the thing indicated that it is connected (the keep-alive heartbeat). |
| defKey | String | The key of the thing's definition. |
| gateway | Object | The details of the gateway |
| gateway.make | String | Brand of the gateway. |
| gateway.model | String | Model of the gateway. |
| gateway.dwProduct | String | deviceWISE product. |
| gateway.dwPlatform | String | deviceWISE platform. |
| gateway.dwVersion | String | deviceWISE version. |
| gateway.appVersion | String | deviceWISE application version. |
| gateway.remShell | Boolean | If the gateway supports remote shell. |
| proto | String | Connection protocol. |
| remoteAddr | String | The remote address of the thing. |
| locWithin | Array | The locations within the current location. |
| locUpdated | String | The date and time the Thing location is updated. |
| loc | Object | The array containing the location information. |
| loc.lat | Float | The latitude of the thing. |
| loc.lng | Float | The longitude of the thing. |
| loc.since | String | The date and time of the first publish from a location. |
| loc.acc | Integer | The accuracy of the location. |
| loc.fixType | String | The method used to determine the location of the thing. |
| loc.addr | Object | The array containing the address information. |
| loc.addr.streetNumber | String | The street number. |
| loc.addr.street | String | The street. |
| loc.addr.city | String | The city. |
| loc.addr.state | String | The state. |
| loc.addr.zipCode | String | The zip code. |
| loc.addr.country | String | The country. |
| messageCounts.daily | Integer | The number of LwM2M message for the current day. |
| messageCounts.monthToDate | Integer | The number of LwM2M message since the beginning of the month. |
| messageCounts.total | Integer | The total number of LwM2M message. |
| smsc | String | The SMSC to use when sending SMS messages to the thing. |
| supportUntil | String | If the thing is a Gateway, this field will contain the date and time when support for the gateway expires. |
PHP API
mixed TR50httpWorker::thingList([$offset[, $limit[, $show[, $sort[, $tags[, $keys]]]]]]);