Managing Tags
- The Tags API
-
The Tags API retrieves the qualified tag name list by a given
nameMask
.Note: URI format supports asterisks (*) and question marks (?).METHOD GET URI https://<NLB DNS>:9090/historian-rest-api/v1/tags/{nameMask}/{maxNumber}
SAMPLE URI https://<NLB DNS>:9090/historian-rest-api/v1/tags?nameMask=*&maxNumber=100
SAMPLE cURL COMMAND curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” https://<nodename>:443/ historian-rest-api/v1/tags?nameMask=*&maxNumber=<Number_Of_Tags>
Table 1. Query Parameters Parameter Description Required? Values nameMask
Tagmask that searches for all tags that match the mask and applies the remaining criteria to retrieve data. The mask can include wildcards, such as asterisks (*). Optional String maxNumber
Maximum tag number provides the limit while returning the results (0 by default). This means that for a query, if using 0, all tags are returned. If a negative number is used, then 0 is used for the maxNumber.
If a positive number is used, then that number of tags is returned. In addition, an error number of +14 notifies the user that there are more than the requested number of tags in the system.
Optional Integer 0 by default
Table 2. Response Parameters Parameter Data Type Required? Description ErrorCode Number Yes For example, ErrorCode = 0, which means the operation was successful. ErrorMessage String Yes For example, NULL. tags String Yes Includes the following: - ALT_SENSOR
- tagName1
- tagName2
- The Tagslist API
The Tags List API
When retrieving large tag lists from Historian, you can paginate the response, allowing you to get the next page, go the end, go back one page, and go to the beginning.GET
method retrieves the list of tags.Request Parameters
You can use wildcards (*, &,?) with string parameters for pattern matching. Results are sorted in ascending tag names. All parameters use the
AND
operator. TheOR
operator is not supported.All request parameters are optional.
When there are NO wildcard characters (*, &,?) with string parameters for pattern matching, then search would be a
contains
searchExample: “dog” pattern will match “dog1”, “dog2”,”dogs”, “dogx”, “dog12”, “dogs are faithful”, “1dog1” and so on. When wildcards (*,&, ?) are used in the search string parameters for pattern matching, then they work as per the wildcard character definition.
? - Single character matching
* - Multi character matching
Eg1: “dog?” pattern will match: “dog1”, “dog2”,”dogs”, “dogx” and so on but not “dog12” or “dogs are faithful”
Eg2: “dog*” pattern will match “dog1”, “dog2”,”dogs”, “dogx”, “dog12”, “dogs are faithful” and so on but not “1dog1”
Parameter Name Data Type Default Description calctype
Integer -1
Returns exact match of calc type (0,1,2). collectiondisabled
Boolean If ignored, all types considered. Must be only true / false, else error out. collectioninterval
Integer 0 – means all intervals If collectorinterval
= 0 consider all intervals, else exact match.collectorcompression
Boolean *
Returns exact match of collector compression (true/false). collectorname
String *
Default *
means consider all.collectortype
Integer 0 – means consider all collector types Returns exact match of collector type. comment
String *
Default *
means consider all.data storename
String *
Default *
means consider all.datatype
Integer 0
– means consider all data typesReturns exact match of data type. description
String *
Default *
means consider all.egudescription
String *
Default *
means consider all.enumeratedset
String *
Default *
means consider all.hasalias
Boolean If ignored, all types considered. Must be only true / false, else error out. isstale
Boolean If ignored, all types considered. Must be only true / false, else error out. lastmodified
String 1970-01-01T00:00:00.000Z
>=
is applied so that last modified tag is returned in the result set.lastmodifieduser
String *
Default *
means consider all.numberofelements
Integer 0 If 0, ignore this parameter else returns exact match of number of elements. pageno
Integer 1
Must be >
1
If invalid, no data is returned. pagesize
Integer 128
Max
512
Min
2
If out of range, returns error. Provide 0 to return all tags at once without any pagination. sourceaddress
String *
Default *
means consider all.tagname
String *
Default *
means consider all.userdefinedtypename
String *
Default *
means consider all.The Tags List Pagination Parameters
When retrieving large tag lists from Historian, you can paginate the response, allowing you to get the next page, go the end, and go back on page and to the beginning. Results with no errors return these pagination parameters:Parameter Value pagesize
Current page size. pageno
Current page number totalcount
Total result other than current page. Links to URLs All URLs are part of the HTTP response headers. first
– First pagetags list
URL (can be null if count is 0).last
- Last pagetags list
URL (can be null if count is 0).prev
– Previous pagetags list
URL (can be null if current page is 1).- Next - Next page
tags list
URL (can be null if current page is last page).
Table 3. Sample cURL commands METHOD GET SAMPLE cURL COMMAND: [lastmodified]
curl -i -H "Accept: application/json" -H "Authorization:Bearer <TOKEN>” http://<nodename>:443/historian-rest-api/v1/tagslist?lastmodified=2017-05-01T00:00:00.00Z SAMPLE cURL COMMAND: [pageno=0]
curl -i -H "Accept: application/json" -H "Authorization:Bearer <TOKEN>” http://<nodename>:443/historian-rest-api/v1/tagslist?pageno=0 SAMPLE cURL COMMAND: [pageno=1]
curl -i -H "Accept: application/json" -H "Authorization:Bearer <TOKEN>” http://<nodename>:443/historian-rest-api/v1/tagslist?pageno=1 SAMPLE cURL COMMAND: [complete tagslist]
curl -i -H "Accept: application/json" -H "Authorization:Bearer <TOKEN>” http://<nodename>:443/historian-rest-api/v1/tagslist Example Queries
The following request returns first page aspageno
is ignored andpagesize
is defaulted to 128, all tags are considered:<baseurl>/v1/tagslist
The following request returns first page aspageno
is ignored andpagesize
is defaulted to 128, all tags are considered that are modified after2017-05-01T00:00:00.00Z
.<baseurl>/v1/tagslist?lastmodified=2017-05-01T00:00:00.00Z
Example Results
The following info is returned for each tag from the criteria provided in the request as an array of tag info.tagid
- Stringtagname
- Stringdescription
- Stringdatatype
- Integercollectorname
- Stringcollectortype
- Integerdata storename
- Stringegudescription
- Stringcomment
- Stringsourceaddress
- Stringsourceaddress
- Stringcollectioninterval
- Integercollectorcompression
- Booleanlastmodifieduser
- Stringenumeratedset
- Stringuserdefinedtypename
- Stringcalctype
- Integerisstale
- Booleanlastmodified
- Longlastmodified
- LonglastmodifiedString
– String – In readable formathas alias
- Booleannumberofelements
- Integercollectiondisabled
- Boolean
Example:{ "TotalCount": 1031, "Page": 1, "PageSize": 4, "Tags": [ { "Tagid": "adb70ebf-978f-46dd-ac6f-5e863cdb0739", "Tagname": "-anilgwxb.Constant", "Description": "anilgwxb.Constant", "DataType": 3, "CollectorName": "ANILGWXB_Simulation", "CollectorType": 2, "DataStoreName": "User", "EngineeringUnits": "", "Comment": "", "SourceAddress": "$Constant", "CollectionInterval": 1000, "CollectorCompression": false, "LastModifiedUser": null, "EnumeratedSetName": "", "UserDefinedTypeName": "", "CalcType": 0, "IsStale": false, "HasAlias": false, "NumberOfElements": 0, "CollectionDisabled": false, "LastModified": 1496992712, "LastModifiedString": "2017-06-09T07:18:32Z" }, { "Tagid": "88e1f448-643f-465a-95c2-d2bd08870547", "Tagname": "anilgwxb.Constant_1%Noise", "Description": "anilgwxb.Constant_1%Noise", "DataType": 3, "CollectorName": "ANILGWXB_Simulation", "CollectorType": 2, "DataStoreName": "User", "EngineeringUnits": "", "Comment": "", "SourceAddress": "$Constant_1%Noise", "CollectionInterval": 1000, "CollectorCompression": false, "LastModifiedUser": null, "EnumeratedSetName": "", "UserDefinedTypeName": "", "CalcType": 0, "IsStale": false, "HasAlias": false, "NumberOfElements": 0, "CollectionDisabled": false, "LastModified": 1496992712, "LastModifiedString": "2017-06-09T07:18:32Z" }, <SNIP> ], "Links": { "first": "https://anilgwxb:443/historian-rest-api/v1/tagslist?pageno=1&pagesize=4", "last": "https://anilgwxb:443/historian-rest-api/v1/tagslist?pageno=258&pagesize=4", "prev": null, "next": "https://anilgwxb:443/historian-rest-api/v1/tagslist?pageno=2&pagesize=4" } }
- The Raw Data API
-
The Raw Data API queries raw data, such as a number of samples or the time range for a list of tags. If the count is not zero, then the API service returns the number of raw samples taken beginning from the start time. If the count is zero, then the service returns the raw samples taken between the start time and the end time.
METHOD: GET, POST URI: - GET
https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/raw/{tagNames}/{start}/{end}/{direction}/{count}
- POST
https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/raw/{start}/{end}/{direction}/{count}
SAMPLE GET URI: Raw By Number
Count value is a non-zero positive number, and end time is greater than start time.
https://<NLB DNS>:9090/historian-rest-api/datapoints/raw/tagName1/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/0/100
https://<NLB DNS>:9090/historian-rest-api/datapoints/raw/tagNames=tagName1&start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&count=100&direction=0
Raw By Time
The count value equals 0.
https://<NLB DNS>:9090/historian-rest-api/datapoints/raw/tagName1/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/0/0
https://<NLB DNS>:9090/historian-rest-api/datapoints/raw/tagNames=tagName1&start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&count=0&direction=0
SAMPLE POST URI: Raw By Number
Count value is a non-zero positive number, and end time is greater than start time.
https://<NLB DNS>:9090/historian-rest-api/datapoints/raw/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/0/100
https://<NLB DNS>:9090/historian-rest-api/datapoints/raw/start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&count=100&direction=0
Raw By Time
The count value equals 0.
https://<NLB DNS>:9090/historian-rest-api/datapoints/raw/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/0/0
https://<NLB DNS>:9090/historian-rest-api/datapoints/raw/start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&count=0&direction=0
SAMPLE cURL COMMAND (GET): [Raw By Number] curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” http://<nodename>:443/historian-rest-api/v1/ datapoints/raw/<tagName>/<start time>/<end time>/<direction>/<count>
SAMPLE cURL COMMAND (GET): [Raw By Time] curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” http://<nodename>:443/historian-rest-api/v1/ datapoints/raw/<tagName>/<start time>/<end time>/<direction>/0
SAMPLE cURL COMMAND (POST): [Raw By Number] curl –X POST -i -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” -d “{\”tagNames\”:\”<tagName>;<tagName>\”}” http:// <nodename>/ historian-rest-api/v1/ datapoints/raw/ <start time>/<end time>/<direction>/<count>
SAMPLE cURL COMMAND (POST): [Raw By Time] curl –X POST -i -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” -d “{\”tagNames\”:\”<tagName>;<tagName>\”}” http:// <nodename>/ historian-rest-api/v1/ datapoints/raw/ start=<start time>&end=<end time>&direction=<direction>&count=<count>
Table 4. Query Parameters Parameter Description Required? Values TagNames Queries the specified tag names. Yes String Start Start time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime End End time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime Direction Specifies the direction (Forward or Backward from the starting time) of data sampling from the archive. The default value is Forward (1). Yes Integer, with a value such as 1. Count Count of archive values within each calculation interval. Yes Integer, with a value such as 100. Table 5. Response Parameters Parameter Data Type Required? Description ErrorCode Integer Yes For example, 0. ErrorMessage String Yes For example, NULL. Data String Yes The object container for the following parameters: - DataType
- DoubleFloat, which stores decimal values up to 15 places.
- ErrorCode
- Value is 0, which means the operation was successful.
- TagName
- Example: TagName1.
- Samples
- Provides TimeStamp, Value, Quality, and
DtatAttributes for each sample. Where,
DataAttributes is the detailed information
regarding the Quality.
For example,
"TimeStamp": "2013-10-02T11:30:00.111Z", "Value": 34.26155", "Quality": 3, "DataAttributes": []
- The Interpolated Data API
-
The Interpolated Data API queries interpolated values for a list of tags. If the start time equals the end time, the request returns one sample.
METHOD: GET, POST URI: - GET
https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/interpolated/{tagNames}/{start}/{end}/{count}/{intervalMs}
- POST
https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/interpolated/{start}/{end}/{count}/{intervalMs}
SAMPLE GET URI: https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/interpolated/tagName1/2013-10-02T11:30:00.111111Z/2013-10-02T11:31:11.111Z/100/10000
SAMPLE POST URI: https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/interpolated/2013-10-02T11:30:00.111111Z/2013-10-02T11:31:11.111Z/100/10000
SAMPLE cURL COMMAND (GET): curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” http://<nodename>:443/ historian-rest-api/v1/ datapoints/interpolated/<tagName>/<start time>/<end time>/<count>/<intervalMS>
SAMPLE cURL COMMAND (POST): curl -i –X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” -d “{\”tagNames\”:\”<tagName>\”}” http://<nodename>:443/historian-rest-api/v1/ datapoints/interpolated/<start time>/<end time>/<count>/<intervalMS>
Table 6. Query Parameters Parameter Description Required? Values TagName Queries the tag names specified. Yes String Start Start time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime End End time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime Count Count of archive values within each calculation interval. Yes Integer, with a value such as 100. intervalMS Interval in milliseconds. Yes 64-bit signed integer, with a value such as 10000. Table 7. Response Parameters Parameter Data Type Required? Description ErrorCode Integer Yes For example, 0. ErrorMessage String Yes For example, NULL. Data String Yes The object container for the following parameters: - DataType
- DoubleFloat, which stores decimal values up to 15 places.
- ErrorCode
- Value is 0, which means the operation was successful.
- TagName
- Example is TagName1.
- Samples
- Provides TimeStamp, Value and Quality for each sample. For example, TimeStamp = 2013-10-02T11:30:00.111Z, Value = 34.26155, and Quality = 3.
- The Current Value API
-
The Current Value API queries the current value data and reads the current values for a list of tags. If the start time is equal to end time, the request returns one sample.
METHOD: GET, POST URI: - GET
https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/raw/{tagNames}/{start}/{end}/{direction}/{count}
- POST
https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/currentvalue
SAMPLE GET URI: https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/currentvalue?tagNames=tagName1
SAMPLE POST URI: https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/currentvalue
SAMPLE cURL COMMAND (GET): curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” http://<nodename>:443/historian-rest-api/v1/ datapoints/currentvalue/<tagName>
SAMPLE cURL COMMAND (POST): curl -i –X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” -d “{\”tagNames\”:\”<tagName>\”}” http://<nodename>:443/historian-rest-api/v1/ datapoints/currentvalue
Table 8. Query Parameters Parameter Description Required? Values TagNames Queries the specified tag names. Yes String Table 9. Response Parameters Parameter Data Type Required? Description ErrorCode Integer Yes For example, 0. ErrorMessage String Yes For example, NULL. Data String Yes The object container for the following parameters: - DataType
- DoubleFloat, which stores decimal values up to 15 places.
- ErrorCode
- Value is 0, which means the operation was successful.
- TagName
- Example is TagName1.
- Samples
- Provides TimeStamp, Value and Quality for each sample. For example, TimeStamp = 2014-01-01T12:00:00Z, Value = 34.26155, and Quality = 3.
- The Calculated Data API
-
The Calculated Data API queries the calculated data for a list of tags. Data can be requested using a number of samples or a time range for a list of tags. If the count is not zero, the service returns the number of raw samples beginning from the start time. If the count is zero, the services uses the interval, start time, and end time to calculate the required sample number.
METHOD: GET, POST URI: - GET
https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/calculated/{tagNames}/{start}/{end}/{calculationMode}/{count}/{intervalMs}
- POST
https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/calculated/{start}/{end}/{calculationMode}/{count}/{intervalMs}
SAMPLE GET URI: - Number of Samples
https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/calculated/tagName1/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/1/100/1000
- Time Range for List of Tags
https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/calculated?tagNames=tagName1&start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&count=100&calculationMode=1&intervalMs=1000
SAMPLE POST URI: - Number of Samples
https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/calculated/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/1/100/1000
- Time Range for List of Tags
https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/calculated?start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&count=100&calculationMode=1&intervalMs=1000
SAMPLE cURL COMMAND (GET): curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” http://<nodename>:8843/ historian-rest-api/v1/ datapoints/calculated/<tagName>/<start time>/<end time>/<count>/<calculation mode>/<intervalMS>
SAMPLE cURL COMMAND (POST): curl -i –X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” -d “{\”tagNames\”:\”<tagName>\”}” http://<nodename>:8843/ historian-rest-api/v1/ datapoints/calculated/<start time>/<end time>/<count>/<calculationmode>/<intervalMS>
Table 10. Query Parameters Parameter Description Required? Values TagNames GE identifier for a location. Yes 1000000106 Start Start time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime End End time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime Count Count of archive values within each calculation interval. Yes Integer, with a value such as 100. Calculation Mode Yes Integer, with a value such as 1. IntervalMS Interval in milliseconds. 64-bit signed integer, with a value such as 1000. Table 11. Response Parameters Parameter Data Type Required? Description ErrorCode Integer Yes For example, 0. ErrorCode String Yes For example, NULL. Data String Yes The object container for the following parameters: - DataType
- DoubleFloat, which stores decimal values up to 15 places.
- ErrorCode
- Value is 0, which means the operation was successful.
- TagName
- Example is TagName1.
- Samples
- Provides TimeStamp, Value and Quality for each sample. For example, TimeStamp = 2013-10-02T11:30:00.111Z, Value = 34.26155, and Quality = 3.
- The Sampled Data API
-
The Sampled Data API queries the sampled data for a list of tags. Data can be requested using a number of samples or a time range for a list of tags. If the count is not zero, the service returns the number of raw samples beginning from the start time. If the count is zero, the services uses the interval, start time, and end time to calculate the required sample number.Note: For the query, you can also use optional parameters such as FilterMode and ReturnDataFields. Unused parameters can be omitted.
METHOD: GET, POST URI: - GET
https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/sampled
- POST
https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/sampled
SAMPLE GET URI: https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/sampled?tagNames=tagName1&start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&samplingMode=1&calculationMode=1&direction=0&count=0&intervalMs=1000
SAMPLE POST URI: https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/sampled
SAMPLE cURL COMMAND (GET): curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” http://<nodename>:443/ historian-rest-api/v1/ datapoints/sampled/<tagName>/<start time>/<end time>/<direction>/<count>/<intervalMS>
SAMPLE cURL COMMAND (POST): curl -i –X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” -d “{ \”tagNames\”:\”<tagName>\”, \”start\”: \”<start>\”, \”end\”: \”<end>\”, \”samplingMode\”: <samplingMode>, \”calculationMode\”: <calculationMode>, \”direction\”: <direction>, \”count\”: <count>, \”returnDataFields\”: <returnDataFields>, \”intervalMs\”: <intervalMs>, \”queryModifier\”: <queryModifier>, \”filterMode\”: <filterMode>, \”filterExpression\”: \”<filterExpression>\”}” http://<nodename>:443/historian-rest-api/v1/datapoints/sampled
Table 12. Query Parameters Parameter Description Required? Values TagNames Queries the tag names specified. Yes String Start Start time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime End End time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime SamplingMode Also known as SamplingModeType. Optional Integer, with a value such as 1. CalculationMode Also known as CalculationModeType. Optional Integer, with a value such as 1. Direction Specifies the direction (Forward or Backward from the starting time) of data sampling from the archive. The default value is Forward (1). Optional Integer, with a value such as 1. Count The count of archive values within each calculation interval. Optional Integer, with a value such as 0. IntervalMS Interval in milliseconds. Optional 64-bit signed integer, with a value such as 1000. Table 13. Response Parameters Parameter Data Type Required? Description ErrorCode Integer Yes For example, 0. ErrorCode String Yes For example, NULL. Data String Yes The object container for the following parameters: - DataType
- DoubleFloat, which stores decimal values up to 15 places.
- ErrorCode
- Value is 0, which means the operation was successful.
- TagName
- Example is TagName1.
- Samples
- Provides TimeStamp, Value and Quality for each sample. For example, TimeStamp = 2013-10-02T11:30:00.111Z, Value = 34.26155, and Quality = 3.
- The Trend Data API
-
The Trend Data API queries the trend data for a list of tags.Note: For the query, you can also use optional parameters such as FilterMode and StatisticsItemFilter. Unused parameters can be omitted.
METHOD: GET, POST URI: - GET
https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/trend
- POST
https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/trend
SAMPLE GET URI: https://<NLB DNS>:9090/historian-rest-api /v1/datapoints/trend?tagNames=tagName1&start=2013-10-02T11: 30:00.111Z&end=2013-10-02T11:31:11.111Z&samplingMode=1&calculationMode=1 &direction=0&count=0&intervalMs=1000
SAMPLE POST URI: https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/trend
SAMPLE cURL COMMAND (GET): curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” http://<nodename>:443/ historian-rest-api/v1/ datapoints/trend/<tagName>/<start time>/<end time>/<samplingMode>/<calculationMode>/<direction>/<count>/<intervalMS>
SAMPLE cURL COMMAND (POST): curl -i –X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” -d “{ \”tagNames\”:\”<tagName>\”, \”start\”: \”<start>\”, \”end\”: \”<end>\”, \”samplingMode\”: <samplingMode>, \”calculationMode\”: <calculationMode>, \”direction\”: <direction>, \”count\”: <count>, \”returnDataFields\”: <returnDataFields>, \”intervalMs\”: <intervalMs>, \”queryModifier\”: <queryModifier>, \”filterMode\”: <filterMode>, \”filterExpression\”: \”<filterExpression>\”}” http://<nodename>:443/historian-rest-api/v1/datapoints/trend
Table 14. Query Parameters Parameter Description Required? Values TagNames Queries the tag names specified. Yes String Start Start time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime End End time of the query, in ISO data format (such as YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime SamplingMode Also known as SamplingModeType. Optional Integer, with a value such as 1. CalculationMode Also known as CalculationModeType. Optional Integer, with a value such as 1. Direction Specifies the direction (Forward or Backward from the starting time) of data sampling from the archive. The default value is Forward (1). Optional Integer, with a value such as 1. Count The count of archive values within each calculation interval. Optional Integer, with a value such as 0. IntervalMS Interval in milliseconds. Optional 64-bit signed integer, with a value such as 1000. Table 15. Response Parameters Parameter Data Type Required? Description ErrorCode Integer Yes For example, 0. ErrorMessage String Yes For example, NULL. Data String Yes The object container for the following parameters: - TagName
- Name of the tag, such as ahistfile.Simulation00001.
- TagSource
- Location where tags are being searched for.
- DataType
- Float, which stores decimal values up to 6 places.
- Trend
- Provides TimeStamp, Value and Quality for each sample. For example, TimeStamp = 2016-03-15T04:53:17.000Z, Value = 170903.6563, and Quality = True.
- The Add Single Tag API
-
For the Add Single Tag API, you can add a new tag to Historian, and the tag name and data type must be provided in the payload (parameter) of the method. All other tags are optional. If a property is provided, the respective validation is performed at the server end. If the tag exists, then any new properties provided in the payload are applied to the existing tag.
METHOD: POST URI: https://<NLB DNS>:9090/historian-rest-api/v1/tags/addtag
SAMPLE URI: https://<NLB DNS>:9090/historian-rest-api/v1/tags/addtag Payload: { "Name" : "SampleTag", "DataType" : 3 }
SAMPLE cURL COMMAND: curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -d “{ \”Name\”:\”Sampletag\”,\"DataType\":3}” -X POST https://<NLB DNS>:9090/historian-rest-api/v1/tags/addtag
Table 16. Query Parameters Parameter Description Required? Values Payload JSON array of PropertyName and PropertyValue. Yes. "Name" and "DataType" properties are required. All other properties are optional. Multidata types. See Payload Parameter for a list of tag properties used to update a tag configuration. Sample ResponseParameter Data Type Required? Description ErrorCode Integer Yes For example, 0. ErrorMessage String Yes For example, NULL. - The Add Bulk Tags API
-
For the Add Bulk Tags API, you can add new tags to Historian using an array, and the tag names and data types must be provided in the payload (parameter) of the method. All other tags are optional. If a property is provided, the respective validation is performed at the server end. If the tags exist, then any new properties provided in the payload are applied to the existing tags. The payload is be an array of tags defined.
METHOD: POST URI: https://<NLB DNS>:9090/historian-rest-api/v1/tags/addtags
SAMPLE URI: https://<NLB DNS>:9090/historian-rest-api/v1/tags/addtags Payload: [ { "Name" : "SampleTag1", "DataType" : 3 }, { "Name" : "SampleTag2", "DataType" : 3 } ]
SAMPLE cURL COMMAND: curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -d “[{ \”Name\”:\”Sampletag1\”}, { \”Name\”:\”Sampletag2\”}]” -X POST https://<NLB DNS>:9090/historian-rest-api/v1/tags/addtags
Table 17. Query Parameters Parameter Description Required? Values Payload JSON array tags with individual tags of PropertyName and PropertyValue. Yes. "Name" and "DataType" properties are required. All other properties are optional. Multidata types. See Payload Parameter for a list of tag properties used to update a tag configuration. Table 18. Response Parameters Parameter Data Type Exists? Description TagName String Yes Tag name. ErrorCode Integer Yes For example, 0. ErrorMessage String Yes For example, NULL. - The Update Tag Configuration API
-
The Update Tag Configuration API allows you to set or modify any tag property values. You cannot, however, rename a tag using this API.
METHOD: PUT URI: https://<NLB DNS>:9090/historian-rest-api/v1/tags/properties/tagName
SAMPLE DELETE URI: https://<NLB DNS>:9090/historian-rest-api/v1/tags/properties/tagName Payload: { "PropertyName" : "PropertyValue" }
SAMPLE cURL COMMAND: curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -d “{ \”Description\”:\”SampleDesc\”}” -X PUT https://<NLB DNS>:9090/historian-rest-api/v1/tags/properties/tagName
Table 19. Query Parameters Parameter Description Required? Values tagName Tag name for which properties need to be set or modified. Yes String Payload JSON array of PropertyName and PropertyValue. At least one property must be provided. Multidata types. See Payload Parameter for a list of tag properties used to update a tag configuration. Table 20. Response Parameters Parameter Data Type Required? Description ErrorCode Integer Yes For example, 0. ErrorMessage String Yes For example, NULL. - The Get Tag Properties API
-
You can use this API to specify which properties are required for retrieval. If no property names are provided, then all properties are retrieved. When using the Get Tag Properties method, requesting a non-existent tag name returns an error.
METHOD: GET / POST URI: (GET) https://<NLB DNS>:9090/historian-rest-api/v1/tags/properties/tagName
This URI returns all tag properties.
URI: (POST) https://<NLB DNS>:9090/historian-rest-api/v1/tags/properties/tagName
Payload { "PropertyName1" : 1, "PropertyName2" : 1 }
SAMPLE GET URI: https://<NLB DNS>:9090/historian-rest-api/v1/tags/properties/tagName
SAMPLE POST URI: https://<NLB DNS>:9090/historian-rest-api/v1/tags/properties/tagName Payload: { "Description" : 1 }
SAMPLE cURL GET COMMAND: curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -X GET https://<NLB DNS>:9090/historian-rest-api/v1/tags/properties/tagName
SAMPLE cURL POST COMMAND: curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -d “{ \”Description\”: 1}” -X POST https://<NLB DNS>:9090/historian-rest-api/v1/tags/properties/tagName
Table 21. Query Parameters Parameter Description Required? Values tagName Tag name for which properties need to be retrieved. Yes String Payload JSON array of PropertyName and boolean (true/false). At least one property must be provided. Multi data types. See Payload Parameter for a list of tag properties used to update a tag configuration. Note: The query payload contains all the tag properties you want returned from the server. In the Update Tag Config method, you need to provide the actual tag property value. However, in the Get Tag Properties method, you need to provide the property and a value of 1 (true), to allow it to be read from the server and returned.Table 22. Response Parameters Parameter Data Type Required? Description ErrorCode Integer Yes For example, 0. ErrorMessage String Yes For example, NULL. Name String Optional If no error, then the tag name of query is returned and all requested parameters. - The Delete Tag API
-
The Delete Tag API provides the ability to delete an existing tag from the Historian server.
Its URI format supports question marks (?).
METHOD: DELETE URI: https://<NLB DNS>:9090/historian-rest-api/v1/tags/tagName?{permanentDelete}
SAMPLE DELETE URI: https://<NLB DNS>:9090/historian-rest-api/v1/tags/tagName?permanentDelete=true
SAMPLE CURL COMMAND: curl -i -H "Authorization: Bearer <TOKEN>” -X DELETE https:// <NLB DNS:9090>:443/historian-rest-api/v1/tags/tagName?permanentDelete=<true|false>
Table 23. Query Parameters Parameter Description Required? Values tagName Name of the tag to be deleted. Yes String permanentDelete Deletes the tag permanently from the Historian server if the value passed in is true. If the parameter is not provided, then permanentDelete is assumed to be false. Optional (false is default) Boolean, true or false Table 24. Response Parameters Parameter Data Type Required? Description ErrorCode Number Yes For example, ErrorCode=0, which means the operation was successful. ErrorMessage String Yes For example, NULL. - The Query Results API
The Query Results API enables you to include the number of samples required, by providing an end point to configure query results.
The minimum number of samples should be 1000.METHOD: PUT URI: https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/ configuration/{maxDataQueryResultSize}
SAMPLE URI: https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/ configuration?maxDataQueryResultSize=6000
SAMPLE CURL COMMAND: curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” https://<nodename>:443/ historian-rest-api/v1/datapoints/configuration? maxDataQueryResultSize=<Number_Of_Query_Results>
Table 25. Query Parameters Parameter Description Required? Values maxDataQueryResultSize Maximum samples that should be configured as part of Query Results. Yes Integer - The Tag Rename API
- This API allows the administrator to rename tags.
METHOD: PUT URI https://<NLB DNS>:9090/historian-rest-api/v1/tags/tagrename/oldtagname/newtagname?{truerename}
SAMPLE URI https://<NLB DNS>:9090/historian-rest-api/v1/tags/tagrename/GDW14NV2E.Simulation0000101/GDW14NV2E.Simulation0000101newname?truerename= <true | false>
SAMPLE CURL COMMAND curl -i -H "Accept: application/json" -i -H "Content-Type: application/json"-H "Authorization: Bearer <TOKEN> -X PUT https://<NLB DNS>:9090/historian-rest-api/v1/tags/tagrename/<oldtagname>/<newtagname>?truerename=<true | false>
Table 27. Query Parameters Parameter Description Required? Values oldtagname Tag which is to be renamed. Yes String newtagname New name for the selected tag. Yes String truerename Renames the tag permanently if the value entered is true. Creates an alias if the value entered is false.
Optional (false is default) Boolean (true or false) Table 28. Response Parameters Parameter Data Type Required? Description Error Code Integer Yes For example, 0. Error Message String Yes For example, NULL. Data List Yes Returns all the properties of the tag. - The Write Tag API
- Write Tag Data API enables you to create data for tags. You can write data
to a tag for different data types such as integer, float, array, multifield
and so on. Once created, you can view the data using other end points. Only
REST API Administrator and users with write permission can perform this
operation.
Method POST URI https://<NLB DNS>:9090/historian-rest-api /v1/datapoints/create
SAMPLE URI https://<NLB DNS>:9090/historian-rest-api /v1/datapoints/create Payload { "TagName": "GDW14NV2E.Simulation00015", "samples": [ { "TimeStamp": "2019-09-17T15:58:00.000Z", "Value": "1", "Quality": 3 } ] }
SAMPLE RESPONSE {
"ErrorCode": 0,
"ErrorMessage": ""
}
SAMPLE CURL COMMAND curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -d “{ \”TagName\”:\”GDW14NV2E.Simulation00015\”,\"samples\":[{\"TimeStamp\":\ "2019-09-17T15:58:00.000Z\",\"Value\": \"1\",\"Quality\": 3}]}” -X POST https://<NLB DNS>:9090/historian-rest-api/v1/datapoints/create
Table 29. Query Parameters Parameter Description Required? Values Payload JSON format of Property Name and Property Value. Yes Multi-data types. It can have integer, float, array, multifield data types. Table 30. Response Parameters Parameter Data Type Required? Description Error Code Integer Yes For example, ErrorCode = 0, which means the operation was successful. Error Message String Yes For example, NULL.