Tags Endpoints (2020/10)

This endpoint allows you to retrieve data about tags on the network.

Tag names, as well as all other entity properties, are case-insensitive (but values can only differ by case). The server may return entity properties and tag keys with a different case than specified by the client in the request.

Base URL for these endpoints:  https://api.bsn.cloud/2020/10/REST/Tags

_________________________________________________________________________

GET /Keys/ 

Returns all tag names defined on a network that match a specified pattern. 

Required Scope Token

bsn.api.main.tags.retrieve

______________________________________________________________

Query String Parameter

pattern string optional

Enter a value in this format "{DataType}::[[sys].][{ObjectType}].<{TagKey}>". If this value is not entered, this will return all tags for all values.

See the definitions below for further guidance:

  • DataType is one of the supported data types. These supported data types are boolean, numeric, string, DateTime, TimeSpan, numeric array, and string array, as described in PropertyandTagMentionsinExpressions (but object is not supported). This value is optional.

  • sys lets you distinguish system tag (defined by system) or custom tag (defined by customer). This value is optional.

  • ObjectType is either Content or Device

  • TagKey can be skipped, or partially specified with a wildcard character like * or ?, which will give you all of the tag keys matching this expression.

Note that /Tag/Keys/ is unique in the scope of entities in that some of the values can be skipped or partially defined. For example, [Content].<M?dia> is a valid entry.

______________________________________________________________

Response

Success Response with Body

200: Returns all tag names defined on a network that match the pattern

Failure

300: The requested representation could not be returned because it is ambiguous (there are multiple requested representations)

400: The request is malformed and therefore invalid

401: The access token is invalid or not specified

403: The supplied access token, though valid, doesn't provide access to this method 

406: The server cannot return the data representation that you requested (as specified in the "Accept" header)

5XX: Any 500 code is an internal server error

 

GET /Values/ 

Returns all tag values defined on a network that match a specified pattern

Required Scope Token

bsn.api.main.tags.retrieve

______________________________________________________________

Query String Parameter

pattern string optional

Enter a value in this format "{DataType}::[[sys].][{ObjectType}].<{TagValues}>".  If this value is not entered, this will return all tags for all values.

See the definitions below for further guidance:

  • DataType is one of the supported data types. These supported data types are boolean, numeric, string, DateTime, TimeSpan, numeric array, and string array, as described in PropertyandTagMentionsinExpressions (but object is not supported). This value is optional.

  • sys lets you distinguish system tag (defined by system) or custom tag (defined by customer). This value is optional.

  • ObjectType is either Content or Device

  • TagValues can be skipped, or partially specified with a wildcard character like * or ?, which will give you all of the tag values matching this expression.

Note that /Tag/Values/ is unique in the scope of entities in that some of the values can be skipped or partially defined. For example, [Content].<M?dia> is a valid entry.

______________________________________________________________

Response

Success Response with Body

200: Returns all tag values defined on a network that match the pattern

Failure

300: The requested representation could not be returned because it is ambiguous (there are multiple requested representations)

400: The request is malformed and therefore invalid

401: The access token is invalid or not specified

403: The supplied access token, though valid, doesn't provide access to this method 

406: The server cannot return the data representation that you requested (as specified in the "Accept" header)

5XX: Any 500 code is an internal server error