historianrestapis - software documentation | ge...

Historian REST APIsReference Manual

Version 7.0 SP1September 2016

Historian REST APIs© 2016 General Electric Company.

GE, the GE Monogram, and Predix are either registered trademarks or trademarks of General Electric Company.All other trademarks are the property of their respective owners.

This documentmay contain Confidential/Proprietary information of General Electric Company and/or its suppliersor vendors. Distribution or reproduction is prohibited without permission.

THIS DOCUMENT AND ITS CONTENTS ARE PROVIDED "AS IS," WITH NO REPRESENTATION ORWARRANTIES OF ANYKIND,WHETHEREXPRESSOR IMPLIED, INCLUDINGBUTNOTLIMITEDTOWARRANTIESOFDESIGN,MERCHANTABILITY,OR FITNESS FORAPARTICULARPURPOSE. ALLOTHER LIABILITY ARISING FROMRELIANCEUPONANY INFORMATIONCONTAINED HEREIN IS EXPRESSLY DISCLAIMED.

Access to and use of the software described in this document is conditioned on acceptance of the End UserLicense Agreement and compliance with its terms.

Contents

Historian APIs Overview 5

Historian APIs Overview 5About Security and Authentication 5Standards 7API Methods 7API Status Messages 7

General API Information 9

Overview of Commonly Used API Parameters 9TagNames Parameter 9Start and End Timestamps Parameter 9TagSamples Parameter 10DataSample Parameter 11SamplingModeType Parameter 12Direction Parameter 13CalculationModeType Parameter 14FilterModeType Parameter 18ReturnDataFields Parameter 18Payload Parameter 19Error Code Definitions 24

Historian REST APIs 26

Overview of the Historian REST APIs 26Tags List API 26Raw Data API 28Interpolated Data API 31Current Value API 33Calculated Data API 34Sampled Data API 37Trend Data API 39Add Single Tag API 41Add Bulk Tags API 42Update Tag Configuration API 44

iiiHistorian REST APIs

Get Tag Properties API 45Delete Tag API 48

Historian REST APIsiv

Historian APIs Overview

Historian APIs Overview

Historian is a high performance data archiving system designed to collect, store, and retrieve time-basedinformation at extremely high speed efficiently. The Historian environment provides a set of REST APIs toquery data from the archives.

This document provides links for setting up your development environment, aswell as information for gettingstarted with the Historian services and their associated APIs.

Important: Port 8443 is used in examples and sample code throughout the e-book. If you copy andpaste the sample code from this document, you must change this port to your installed port.

See the following topics for more information:

• About Security and Authentication on page 5• Standards on page 7• API Methods on page 7• API Status Messages on page 7

About Security and Authentication

For security purposes, Historian uses the User Account and Authentication (UAA) service as a trusted sourceof tokens issued for authentication. The UAA is a multi-tenant identity management service, used in CloudFoundry, but also available as a standalone OAuth2 server. Its primary role is as an OAuth2 provider, issuingtokens for client applications to usewhen they act on behalf of Cloud Foundry users. It can also authenticateusers with Cloud Foundry credentials, and can act as an SSO service using those credentials, or others. Itcontains endpoints formanaginguser accounts, registeringOAuth2 clients, andothermanagement functions.

The following diagram shows how the UAA Server functions with a Python REST client:

5© 2016 General Electric Company.

Figure 1: UAA Server and Python REST Client

Authorization

For exchanging data between the client-server system, user authentication is required. Once you haveprovided your client credentials, an access or bearer token is generated. This token is used for the RESTAPIs.

cURL command format for generating an oauth token:curl -u <Client-Id>:<Client-secret>https://<nodename>:8443/uaa/oauth/token -d 'grant_type=client_credentials'

Sample cURL command: curl -u admin:adminsecret https://<nodename>:8443/uaa/oauth/token -d 'grant_type=client_credentials'

Note: In the following image, the actual token text is blurred for security concerns.

Figure 2: OAuth Access Token Sample

Client applications can access data using service REST API endpoints. Your application makes an HTTPrequest and parses the response. You can use any web-development language to access the APIs.

© 2016 General Electric Company.6

Standards

Historian APIs use a REST application architecture constrained by Hypermedia as the Engine of ApplicationState (HATEOAS) that distinguishes it frommost other network application architectures. Therefore, a clientinteracts with a network application entirely through hypermedia provided dynamically by applicationservers. The REST client doesn't need prior knowledge about how to interact with a particular applicationor server beyond a basic understanding of hypermedia.

As defined by the query parameters, the Historian APIs use "search" functions to access raw data usingcURL and HTTP, while responses are in JSON format.

cURL is a command-line utility used to transfer data fromor to a server, using one of the supported protocols,such as DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP,LDAPS, POP3, POP3S, RTMP, RTSP,SCP, SFTP, SMTP, SMTPS, TELNET and TFTP. The command is designed to work without user interaction.

cURL offers many useful functions such as proxy support, user authentication, FTP upload, HTTP post, SSLconnections, cookies, file transfer resume, user and password authentication, and more.

You can run the sample commands provided in this document from Bash on Windows in the Windowsoperating system, and also in Linux Shell in the Linux operating system.

As a prerequisite, make sure you install cURL on your system, if it is not already installed. Run the curl --version command on Windows Bash or Linux shell to check if cURL is installed on your system.

Important: Do not create your own URIs. Instead, use the links in this document and in the responsesto navigate between resources.

API Methods

The Historian APIs use GET, POST, PUT, and DELETE methods.

UsageMethod

Retrieves a resource.GET

Creates (or adds) a resource.POST

Updates a resource.PUT

Removes a resource.DELETE

API Status Messages

In its use of the following HTTP status codes, the Historian API services adhere as closely as possible tostandard HTTP and REST conventions.

UsageStatus Code

Success message. The request has completed.200 OK


UsageStatus Code

Success message. A new resource has been created. The resource URI isavailable from the location header in the response.

201 Created

Success message. An update to an existing resource has been applied.204 No Content

Error message. The request was malformed. The response body providesadditional information.

400 Bad Request

Error message. Either you are not authenticated, or the authentication isincorrect. You must re-authenticate and try again.

401 Unauthorized

Error message. You do not have permission to access this resource.403 Forbidden

Error message. The requested resource does not exist.404 Not Found

Error message. The server encountered an unexpected condition thatprevented it from fulfilling the request.

500 Internal Error


General API Information

Overview of Commonly Used API Parameters

The Historian REST service provides various REST API calls to retrieve the current tags list and query datawith different sampling modes. Most of these API calls use the following common parameters:

• TagNames Parameter on page 9• Start and End Timestamps Parameter on page 9• TagSamples Parameter on page 10• DataSample Parameter on page 11• SamplingModeType Parameter on page 12• Direction Parameter on page 13• CalculationModeType Parameter on page 14• FilterModeType Parameter on page 18• ReturnDataFields Parameter on page 18• Payload Parameter on page 19• Error Code Definitions on page 24

TagNames Parameter

By default, the Historian REST service provides support to read samples formultiple tags. Multiple tag namesare separated by semicolons (;). For example, "tagname1;tagname2;tagname3".

https://<historianservername>:8443/historian-rest-api/v1/datapoints/currentvalue?tagNames=tagName1;tagname2;tagname3

Encode the semicolon as%3B if using theURI format, as the semicolon is also a valid character for aHistorianname, and the web service parses the tag names incorrectly if a tag name contains a semicolon.

Start and End Timestamps Parameter

For the Start and End Timestamps parameter, the Timestamp format in the URI must be in ISO data format,such as YYYY-MM-DDTHH:mm:ss.SSSZ.

EPOCH time (standard base time) is only valid in the JSON-format request body or response body, such as\/Date(928167600000-0500)\/. If you use the same timestamp for start and end timestamps, therequest returns a single result.

All timestamps passed to the REST service must be formatted as UTC timestamps.


DescriptionObject Name

Start time of the query. This represents the earliesttimestamp for any tag contained in the query.

If no StartTime is specified, the start time is two hoursprior to running the query.

StartTime

End time of the query. This represents the latesttimestamp for any tag contained in the query.

If no EndTime is specified, the end time is the timethat the query runs.

EndTime

TagSamples Parameter

The TagSamples parameter is the output from the REST API calls.

DescriptionPropertyType

PropertyName

Name of the tag.StringTagName

Tag Data Type Value:StringDataType

• Blob – Stores tags as binary large objects. The Blob datatype generallyrefers to undeterminedbinary data types, such as an Excel spreadsheet,a PDF file, or a Word file.

• Boolean (one byte) – Stores boolean values. Valid values for the booleandata type are 0=FALSE and 1=TRUE. If the user sends zero, the value istaken as zero. Anything other than zero, the value is treated as one.

• Byte (one byte) – Stores integer values. Valid values for the byte datatype are -128 to +127.

• SingleFloat (four bytes) – Stores decimal values up to six places. Validranges for the single float data type are 1.175494351e-38F to3.402823466e+38F

• DoubleFloat (eight bytes) – Stores decimal values up to 15 places. Validvalues for the double float data type are 2.2250738585072014e-308to 1.7976931348623158e+308.

• SingleInteger (two bytes) – Stores whole numbers, without decimalplaces. Valid values for the single integer data type are -32767 to+32767.

• DoubleInteger (four bytes) – Stores whole numbers, without decimalplaces. Valid values for the double integer data type are -2147483648to +2147483648.

• FixedString (Configured by user) – Stores string data of a fixed size.Valid values are between 0 and 255 bytes.

• Float – Single float.• Integer – Single integer.• MultiField – Stores string data that has multiple words.



PropertyName

• QuadInteger (eight bytes) – Stores whole numbers without decimalplaces. Valid values for the quad integer data type are-9,223,372,036,854,775,808 (negative nine quintillion) to+9,223,372,036,854,775,807 (positive nine quintillion).

• Scaled (two bytes) – Lets you store a four-byte float as a twobyte integerin the Historian archive. The scaled data type saves disk space butsacrifices data precision as a result.

• Time – Returns or sets the type of time stamping applied to data atcollection time.

• UDoubleInteger (UnsignedDouble Integer) (four bytes) – Storeswholenumbers without decimal places. Valid values for the unsigned doubleinteger data type are 0 to 4,294,967, 295 (4.2 billion).

• Undefined – Data type is not defined.• UQuadInteger (Unsigned Quad Integer) (eight bytes) – Stores whole

numbers without decimal places. Valid values for the unsigned quadinteger data type are 0 to 18,446,744,073,709,551,615 (19 quintillion).

• USingleInteger (Unsigned Single Integer) (two bytes) – Stores wholenumbers without decimal places. Valid values for the unsigned singleinteger data type are 0 to 65535.

• VariableString (No fixed size) – Stores string values of undeterminedsize. This data type is useful if you cannot rely on a constant stringlength from your data source.

• Array – Returns an array of tags fromyour data source. You can specifyorientation, size, and number of rows returned in the array.

Error Code Definition

See Error Code Definitions on page 24 for more information.

Error CodeErrorCode

See DataSample Parameter on page 11 for more information.DataSample

Samples

DataSample Parameter

The DataSample Parameter specifies the number of data samples to retrieve from the archive. Samples areevenly spaced within the time range defined by start time and end time for most sampling modes.

DescriptionProperty TypeProperty Name

Format for a multi-field tag like {"field1":"1","field2":"1000.0"} (user-defined type tag).

JavaScript code can parse the valuestring as a JSON object. All field valuesare string.

StringValue


DescriptionProperty TypeProperty Name

Start and end times of the query. If nostart time is specified, the start time is

DateTimeTimeStamp

two hours prior to running the query. Ifno EndTime is specified, the end time isthe time the query runs.

Data type consisting of a set of namedvalues called elements, members or

Integer

(Enumerated value ofDataQuality.StatusType)

Quality

enumerators of the type. Property valuesreflect quality as "quality is good" or "quality is bad".

Value andStatus • 0 – Bad

• 1 – Uncertain• 2 – NA• 3 – Good

SamplingModeType Parameter

The SamplingModeType parameter is the mode of sampling data from the archive. The default setting forthe Sampling Mode is Calculated.

ValueDescriptionProperties

0Sampling mode is not defined.Undefined

1Retrieves the current value. The time-interval criteria are ignored.

CurrentValue

2Retrieves evenly-spaced, interpolatedvalues based on interval or

Interpolated

NumberOfSamples and the time-framecriteria.

3Returns the raw minimum and rawmaximum value for each specified

Trend

interval. Use the Trend samplingmode tomaximize performance when retrievingdata points for plotting. For the Trendsampling mode, if the sampling intervaldoes not evenly divide by the intervallength, Historian ignores any leftovervalues at the end, rather than puttingthem into a smaller interval.

4Retrieves raw archive values based ontime-frame criteria.

RawByTime



5Retrieves rawarchive values based on theStartTime criteria, theNumberOfSamples,

RawByNumber

andDirection criteria. The EndTimecriteriais ignored for this sampling mode.

6Retrieves evenly spaced calculated valuesbased onNumberOfSamples, interval, the

Calculated

time frame criteria, and theCalculationMode criteria.

7Returns actual collected values withoutinterpolation.

Lab

8Provides rawdata in place of interpolateddata when the number of samples arefewer than the available samples.

InterpolatedtoRaw

9The TrendtoRaw sampling mode almostalways produces the same results as the

TrendtoRaw

Trend sampling mode. However, whenmore samples are requested than thereare raw data points, the TrendtoRawsampling mode returns all available rawdata points with no further processing.Use TrendtoRaw in place of Trend whenthis condition exists.

10Provides raw data for the selectedcalculateddata,whenNumberOfSamplesis less than the available samples.

LabtoRaw

11Returns filtered time ranges using thefollowing values:

RawByFilterToggle

• 1 – true• 0 – false

This samplingmode is used with the timerange and filter tag conditions. Theresponse string starts with a starting timestamp and ends with an endingtimestamp.

Direction Parameter

TheDirection Parameter specifies the direction (Forward or Backward from the starting time) of data samplingfrom the archive. The default value is Forward.

ValueDirection

0Forward


ValueDirection

1Backward

CalculationModeType Parameter

The CalculationModeType parameter is only applied if the Sampling Mode is set to Calculated. It representsthe type of calculation to use on the archive data. The default Calculation Mode, if none is specified, isAverage.

ValueDescriptionCalculation Mode Type

0Calculation mode is not defined.Undefined

1Retrieves the time-weighted average for eachcalculation interval.

Average

2Retrieves the time-weighted standarddeviation for each calculation interval.

StandardDeviation

3Retrieves the time-weighted rate total for eachcalculation interval.

Use rate totals when working with acontinuous measurement. Time weighting

Total

takes into account that compressed data isnot evenly spaced in time. A factor must beapplied to the total value to convert intoappropriate engineering units. As a rate total,the default is Units/Day. If the actual units ofthe continuous measurement areUnits/Minute, you would multiply the resultsby 1440 (minutes per day) to convert the totalinto appropriate engineering units.

4Retrieves the minimum value for eachcalculation interval.

Minimum

5Retrieves the maximum value for eachcalculation interval.

Maximum

6Counts the number of raw samples foundwithgood quality in the interval.

Value is the count of raw samples with goodquality in the interval. The values of each

Count

sample are ignored. The Count does notinclude any samples of bad quality, includingthe start and end of collection markers.

For Quality, the percentage of good samplesis always 100, even if the interval does notcontain any raw samples, or contains only badquality samples.



Count is useful for analyzing the distributionof the raw data samples to determine theeffect of compression deadbands. It is alsouseful to determinewhich tags are consumingthe most archive space.

7Retrieves the arithmetic average of all goodquality raw samples for each calculationinterval.

Value is the sum of all good quality samplesin the interval, divided by the number of good

RawAverage

quality samples in the interval. All bad qualitysamples are ignored. That is RawAverage isequivalent to RawTotal divided by the Count.

For Quality, if there are no raw samples in theinterval or if they all are bad quality, then thepercentage of good is 0. Otherwise, thepercentage of good is always 100, even if theinterval contains bad quality samples.

RawAverage is useful for calculating anaccurate average when a sufficient numberof raw samples are collected.

8Retrieves the arithmetic standard deviation ofraw values for each calculation interval.

For Value, any raw point of bad data qualityis ignored.

RawStandardDeviation

For Quality, if there are no raw samples in theinterval or they all have bad quality, then thepercentage of good is 0. Otherwise, thepercentage of good is always 100, even if theinterval contains bad quality samples.

RawStandardDeviation is useful for calculatingan accurate standard deviation when asufficient number of raw samples arecollected.

9Retrieves the arithmetic total (sum) of sampledvalues for each interval.

Value is the sum of the good quality values ofall raw samples in the interval. All bad qualitysamples are ignored.

RawTotal

For Quality, the percentage of good samplesis always 100, even if the interval does notcontain any raw samples or it contains onlybad quality samples.



If the same start and end times are used, andthe time span is treated as a single interval,then all values are added together.

RawTotal is useful for calculating an accuratetotalwhena sufficient number of raw samplesare collected. Note that unlike ihTotal, this isa simple sum with no assumption that thevalues are rate values.

10Retrieves the timestampof theminimumvaluefound within each calculation interval. It can

MinimumTime

be a raw or an interpolated value. Theminimummust be agooddata quality sample.

11Retrieves the timestamp of the maximumvalue found within each calculation interval.

MaximumTime

It can be a raw or an interpolated value. Themaximummust be a good data qualitysample.

12Retrieves the amount of time (milliseconds)during the interval when the data is of goodquality and the filter condition is met.

TimeGood

13Retrieves the amount of time a tag uses totransition to another state from a previousstate during a time interval.

StateCount

14Retrieves the duration that a tag stayed in agiven state within an interval.

StateTime

15Retrieves the OPCQAND, bit-wise ANDoperation of all the 16-bit OPC qualities of theraw samples stored in the specified interval.

Note that OPC Quality is a subfield forQuality-Value-Timestamp (QVT), so when this

OPCQAnd

calculation mode is used, OPC Quality isconsidered for calculation.

16Retrieves the OPCQOR, bit-wise OR operationof all the 16-bit OPC qualities of the rawsamples stored in the specified interval.

Note that OPC Quality is a subfield forQuality-Value-Timestamp (QVT), so when this

OPCQOr

calculation mode is used, OPC Quality isconsidered for calculation.

17Retrieves the first good raw sample value fora given interval.

Value is the value of the raw sample, or zeroif there are no good raw samples in theinterval.

FirstRawValue



For Quality, if there are not good raw samplesin the interval, then the percentage of good is0. Otherwise, the percentageof good is always100, even if the interval contains bad qualitysamples. Note that Quality is the same forFirstRawValue and FirstRawTime.

The Raw sample has a quality of Good, Bad,or Uncertain, and that is converted to a 0 or100 percent.

18Retrieves the first good raw timestamp for agiven interval.

Value is the timestamp of the sample or theyear 1969 if there are no good raw samplesin the interval.

FirstRawTime

For Quality, if there are not good raw samplesin the interval, then the percentage of good is0. Otherwise, the percentageof good is always100, even if the interval contains bad qualitysamples. Note that Quality is the same forFirstRawValue and FirstRawTime.


19Retrieves the last good raw sample value fora given time interval.

Value is the value of the raw sample or zero ifthere are no good raw samples in the interval.

LastRawValue

For Quality, if there are no good raw samplesin the interval, the the percentage of goodsamples is 0. Otherwise, the percentage ofgood is always 100, even if the intervalcontains bad samples. Note that Quality is thesame for LastRawValue and LastRawTime.


20Retrieves the last good timestamp of the lastvalue for a given time interval.

Value is the timestamp of the sample or theyear 1969 if there are no good raw samplesin the interval.

LastRawTime

For Quality, if there are no good raw samplesin the interval, the percentage of goodsamples is 0. Otherwise, the percentage of



good is always 100, even if the intervalcontains bad samples. Note that Quality is thesame for LastRawValue and LastRawTime.


21Retrieves the statistics for a tag from thearchive stored in the specified interval.

TagStats

FilterModeType Parameter

The FilterModeType parameter defines how time periods before and after transitions in the filter conditionshould be handled.

When the FilterModeType parameter is applied, then the Start time and End time are specified as:

• ExactTime• BeforeTime• AfterTime• BeforeAndAfterTime

For example, AfterTime indicates that the filter condition should be True starting at the timestamp of thearchive value that triggered the True condition, and leading up to the timestamp of the archive value thattriggered the False condition.


1Retrieves data for the exact times thatthe filter condition is True.

ExactTime

2Retrieves data from the timestamp ofthe last False filter condition to thetimestamp of the next True condition.

BeforeTime

3Retrieves data from the timestamp ofthe True filter condition to thetimestamp of the next False condition.

AfterTime

4Retrieves data from the timestamp ofthe last False filter condition to thetimestamp of the next False condition.

BeforeAndAfterTime

ReturnDataFields Parameter

The ReturnDataFields bitwise parameter specifies which data fields are returned in a query. Using it in aquery returns data such as TimeStamp, and each field returns a Boolean value.


Each time-series data sample contains QVT (quality, value, and timestamp) values. If ReturnDataFields isnot provided, then the default value of 0 is considered, and all QVT values are returned for each data sample.To return one of the data field properties, such as TimeStamp, use the TimeStamp option as shown in thetable.

Field value (Boolean)DescriptionProperties

0 (0000)Specifies that all data fieldsare returned in the query.

All Fields

1 (0001)The time stamp of thecollected sample or an interval

TimeStamp

time stamp.When specified inthe query, returns theTimeStamp property.

2 (0010)The collected value orsampled value; the data type

Value

of the value will be the samedata type as the tag's rawdata.

4 (0100)When specified in the query,returns the Quality property.

Quality

Each sample in Current Valueand Raw query retrieval has aquality of:

• Good (3)• Not Available (2)• Uncertain (1)• Bad (0)

Interpolated and Lab Retrievalexpress quality as "percentgood".

Payload ParameterThis parameter queries for the tag properties requested from the server.

Use the Payload parameter to query for all the tag properties to return from the server. In the Update TagConfiguration API, you must provide the actual tag property value. However, in the Get Tag Properties API,you must provide the property name and value of 1 (true), so the property can be read from the server andreturned.

The properties listed in the following table are valid in APIs that use the Payload parameter, unless otherwisespecified. For Property Names used in the Get Tag Properties API, the property name is always a Boolean(true/false) value, while it can be a string or integer for other APIs.


Property Name

Used for Get Tag Properties API.BooleanAllFields



Property Name

Used for the Get Tag Properties API, Add Single TagAPI, and Add Bulk Tags API.

Boolean,String

Name

StringDescription

StringEngineeringUnits

StringComment

Type definition is an enumerated type "ihDataType".

{ihDataTypeUndefined = 0,

SignedIntegralDataType : ihDataType

ihScaled,ihFloat,ihDoubleFloat,ihInteger,ihDoubleInteger,ihFixedString,ihVariableString,ihBlob,ihTime,ihInt64,ihUInt64,ihUInt32,ihUInt16,ihByte,ihBool,ihMultiField,ihArray,ihMaxDataType} ihDataType;

UnsignedCharFixedStringLength

StringCollectorName

StringSourceAddress

Type definition is an enumerated type"ihCollectionType".

{ihUnsolicited = 1,

SignedIntegralCollectionType : ihCollectionType

ihPolled} ihCollectionType;

SignedIntegralCollectionInterval

UnsignedLongCollectionOffset

BooleanLoadBalancing



Property Name

Type definition is an enumerated type"ihTimeStampType".

{ihSource = 1,

SignedIntegralTimeStampType : ihTimeStampType

ihInterface,} ihTimeStampType;

DoubleHiEngineeringUnits

DoubleLoEngineeringUnits

BooleanInputScaling

DoubleHiScale

DoubleLoScale

BooleanCollectorCompression

FloatCollectorDeadbandPercentRange

BooleanArchiveCompression

FloatArchiveDeadbandPercentRange

StringGeneral1

StringGeneral2

StringGeneral3

StringGeneral4

StringGeneral5

StringReadSecurityGroup

StringWriteSecurityGroup

StringAdministratorSecurityGroup

Used for Get Tag Properties API.BooleanLastModified

Used for Get Tag Properties API.BooleanLastModifiedUser

Used for Get Tag Properties API.BooleanInterfaceType

Type definition is an enumerated type"ihInterfaceType".

{ihInterfaceUndefined = 0,

SignedIntegralCollectorType : ihInterfaceType

ihIFix,ihRandom,ihOPC,ihFile,ihIFixLabData,ihManualEntry,



Property Name

ihOther,ihCalcEngine,ihServerToServer,ihPI,ihOPCAE,ihCIMPE,ihPIDistributor,ihCIMME,ihPerfTag,ihCustom,ihServerToServerDistributor,ihWindowsPerfMon,} ihInterfaceType;

SignedIntegralUTCBias

Used for Get Tag Properties API.BooleanAverageCollectionTime

StringArrayCalculationDependencies

BooleanCollectionDisabled

UnsignedLongArchiveCompressionTimeout

UnsignedLongCollectorCompressionTimeout

BooleanSpikeLogic

BooleanSpikeLogicOverride

BooleanCollectorAbsoluteDeadbanding

DoubleCollectorAbsoluteDeadband

BooleanArchiveAbsoluteDeadbanding

DoubleArchiveAbsoluteDeadband

BooleanStepValue

Type definition is an enumerated type"ihTimeResolution".

{ihSeconds = 0,

SignedIntegralTimeResolution : ihTimeResolution

ihMilliseconds,ihMicroseconds,ihNanoseconds} ihTimeResolution;

BooleanConditionCollectionEnabled

StringConditionCollectionTriggerTag



Property Name

Type definition is an enumerated type"ihConditionCollectionComparison".

{ihConditionComparisonUndefined = 0,

SignedIntegralConditionCollectionComparison :ihConditionCollectionComparison

ihConditionComparisonEqual,ihConditionComparisonLessThan,ihConditionComparisonLessThanEqual,ihConditionComparisonGreaterThan,ihConditionComparisonGreaterThanEqual,ihConditionComparisonNotEqual} ihConditionCollectionComparison;

StringConditionCollectionCompareValue

BooleanConditionCollectionMarkers

When the Calculation field is used, then two moreconditions are required. Calculation is not a specific

StringCalculation

field for a tag property. If the tag's collector orinterface type is Server-to-server and the Calculationfield is set (not Null), then the field value is set to thesource address.

Used for Get Tag Properties API.BooleanTagId

StringEnumeratedSetName

StringDataStoreName

Long LongDefaultQueryModifiers

StringUserDefinedTypeName

SignedIntegralNumberOfElements

Type definition is an enumerated type"ihTagDataDensity".

{ihDataDensityUndefined = 0,

SignedIntegralDataDensity : ihTagDataDensity

ihDataDensityMinimum = 1,ihDataDensityMedium = 4,ihDataDensityMaximum = 7} ihTagDataDensity;

Type definition is an enumerated type "ihCalcType".

{ihRawTag = 0,

SignedIntegralCalcType : ihTagCalcType

ihAnalyticTag = 1,ihPythonExprTag = 2} ihTagCalcType;

Used for Get Tag Properties API.BooleanHasAlias



Property Name

Used for Get Tag Properties API.BooleanIsStale

Error Code Definitions

The following table provides the values and definitions for the ErrorCode parameter.

Table 1: Error Code Definitions

Error Code DefinitionError Code Value:

Operation successful.Success = 0

Operation failed.Failed = -1

Operation failed due to timeout.Timeout = -2

Not connected to Historian server.NotConnected = -3

The given collector does not exist on the server.CollectorNotFound = -4

Operation not supported.NotSupported = -5

Attempt to overwrite an existing data sample.DuplicateData = -6

Bad user name or password.InvalidUsername = -7

Insufficient permissions for operation.AccessDenied = -8

Attempted data write too far in the future.WriteInFuture = -9

Attempted data write to an offline archive.WriteArchiveOffline = -10

Attempted data write to a read-only archive.WriteArchiveReadonly = -11

Attempted data write beyond the configured activerange.

WriteOutsideActiveRange = -12

Attempted data write with no available archives.WriteNoArchiveAvailable = -13

The requested tag was not found.InvalidTagname = -14

Number of licensed tags exceeded.LicensedTagCountExceeded = -15

Number of licensed server connections exceeded.LicensedConnectionCountExceeded = -16

Internal license error.InternalLicenseError = -17

No available tag data.NoValue = -18

The given collector namealready exists on the server.DuplicateCollector = -19

Server or feature is not licensed.NotLicensed = -20

Circular reference detected in calculation.CircularReference = -21

Insufficient disk space to perform backup.BackupInsufficientSpace = -22


Error Code DefinitionError Code Value:

Operation unsupported due to server version.InvalidServerVersion = -23

Upper limit on query results exceeded.QueryResultSizeExceeded = -24

Attempted data delete outside allowedmodificationinterval.

DeleteOutsideActiveRange = -25

Alarm and Event subsystem unreachable.AlarmArchiverUnavailable = -26

A supplied argument is invalid.ArgumentException = -27

A supplied argument is NULL.ArgumentNullException = -28

A supplied argument is outside the valid range.ArgumentOutOfRangeException = -29

The requested Enumerated Set was not found.InvalidEnumeratedSet = -30

The requested data store was not found.InvalidDataStore = -31

Operation not permitted.NotPermitted = -32

The Custom data type is not supported.InvalidCustomDataType = -33

N/AihSTATUS_EXISTING_USERDEF_REFERENCES = -34

N/AihSTATUS_INVALID_TAGNAME_DELETEDTAG = -35

N/AihSTATUS_INVALID_DHS_NODENAME = -36

N/AihSTATUS_DHS_SERVICE_IN_USE = -37

N/AihSTATUS_DHS_STORAGE_IN_USE = -38

N/AihSTATUS_DHS_TOO_MANY_NODES_IN_MIRROR =-39

N/AihSTATUS_ARCHIVE_IN_SYNC = -40

N/AInvalidArchiveName= -41

Session id is invalid.InvalidSession = 1

Session has expired.SessionExpired = 2

Unknown error, please check server log.UnknownError = 3

No valid client buffer manager.NoValidClientBufferManager= 4

No value in returned data set.NoValueInDataSet = 5

Tag doesn't exist.TagNotExisting = 6

Service call to central buffer server fail.ClientBufferManagerCommunicationError = 7

Tag type is not supported.TagTypeNotSupported=8

Value type doesn't match tag data type.ValueTypeNotMatchTagDataType = 9

Invalid query parameter.InvalidParameter=10

Tag Search Criteria result was more than 5000.TagSearchResultIsHuge = 11

No valid server or historian server name isn't in theserver list.

InvalidHistorianServer=12


Historian REST APIs

Overview of the Historian REST APIs

Historian provides the following APIs, which use REST calls to retrieve data and tag information from theHistorian archives.

Important: Port 8443 is used in examples and sample code throughout the e-book. If you copy andpaste the sample code from this document, you must change this port to your installed port.

• Tags List API on page 26: Provides a list of the current tags.• Raw Data API on page 28: Queries raw data using a number of samples or a time range for a list of tags.• Interpolated Data API on page 31: Queries interpolated data for a list of tags.• Current Value API on page 33: Queries the current value data for a list of tags.• Calculated Data API on page 34: Queries calculated data for a list of tags, using a number of samples

or a time range for those tags.• Sampled Data API on page 37: Queries sampled data using a number of samples or a time range for a

list of tags.• Trend Data API on page 39: Queries trend data for a list of tags.• Add Single Tag API on page 41• Add Bulk Tags API on page 42• Update Tag Configuration API on page 44• Get Tag Properties API on page 45• Delete Tag API on page 48

Tags List API

The Tags List API retrieves the qualified tag name list by a given nameMask.

Note: URI format supports asterisks (*) and question marks (?).

GETMETHOD:

https://<historianservername>:8443/historian-rest-api /v1/tags/{nameMask}/{maxNumber}

URI:

https://<historianservername>:8443/historian-rest-api /v1/tags?nameMask=*&maxNumber=100

SAMPLE URI:

curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” https://<nodename>:8443/

SAMPLE cURL COMMAND:

historian-rest-api/v1/tags?nameMask=*&maxNumber=<Number_Of_Tags>


Query Parameters

ValuesRequired?DescriptionParameter

StringOptionalTagmask that searches for all tags thatmatch the mask and applies the

nameMask

remaining criteria to retrieve data. Themask can include wildcards, such asasterisks (*).

Integer

0 by default

OptionalMaximumtagnumberprovides the limitwhile 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 isused for the maxNumber.

maxNumber

If a positive number is used, then thatnumber of tags is returned. In addition,an error number of +14 notifies the userthat there aremore than the requestednumber of tags in the system.

Response Parameters

DescriptionRequired?Data TypeParameter

For example, ErrorCode = 0, which means theoperation was successful.

YesNumberErrorCode

For example, NULL.YesStringErrorMessage

Includes the following:YesStringtags

• ALT_SENSOR• tagName1• tagName2

Sample Response

{"ErrorCode":0,"ErrorMessage": null,"tags": [

"ALT_SENSOR","tagName1","tagName2"

]}


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 thecount is not zero, then the API service returns the number of raw samples taken beginning from the starttime. If the count is zero, then the service returns the raw samples taken between the start time and theend time.

GET, POSTMETHOD:

URI:https://<historianservername>:8443/historian-rest-api/v1/datapoints/raw/{tagNames}/{start}/{end}/{direction}/{count}

GET

https://<historianservername>:8443/historian-rest-api/v1/datapoints/raw/{start}/{end}/{direction}/{count}

POST

SAMPLE GET URI:Count value is a non-zero positive number, and end time is greaterthan start time.

Raw ByNumber

https://<historianservername>:8443/historian-rest-api/datapoints/raw/tagName1/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/0/100

https://<historianservername>:8443/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

The count value equals 0.Raw ByTime

https://<historianservername>:8443/historian-rest-api/datapoints/raw/tagName1/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/0/0

https://<historianservername>:8443/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:Count value is a non-zero positive number, and end time is greaterthan start time.

Raw ByNumber

https://<historianservername>:8443/historian-rest-api/datapoints/raw/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/0/100


https://<historianservername>:8443/historian-rest-api/datapoints/raw?start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&count=100&direction=0

The count value equals 0.Raw ByTime

https://<historianservername>:8443/historian-rest-api/datapoints/raw/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/0/0

https://<historianservername>:8443/historian-rest-api/datapoints/raw?start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&count=0&direction=0

curl -i -H "Accept: application/json" -H "Authorization:Bearer <TOKEN>” http://<nodename>:8443/ historian-rest-

SAMPLE cURLCOMMAND (GET):[Raw By Number] api/v1/ datapoints/raw/<tagName>/<start time>/<end

time>/<direction>/<count>


SAMPLE cURLCOMMAND (GET):[Raw By Time] api/v1/ datapoints/raw/<tagName>/<start time>/<end

time>/<direction>/0

curl –X POST -i -H "Content-Type: application/json" -H"Accept: application/json" -H "Authorization: Bearer <TO

SAMPLE cURLCOMMAND (POST):[Raw By Number] KEN>” -d “{\”tagNames\”=\”<tagName>\”}” http://<node

name>:8443/ historian-rest-api/v1/ datapoints/raw/<starttime>/<end time>/<direction>/<count>

curl –X POST -i -H "Content-Type: application/json" -H"Accept: application/json" -H "Authorization: Bearer <TO

SAMPLE cURLCOMMAND (POST):[Raw By Time] KEN>” -d “{\”tagNames\”=\”<tagName>\”}” ‘ http://<node

name>:8443/ historian-rest-api/v1/ datapoints/raw?start=<start time>&end=<end time>&direction=<direction>&count=<count>’

Query Parameters


StringYesQueries the specified tagnames.

TagNames

DateTimeYesStart time of the query, in ISOdata format (such asYYYY-MM-DDTHH:mm:ss.SSSZ).

Start

DateTimeYesEnd time of the query, in ISOdata format (such asYYYY-MM-DDTHH:mm:ss.SSSZ).

End



Integer, with a value such as 0.YesSpecifies the direction(Forward or Backward from

Direction

the starting time) of datasampling from the archive.The default value is Forward(0).

Integer, with a value such as 100.YesCount of archive valueswithineach calculation interval.

Count

Response Parameters


For example, 0.YesIntegerErrorCode


The object container for the followingparameters:

YesStringData

DoubleFloat,whichstoresdecimalvalues up to 15 places.

DataType

Value is 0, which means theoperation was successful.

ErrorCode

Example: TagName1.TagName

Provides TimeStamp, Value andQuality for each sample. For

Samples

example, TimeStamp =2013-10-02T11:30:00.111Z, Value= 34.26155, and Quality = 3.

Sample Response

{"ErrorCode" : 0,"ErrorMessage": null,"Data":[{"DataType":"DoubleFloat","ErrorCode":0,"TagName":"TagName1","Samples":[ {

"TimeStamp":"2013-10-02T11:30:00.111Z","Value":"34.26155","Quality":3 },

{ "TimeStamp":"2013-10-02T11:30:10.111Z","Value":"37.26155", "Quality":3 },

{ "TimeStamp":"2013-10-02T11:31:00.111Z","Value":"33.26155", "Quality":3 }

]


}]}

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.

GET, POSTMETHOD:

URI:https://<historianservername>:8443/historian-rest-api/v1/datapoints/interpolated/{tagNames}/{start}/{end}/{count}/{intervalMs}

GET

https://<historianservername>:8443/historian-rest-api/v1/datapoints/interpolated/{start}/{end}/{count}/{intervalMs}

POST

https://<historianservername>:8443/historian-rest-api/v1/datapoints/interpolated/tagName1/2013-10-02T11:30:00.111111Z/2013-10-02T11:31:11.111Z/100/10000

SAMPLE GET URI:

https://<historianservername>:8443/historian-rest-api/v1/datapoints/interpolated/2013-10-02T11:30:00.111111Z/2013-10-02T11:31:11.111Z/100/10000

SAMPLE POST URI:


SAMPLEcURLCOMMAND(GET):

api/v1/ datapoints/interpolated/<tagName>/<starttime>/<end time>/<count>/<intervalMS>

curl -i –X POST -H "Content-Type: application/json" -H"Accept: application/json" -H "Authorization: Bearer

SAMPLEcURLCOMMAND(POST):

<TOKEN>” -d “{\”tagNames\”:\”<tagName>\”}”http://<nodename>:8443/ historian-rest-api/v1/ datapoints/interpolated/<start time>/<endtime>/<count>/<intervalMS>

Query Parameters


StringYesQueries the tag namesspecified.

TagName


Start




End


Count

64-bit signed integer, with a value such as10000.

YesInterval in milliseconds.intervalMS

Response Parameters





YesStringData


DataType


ErrorCode

Example is TagName1.TagName


Samples


Sample Response





]


}]}

Current Value API

The Current Value API queries the current value data and reads the current values for a list of tags. If thestart time is equal to end time, the requiest returns one sample.

GET, POSTMETHOD:

URI:https://<historianservername>:8443/historian-rest-api/v1/datapoints/raw/{tagNames}/{start}/{end}/{direction}/{count}

GET

https://<historianservername>:8443/historian-rest-api/v1/datapoints/currentvalue

POST

https://<historianservername>:8443/historian-rest-api/v1/datapoints/currentvalue?tagNames=tagName1

SAMPLE GET URI:

https://<historianservername>:8443/historian-rest-api/v1/datapoints/currentvalue

SAMPLE POST URI:

curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” http://<nodename>:8443/ historian-rest-api/v1/ datapoints/currentvalue/<tagName>

SAMPLE cURL COMMAND(GET):

curl -i –X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer

SAMPLE cURL COMMAND(POST):

<TOKEN>” -d “{\”tagNames\”:\”<tagName>\”}”http://<nodename>:8443/ historian-rest-api/v1/ datapoints/currentvalue

Query Parameters


StringYesQueries the specified tagnames.

TagNames

Response Parameters







YesStringData

DoubleFloat, which storesdecimal values up to 15 places.

DataType


ErrorCode



Samples

example, TimeStamp =2014-01-01T12:00:00Z, Value =34.26155, and Quality = 3.

Sample Response


"TimeStamp":"2014-01-01T12:00:00Z","Value":"34.26155","Quality":3 } ]}]

}

Calculated Data API

The CalculatedData API queries the calculated data for a list of tags. Data can be requested using a numberof samples or a time range for a list of tags. If the count is not zero, the service returns the number of rawsamples beginning from the start time. If the count is zero, the services uses the interval, start time, andend time to calculate the required sample number.

GET, POSTMETHOD:

URI:https://<historianservername>:8443/historian-rest-api/v1/datapoints/calculated/{tag

GET

Names}/{start}/{end}/{calculationMode}/{count}/{intervalMs}

https://<historianservername>:8443/historian-rest-api/v1/datapoints/calculated/{start}/{end}/{calculationMode}/{count}/{intervalMs}

POST


SAMPLE GET URI:https://<historianservername>:8443/historian-rest-api/v1/datapoints/calculated/tag

NumberofSamples

Name1/2013-10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/1/100/1000

https://<historianservername>:8443/historian-rest-api/v1/datapoints/calculated?tag

TimeRange for Listof Tags

Names=tagName1&start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&count=100&calculationMode=1&intervalMs=1000

SAMPLE POST URI:https://<historianservername>:8443/historian-rest-api/v1/datapoints/calculated/2013-

Number of Samples

10-02T11:30:00.111Z/2013-10-02T11:31:11.111Z/1/100/1000

https://<historianservername>:8443/historian-rest-api/v1/datapoints/calculat

Time Range for Listof Tags

ed?start=2013-10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&count=100&calculationMode=1&intervalMs=1000


SAMPLE cURLCOMMAND (GET):

api/v1/ datapoints/calculated/<tagName>/<start time>/<endtime>/<count>/<calculation mode>/<intervalMS>

curl -i –X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>”

SAMPLE cURLCOMMAND (POST):

-d “{\”tagNames\”:\”<tagName>\”}” http://<nodename>:8843/historian-rest-api/v1/ datapoints/calculated/<starttime>/<end time>/<count>/<calculationmode>/<intervalMS>

Query Parameters


1000000106YesGE identifier for a location.TagNames


Start


End


Count



Integer, with a value such as 1.YesEnd time in milliseconds.CalculationMode


Interval in milliseconds.IntervalMS

Response Parameters



For example, NULL.YesStringErrorCode


YesStringData


DataType


ErrorCode



Samples


Sample Response





]}]

}


Sampled Data API

The Sampled Data API queries the sampled data for a list of tags. Data can be requested using a numberof samples or a time range for a list of tags. If the count is not zero, the service returns the number of rawsamples beginning from the start time. If the count is zero, the services uses the interval, start time, andend 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.

GET, POSTMETHOD:

URI:https://<historianservername>:8443/historian-rest-api/v1/datapoints/sampled

GET

https://<historianservername>:8443/historian-rest-api/v1/datapoints/sampled

POST

https://<historianservername>:8443/historian-rest-api/v1/datapoints/sampled?tagNames=tagName1&start=2013-

SAMPLE GET URI:

10-02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&samplingMode=1&calculationMode=1&direction=0&count=0&intervalMs=1000

https://<historianservername>:8443/historian-rest-api/v1/datapoints/sampled

SAMPLE POST URI:



api/v1/ datapoints/sampled/<tagName>/<start time>/<endtime>/<direction>/<count>/<intervalMS>



<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>:8443/historian-rest-api/v1/datapoints/sampled

Query Parameters



TagNames




Start


End

Integer, with a value such as 1.OptionalAlso known asSamplingModeType.

SamplingMode

Integer, with a value such as 1.OptionalAlso known asCalculationModeType.

CalculationMode

Integer, with a value such as 0.OptionalSpecifies the direction(Forward or Backward from

Direction


Integer, with a value such as 0.OptionalThe count of archive valueswithin each calculationinterval.

Count


OptionalInterval in milliseconds.IntervalMS

Response Parameters



For example, NULL.YesStringErrorCode


YesStringData


DataType


ErrorCode



Samples



Sample Response





]}]

}

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.

GET, POSTMETHOD:

URI:https://<historianservername>:8443/historian-rest-api /v1/datapoints/trend

GET

https://<historianservername>:8443/historian-rest-api /v1/datapoints/trend

POST

https://<historianservername>:8443/historian-rest-api/v1/datapoints/trend?tagNames=tagName1&start=2013-10-

SAMPLE GET URI:

02T11:30:00.111Z&end=2013-10-02T11:31:11.111Z&samplingMode=1&calculationMode=1&direction=0&count=0&intervalMs=1000

https://<historianservername>:8443/historian-rest-api/v1/datapoints/trend

SAMPLE POST URI:



api/v1/ datapoints/trend/<tagName>/<start time>/<endtime>/<samplingMode>/<calculationMode>/<direction>/<count>/<intervalMS>




<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>:8443/historian-rest-api/v1/datapoints/trend

Query Parameters



TagNames


Start


End

Integer, with a value such as 1.OptionalAlso known asSamplingModeType.

SamplingMode

Integer, with a value such as 1.OptionalAlso known asCalculationModeType.

CalculationMode

Integer, with a value such as 0.OptionalSpecifies the direction(Forward or Backward from

Direction


Integer, with a value such as 0.OptionalThe count of archive valueswithin each calculationinterval.

Count


OptionalInterval in milliseconds.IntervalMS

Response Parameters







YesStringData

Name of the tag, such asahistfile.Simulation00001.

TagName

Location where tags are beingsearched for.

TagSource

Float, which stores decimal valuesup to 6 places.

DataType


Trend

example, TimeStamp =2016-03-15T04:53:17.000Z, Value= 170903.6563, andQuality = True.

Sample Response

{"ErrorCode": 0,"ErrorMessage": null,"Data": {"TagName": "ahistfile.Simulation00001","TagSource": "localhost","DataType": "Float","Trend":[

{"Timestamp":"2016-03-15T04:53:17.000Z","Value":"170903.6563","Quality":true}]}}

Add Single Tag APIThe Add Single Tag API provides the ability to add a new tag to Historian.

For the Add Single Tag API, you can add a new tag to Historian, and the tag name and data type must beprovided in the payload (parameter) of the method. All other tags are optional. If a property is provided, therespective validation is performed at the server end. If the tag exists, then any new properties provided inthe payload are applied to the existing tag.

POSTMETHOD:

https://<historianservername>:8443/historian-rest-api/v1/tags/addtag

URI:


https://<historianservername>:8443/historian-rest-api/v1/tags/addtagSAMPLE DELETEURI:

Payload:

{"Name" : "SampleTag","DataType" : 3

}

curl -i -H "Accept: application/json" -i -H "Content-Type:application/json" -H "Authorization: Bearer <TOKEN>” -d “{

SAMPLE cURLCOMMAND:

\”Name\”:\”Sampletag\”,\"DataType\":3}” -X POSThttps://<historianservername>:8443/historian-rest-api/v1/tags/addtag

Query Parameters


Multidata types. See PayloadParameter on page 19 for a list of

Yes. "Name" and"DataType" properties

JSONarrayof PropertyNameand PropertyValue.

Payload

tag properties used to update atag configuration.

are required. All otherproperties are optional.

Response Parameters




Sample Payload

{"Name" : "tag1","DataType" : 3 ,"Id": "F34CFE80-7428-41A1-AC67-DB0F3D2E1146"}

Sample Response

{"ErrorCode": 0,"ErrorMessage": null}

Add Bulk Tags APIThe Add Bulk Tags API provides the ability to add new tags to Historian using an array.


For the Add Bulk Tags API, you can add new tags to Historian using an array, and the tag names and datatypes must be provided in the payload (parameter) of the method. All other tags are optional. If a propertyis provided, the respective validation is performed at the server end. If the tags exist, then any newpropertiesprovided in the payload are applied to the existing tags. The payload is be an array of tags defined.

POSTMETHOD:

https://<historianservername>:8443/historian-rest-api/v1/tags/addtags

URI:

https://<historianservername>:8443/historian-rest-api/v1/tags/addtagsSAMPLE DELETEURI:

Payload:

[{

"Name" : "SampleTag1","DataType" : 3

},{

"Name" : "SampleTag2","DataType" : 3

}]

curl -i -H "Accept: application/json" -i -H "Content-Type:application/json" -H "Authorization: Bearer <TOKEN>” -d “[{

SAMPLE cURLCOMMAND:

\”Name\”:\”Sampletag1\”}, { \”Name\”:\”Sampletag2\”}]” -XPOST https://<historianservername>:8443/historian-rest-api/v1/tags/addtags

Query Parameters


Multidata types. See PayloadParameter on page 19 for a list of

Yes. "Name" and"DataType" properties

JSON array tags withindividual tags of

Payload

tag properties used to update atag configuration.

are required. All otherproperties are optional.

PropertyName andPropertyValue.

Response Parameters

DescriptionExists?Data TypeParameter

Tag name.YesStringTagName



Sample Payload

[{"Name": "tag1",


"Description": 1},{"Name": "tag2","DataType": 3,"Description": 3

}]

Sample Response

[{"TagName": "Tag1","ErrorCode": 10,"ErrorMessage": "Fail to validate the tag Tag1 error is 'Invalid data

type'"},{"TagName": "Tag2","ErrorCode": 0,"ErrorMessage": ""

}]

Update Tag Configuration APIYou can use this API to update tag properties.

The Update Tag Configuration API allows you to set or modify any tag property values.

A Rename cannot be done using the Update Tag Configuration properties.

PUTMETHOD:

https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName

URI:

https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagNameSAMPLE DELETEURI:

Payload:{

"PropertyName" : "PropertyValue"}


SAMPLE cURLCOMMAND:

\”Description\”:\”SampleDesc\”}” -X PUT https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName


Query Parameters


StringYesTag name for whichproperties need to be set ormodified.

tagName

Multidata types. See Payload Parameter onpage 19 for a list of tag properties used toupdate a tag configuration.

At least onepropertymust beprovided.

JSON array of PropertyNameand PropertyValue.

Payload

Response Parameters




Sample Payload

{"Description" : "Test desc"."CollectionOffset" : 4294967295}

Sample Response

{"ErrorCode": 0,"ErrorMessage": null}

Get Tag Properties APIUse the Get Tags API to retrieve existing tag properties.

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 tagname returns an error.

GET / POSTMETHOD:


This URI returns all tag properties.

URI: (GET)



Payload

URI: (POST)

{"PropertyName1" : 1,"PropertyName2" : 1}


SAMPLE GET URI:

https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagNameSAMPLE POST URI:

Payload:{

"Description" : 1}

curl -i -H "Accept: application/json" -i -H "Content-Type:application/json" -H "Authorization: Bearer <TOKEN>” -X GET

SAMPLE cURL GETCOMMAND:



SAMPLEcURLPOSTCOMMAND:

\”Description\”: 1}” -X POST https://<historianservername>:8443/historian-rest-api/v1/tags/properties/tagName

Query Parameters


StringYesTag name for whichproperties need to beretrieved.

tagName

Multi data types. See Payload Parameteron page 19 for a list of tag properties usedto update a tag configuration.

At least onepropertymust beprovided.

JSON array of PropertyNameand bool (true/false).

Payload

Note: The query payload contains all the tag properties you want returned from the server. In theUpdate Tag Config method, you need to provide the actual tag property value. However, in the Get TagProperties method, you need to provide the property and a value of 1 (true), to allow it to be read fromthe server and returned.


Response Parameters




If no error, then the tag name of query isreturned and all requested parameters.

OptionalStringName

The response always includes these parameters.

Sample Response

{“ErrorCode” : 0,“ErrorMessage” : NULL,"Name": "AnilGH7-1.Simulation00001","Description": "AnilGH7-1.Simulation00001","EngineeringUnits": null,"Comment": null,"CollectorName": "ANILGH7-1_Simulation","SourceAddress": "Simulation00001","CollectionType": 2,"DataType": 2,"FixedStringLength": 8,"CollectionInterval": 1000,"CollectionOffset": 0,"LoadBalancing": false,"TimeStampType": 2,"HiEngineeringUnits": 200000,"LoEngineeringUnits": 0,"InputScaling": true,"HiScale": 32767,"LoScale": 0,"CollectorCompression": false,"CollectorDeadbandPercentRange": 0,"ArchiveCompression": false,"ArchiveDeadbandPercentRange": 0,"General1": null,"General2": null,"General3": null,"General4": null,"General5": null,"ReadSecurityGroup": null,"WriteSecurityGroup": null,"AdministratorSecurityGroup": null,"LastModified": "2016-08-31T10:34:37.749Z","LastModifiedUser": "\\admin","CollectorType": 2,"UTCBias": 0,"CalculationDependencies": [],"CollectionDisabled": false,"ArchiveCompressionTimeout": 0,"CollectorCompressionTimeout": 0,"SpikeLogic": true,"SpikeLogicOverride": false,"CollectorAbsoluteDeadbanding": false,"CollectorAbsoluteDeadband": 0,


"ArchiveAbsoluteDeadbanding": false,"ArchiveAbsoluteDeadband": 0,"StepValue": false,"TimeResolution": 0,"ConditionCollectionEnabled": false,"ConditionCollectionTriggerTag": null,"ConditionCollectionComparison": 1,"ConditionCollectionCompareValue": null,"ConditionCollectionMarkers": true,"Calculation": "Simulation00001","Id": "A4FD6A00-BE45-463F-93C9-F287F3220B31","EnumeratedSetName": null,"DataStoreName": "User","DefaultQueryModifiers": 0,"UserDefinedTypeName": null,"NumberOfElements": 0,"DataDensity": 4,"CalcType": 0,"HasAlias": false,"IsStale": false

}

The response always includes the Name field. The Calculation property is returned only when the tagsinterface type is 9 (S2S Collector type) tag.

Delete Tag APIThis API allows a user to remove an existing tag from the Historian server.

The Delete Tag API provides the ability to delete an existing tag from the Historian server.

Its URI format supports question marks (?).

DELETEMETHOD:

https://<historianservername>:8443/historian-rest-api/v1/tags/tagName?{permanentDelete}

URI:

https://<historianservername>:8443/historian-rest-api/v1/tags/tagName?permanentDelete=true

SAMPLE DELETEURI:

curl -i -H "Authorization: Bearer <TOKEN>” -X DELETE https://<historianservername>:8443/historian-rest-api/v1/tags/tagName?permanentDelete=<true|false>

SAMPLE cURLCOMMAND:

Query Parameters


StringYesNameof the tag to be deleted.tagName

Boolean, true or falseOptional(false isdefault)

Deletes the tag permanentlyfrom theHistorian server if thevalue passed in is true. If theparameter is not provided,

permanentDelete



then permanentDelete isassumed to be false.

Response Parameters


For example, ErrorCode=0, which means theoperation was successful.

YesNumberErrorCode


Sample Response

{"ErrorCode": 0,"ErrorMessage": null,}


historianrestapis - software documentation | ge...

Documents