listThings

The "listThings" action lists things that match specified filter criteria. The results are returned as an array of objects. You can identify a thing by its ID or "thingName". The "returnThingsBy" property controls how the response identifies things.

 

Request examples

Minimal

{
 "action": "listThings",
 "params": {
   "returnThingsBy": "id"
 },
 "authToken": "replaceWithAuthTokenFromCreateSession" 
}
 
 

Maximal

{
 "api": "hub",
 "action": "listThings",
 "params": {
   "returnThingsBy": "name",
   "thingNameFilter": "My Dev",
   "manufacturerFilter": [ "Siemens", "Rockwell" ],
   "modelFilter": [ "ACME-123", "model2" ],
   "serialNumberFilter": "AB678",
   "thingTypeFilter": [ "ACME Temperature Sensor" ],
   "purposeFilter": [ "Stamper temperature" ],
   "locationFilter": [ "factory1/line1/station1" ],
   "lifecycleLabelsFilter": ["out-of-warranty", "deprecated"],
   "hostnamesFilter": [ "127.0.0.1" ],
   "statusFilter": ["active", "inactive"],
   "connectionStatusFilter": ["connected", "disconnected"]
 },
 "responseOptions": {
   "binaryFormat":   "hex",
   "numberFormat":   "string",
   "variantFormat":  "variantObject"
 },
 "authToken": "replaceWithAuthTokenFromCreateSession",
 "requestId": "1",
 "debug": "none"
}
 
 

 

Response examples

Minimal

{
 "authToken": "replaceWithAuthTokenFromCreateSession",
 "result": {
   "returnThingsBy": "id",
   "ids": [ 1, 2 ]
 },
 "errorCode": 0,
 "errorMessage": ""
}
 
 

Maximal

{
 "authToken": "replaceWithAuthTokenFromCreateSession",
 "result": {
   "returnThingsBy": "name",
   "thingNames": [ "My Device", "Changed Name" ]
 },
 "errorCode": 0,
 "errorMessage": ""
}
 
 

 

Properties 

Request properties ("params")

Property Description Default Type Limits (inclusive)

connectionStatusFilter

The "connectionStatusFilter" property filters the returned sessions by the selected connection statuses. The "listThings" action uses it to return things that match the specified connection states. Omitting the property or setting it to null matches all things.
 

 Optional with default of [] array

"disconnected"

"connected"

"connectedTemporarily"

"unknown"

hostnamesFilter

The "hostnamesFilter" property finds things that contain one of the hostnames included in the property. Each string specifies a partial or complete hostname or IP Address that a thing uses. A thing may have zero or more hostnames. 

 

Because the API does not prevent the same hostname from being assigned to many things, it may return multiple things assigned to the same hostname.

 Optional with default of [] array of strings Array containing zero or more hostnames.

lifecycleLabelsFilter

 The "lifecycleLabelsFilter" property filters the results by the specified lifecycleLabels. An empty array matches all things. Optional with default of [] array of strings

Array containing zero or more lifecycleLabel strings.

 

locationFilter

 The "locationFilter" property filters results by the value of the "location" property. Each string is a partial or complete location name, such as, "locationFilter": [ "myLoca", "factory2-line6-station1" ]. The action returns things that match at least one item in the array, provided it also satisfies all other specified filter properties. Optional with default of [] array zero or more location strings.

manufacturerFilter

 The "manufacturerFilter" property filters results by the value of the "manufacturer" property. Each string is a partial or complete manufacturer name, such as, "manufacturerFilter": [ "Siem", "Rockwell" ]. The action returns things that match at least one item in the array, provided it also satisfies all other specified filter properties.
 		 Optional with default of [] array zero or more manufacturer strings

modelFilter

 The "modelFilter" property filters results by the value of the "model" property. Each string is a partial or complete model name, such as "modelFilter": [ "ACME-123", "mod_" ]. The action returns things that match at least one item in the array, provided it also satisfies all other specified filter properties. Optional with default of [] array zero or more model strings

purposeFilter

 The "purposeFilter" property returns things that match at least one item in the array, provided it also satisfies all other specified filter properties. Each string is a partial or complete purpose, such as, "purposeFilter": [ "myPur", "Manage an Acid Bath" ]. Optional with default of [] array of strings zero or more purpose strings

returnThingsBy

 The "returnThingsBy" property specifies whether to returns things identified by ID or "name". Optional with default of null string enum

"id"

"name"

serialNumberFilter

 The "serialNumberFilter" property specifies a complete or partial serial number, such as, "serialNumberFilter": "AB678". The action returns things that match the serial number, provided it also satisfies all other specified filter properties. Optional with default of "" string 1 to 64 bytes

statusFilter

The "statusFilter" property filters results based on the value of the "status" property. If the array is empty, null, or omitted, it matches all status values; otherwise, it returns code packages only when their status matches one of the values in the array. If "includeDeactivatedCode" is set to true or false, it overrides conflicting status codes.

 

When using the tag actions, this property finds tags based on their status. You can include zero or more status values. The "listTags" action returns tags that match at least one of the specified status values. An empty array or null value matches all status values.

  • Use "statusFilter": "active" to return active tags.
  • Use "statusFilter": "inactive" to return inactive tags.
  • The "listTags" action returns tags that match at least one of the specified status values.
  • Omitting the property or setting it to null matches all tags.
 Optional with default of [] array

"developing"

"deleted"

"inactive"

"deprecated"

"testing"

"active"

 

When using tag actions, "inactive" and "active" are the only valid statuses 

thingNameFilter

 The "thingNameFilter" property specifies a partial or full name of a thing to describe. The action returns things that match the specified partial or full name of the thing, provided it satisfies all other specified filter properties. Optional with default of "" string 1 to 64 bytes

thingTypeFilter

 The "thingTypeFilter" property filters the results by the value of the "thingType" property. Each string is a partial or complete type, such as, "thingTypeFilter": [ "myTy", "PLC" ]. The action returns things that match at least one item in the array, provided it also satisfies all other specified filter properties. Optional with default of [] array of strings zero or more type strings

 

Response properties ("result")

Property Description Type Limits (inclusive)

ids

The "ids" property is an array. Each identifier in the array uniquely specifies a table row, indicating which records the action affects. 

  • The "ids" property is mutually exclusive with the "primaryKeys" property meaning it is required when "primaryKeys" is omitted or an error is returned if both have values.
  • It is typically an array of integers ("ids": [1,3,5]).
  • It can be an array of an array of strings ("ids": ["9555444333222111","9555444333222112", "9555444333222113"]).
    • A string "id" supports numbers larger than 9,007,199,254,740,991.
    • This is the largest number supported by many programming languages and JSON parser implementations that use IEEE double-precision floats to hold numbers.
  • It can be the primary key value of another field in the table, making it useful when your table is created by another API, such as SQL, that allows any field in the table to be the primary key.
    • If your table does not have an "id" field but uses a "vin" field as the primary key, you can use vin values to look up records ("ids": [ "4Y1SL65848Z411439", "1HGBH41JXMN109186" ]).
  • If your table uses more than one field as the primary key, you must use the "primaryKeys" property to look up records.

Tip: The "getRecordsByIds" action uses a primary key index to look up records. A primary key index must be a unique, non-null index without conditional filtering. For best performance and maximum simplicity, create tables using the JSON DB API because it automatically creates an auto increment "id" field that is indexed as a primary key.

 array 0 or more ids

returnThingsBy

 The "returnThingsBy" property is an enumerated string with the following values: "name" and "id". It is used by the "listThings" action to specify whether it returns things identified by ID or "name". string enum

"name"

"id"

thingNames

 The "thingNames" property is an array of strings that specifies one or more thing names. Each item in the array is the exact name of a thing. You can use it to describe or delete things. array of strings 1 or more thingName strings

 

Was this article helpful?

Give feedback about this article

Related Articles