Read

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

  • Required security permission - READ.

  • HTTP methods supported: GET, POST.

Description

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 a single or multiple objects or object properties. Each object property has a unique path, an example of the property Object Name of a Generic Item path is System/Core/Examples/Demo Data/Process Data/DC4711.ObjectName. Property path is used the same way as a regular object path to read the property value.

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.

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"
        }
    ]
}