Read

  • Reads the value, quality and timestamp of one or more items.

  • Required security permission - READ.

  • HTTP methods supported: GET, POST.

  • Implements a query mechanism to fetch the path of the connector, core, parent or system object.

Read Actual Values & Properties

Read endpoint returns object value, quality and timestamp of one or more items, or item properties.

Parameters

Name Type Optional Description

identifier

string

no

Item or property path.

fields

string

yes

Comma separated string to customize which fields should be included in the response, by default 'i,p,v,q,t'. Provide 'ALL' to include all fields.

Field Description

i

object ID

p

path

v

value

q

quality mask

qtxt

quality text

qs

quality status (0=good, 1=uncertain, 2= bad)

qstxt

quality status text (good, uncertain, bad)

Examples

Read actual value

Example to read the actual value of one or multiple objects. The read an actual value the provided item path can either be the object path or path of the dynamic property, like ItemValue.

HTTP GET
Request URL

  • Single - /api/v2/read?identifier=/System/Core/Examples/Demo Data/Process Data/DC4711

Response body

  • Single

{
    "data": [
        {
            "p": "/System/Core/Examples/Demo Data/Process Data/DC4711",
            "v": 10,
            "q": 0,
            "t": "2019-01-01T12:00:00.000Z"
        }
    ]
}

  • Multiple

{
    "data": [
        {
            "p": "/System/Core/Examples/Demo Data/Process Data/DC4711",
            "v": 10,
            "q": 0,
            "t": "2019-01-01T12:00:00.000Z"
        },
        {
            "p": "/System/Core/Examples/Demo Data/Process Data/DC666",
            "v": 20,
            "q": 0,
            "t": "2019-01-01T12:00:00.000Z"
        }
    ]
}
HTTP POST
Request URL

  • /api/v2/read

Request body
{
    "items": [
        {
            "p": "/System/Core/Examples/Demo Data/Process Data/DC4711"
        },
        {
            "p": "/System/Core/Examples/Demo Data/Process Data/DC666"
        }
    ]
}
Response body
{
    "data": [
        {
            "p": "/System/Core/Examples/Demo Data/Process Data/DC4711",
            "v": 10,
            "q": 0,
            "t": "2019-01-01T12:00:00.000Z"
        },
            {
            "p": "/System/Core/Examples/Demo Data/Process Data/DC666",
            "v": 20,
            "q": 0,
            "t": "2019-01-01T12:00:00.000Z"
        }
    ]
}

Read object properties

This example shows how to read object properties, such as description or engineering unit. Each object property has a unique path, an example of the property ObjectDescription of an item is System/Core/Examples/Demo Data/Process Data/DC4711.ObjectDescription.

HTTP GET
Request URL

  • /api/v2/read?identifier=/System/Core/Examples/Demo Data/Process Data/DC4711.ObjectDescription&identifier=/System/Core/Examples/Demo Data/Process Data/DC666.OpcEngUnit

Response body
{
    "data": [
        {
            "i": 281474986016792,
            "p": "/System/Core/Examples/Demo Data/Process Data/DC4711.ObjectDescription",
            "q": 0,
            "t": "2018-09-10T12:15:14.724Z",
            "v": "Simulated Density"
        },
        {
            "i": 281474986213403,
            "p": "/System/Core/Examples/Demo Data/Process Data/DC666.OpcEngUnit",
            "q": 0,
            "t": "2018-09-10T12:15:14.739Z",
            "v": "g/cm³"
        }
    ]
}
HTTP POST
Request URL

  • /api/v2/read

Request body
{
    "items": [
        {
            "p": "/System/Core/Examples/Demo Data/Process Data/DC4711.ObjectDescription"
        },
        {
            "p": "/System/Core/Examples/Demo Data/Process Data/DC666.OpcEngUnit"
        }
    ]
}
Response body
{
    "data": [
        {
            "i": 281474986016792,
            "p": "/System/Core/Examples/Demo Data/Process Data/DC4711.ObjectDescription",
            "q": 0,
            "t": "2018-09-10T12:15:14.724Z",
            "v": "Simulated Density"
        },
        {
            "i": 281474986213403,
            "p": "/System/Core/Examples/Demo Data/Process Data/DC666.OpcEngUnit",
            "q": 0,
            "t": "2018-09-10T12:15:14.739Z",
            "v": "g/cm³"
        }
    ]
}

Failed read request

This example shows the response of a failed read request due to incorrect object path. The HTTP status code of the response is in this example 200 (OK). Response contains an error message and object path.

HTTP GET
Request URL

  • /api/v2/read?identifier=/System/Core/Examples/Demo Data/Process Data/DC000

Response body
{
    "data": [
        {
            "error": {
                "msg": "Object could not be resolved."
            },
            "p": "/System/Core/Examples/Demo Data/Process Data/DC000"
        }
    ]
}

Queries

The Read endpoint implements a query mechanism to be able to fetch data other than actual values or properties. Each item in the request can have one query defined in the query field q of the options opt field.

{
    "items": [
        {
            "p": "/System/Core/Examples/Demo Data/Process Data/DC4711",
            "opt": {
                "q": "COREPATH"
            }
        }
    ]
}

Supported queries are:

Read Connector path

The query CONNECTORPATH can be used to fetch the path of the connector to which the given item belongs or null if no connector was found in the parent objects hierarchy.

The Web API user must have READ permission on the provided item and LIST permission on the returned connector path.

Request

The request body must have the structure as described in the Queries section.

Response

The endpoint response structure is the same as the default read response. The value (v) field contains the path of the connector object. The timestamp (t) field contains the UTC time when the query got executed. The quality (q) field will have the value 0.

Read Core Path

The query COREPATH can be used to fetch the path of the core to which the given item belongs.

The Web API user must have READ permission on the provided item and LIST permission on the returned core path.

Request

The request body must have the structure as described in the Queries section.

Response

The endpoint response structure is the same as the default read response. The value (v) field contains the path of the core object. The timestamp (t) field contains the UTC time when the query got executed. The quality (q) field will have the value 0.

Read Parent Path

The query PARENTPATH can be used to fetch the path of the parent of the given item.

The Web API user must have READ permission on the provided item and LIST permission on the returned parent path.

Request

The request body must have the structure as described in the Queries section.

Response

The endpoint response structure is the same as the default read response. The value (v) field contains the parent path. The timestamp (t) field contains the UTC time when the query got executed. The quality (q) field will have the value 0.

Read System Path

The query SYSTEMPATH can be used to fetch the path of the system to which the given object belongs.

The Web API user must have READ permission on the provided item and LIST permission on the returned system path.

Request

The request body must have the structure as described in the Queries section.

Response

The endpoint response structure is the same as the default read response. The value (v) field contains the path of the system object. The timestamp (t) field contains the UTC time when the query got executed. The quality (q) field will have the value 0.