listTags

The "listTags" action lists tags that match specified filter criteria. The results are returned as an array of objects. You can identify a tag by its ID or name. The "returnTagsBy" property controls how the response identifies tags.

The purpose of this action is to return a list of matching tags that you can use with other actions, such as "deleteTags" or "describeTags".

 

Request examples

Minimal

This example returns all tags.

{
  "api": "hub",
  "action": "listTags",
  "params": {
    "returnTagsBy": "id"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession" 
}
 
 

Maximal

This example returns tags that match the optional filter criteria.

{
  "api": "hub",
  "action": "listTags",
  "params": {
    "returnTagsBy": "tagName",

    "tagNameFilter": "My Dev",
    "tagDataTypeFilter": [ "string" ],
    "statusFilter":   [ "active", "inactive" ],
    "purposeFilter":  [ "Stamper temperature" ],
    "labelsFilter":   [ "temperature", "pressure" ],

    "connectorIdFilter": [ 51, 52 ], 
    "thingIdFilter": [ 1 ], 
    "integrationTableIdFilter": [ 1 ], 
    "topicIdFilter": [ 1 ]

  },
  "responseOptions": {
    "numberFormat":   "string"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "requestId": "1",
  "debug": "none"
}
 
 

 

Response examples

Minimal

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

Maximal

{
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "result": {
    "returnTagsBy": "tagName",
    "tagNames": [ "My Device", "Changed Name" ]
  },
  "errorCode": 0,
  "errorMessage": ""
}
 
 

 

Properties

Request properties ("params") 

Property Description Default Type Limits (inclusive)

connectorIdFilter

 The "connectorIdFilter" property filters the response by the specified unique integer ID of a connector. The "listTags" action includes the tag associated with the specified connector. Optional with default of [] array zero or more connector id integers

integrationTableIdFilter

 The "integrationTableIdFilter" property specifies the unique integer ID of an integration table. The "listTags" action includes tags associated with the specified integration table. Optional with default of [] array of integers zero or more integration table id integers

labelsFilter

The "labelsFilter" property finds tags that contain one of the labels included in the property. Each string is a label. A tag may have zero or more labels. Each label is a string from 1 to 64 bytes.

 

The API allows the same label to be assigned to many tags.

 Optional with default of [] array of strings zero or more label 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

returnTagsBy

 The "returnTagsBy" property specifies whether to return tags identified by ID or name. Optional with default of "id" string enum

"id"

"tagName"

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 

tagDataTypeFilter

 The "tagDataTypeFilter" property specifies one or more tag data types. Each item in the array is the exact name of a tag data type. The "listTags" action returns tags that match one of the specified values.  Optional with default of [] array of strings 1 to 64 bytes

tagNameFilter

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

thingIdFilter

 The "thingIdFilter" property specifies zero or more unique integers ID of a thing which will be used to filter the results. The "listTags" action includes tags associated with the specified thing, which is a device or software application. Optional with default of [] array of integers zero or more thing id integers

topicIdFilter

 The "topicIdFilter" property specifies the unique integer ID of an MQTT topic. The "listTags" action includes tags associated with the specified topic. Optional with default of [] array of integers zero or more topic id integers

 

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

returnTagsBy

 The "returnTagsBy" property is an enumerated string with the following values: "tagName" and “id".It is used by the "listTags" action to determine whether tags are returned by ID or by name. string enum

"id"

"tagName"

tagNames

 The "tagNames" property is an array of strings that specifies one or more tag names. You can use it to describe or delete tags. Each item in the array is the exact name of a tag.  string 1 to 256 bytes

 

 

Was this article helpful?

Give feedback about this article

Related Articles