Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

GetPropertyValueHistory

Retrieves information about the history of a time series property value for a component, component type, entity, or workspace.

You must specify a value for workspaceId. For entity-specific queries, specify values for componentName and entityId. For cross-entity queries, specify a value for componentTypeId.

Request Syntax


POST /workspaces/workspaceId/entity-properties/history HTTP/1.1
Content-type: application/json

{
   "componentName": "string",
   "componentPath": "string",
   "componentTypeId": "string",
   "endDateTime": number,
   "endTime": "string",
   "entityId": "string",
   "interpolation": { 
      "interpolationType": "string",
      "intervalInSeconds": number
   },
   "maxResults": number,
   "nextToken": "string",
   "orderByTime": "string",
   "propertyFilters": [ 
      { 
         "operator": "string",
         "propertyName": "string",
         "value": { 
            "booleanValue": boolean,
            "doubleValue": number,
            "expression": "string",
            "integerValue": number,
            "listValue": [ 
               "DataValue"
            ],
            "longValue": number,
            "mapValue": { 
               "string" : "DataValue"
            },
            "relationshipValue": { 
               "targetComponentName": "string",
               "targetEntityId": "string"
            },
            "stringValue": "string"
         }
      }
   ],
   "selectedProperties": [ "string" ],
   "startDateTime": number,
   "startTime": "string"
}

URI Request Parameters

The request uses the following URI parameters.

workspaceId

The ID of the workspace.

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z_0-9][a-zA-Z_\-0-9]*[a-zA-Z0-9]+

Required: Yes

Request Body

The request accepts the following data in JSON format.

componentName

The name of the component.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: [a-zA-Z_\-0-9]+

Required: No

componentPath

This string specifies the path to the composite component, starting from the top-level component.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: [a-zA-Z_\-0-9/]+

Required: No

componentTypeId

The ID of the component type.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: [a-zA-Z_\.\-0-9:]+

Required: No

endDateTime

This parameter has been deprecated.

The date and time of the latest property value to return.

Type: Timestamp

Required: No

endTime

The ISO8601 DateTime of the latest property value to return.

For more information about the ISO8601 DateTime format, see the data type PropertyValue.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 35.

Required: No

entityId

The ID of the entity.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|^[a-zA-Z0-9][a-zA-Z_\-0-9.:]*[a-zA-Z0-9]+

Required: No

interpolation

An object that specifies the interpolation type and the interval over which to interpolate data.

Type: InterpolationParameters object

Required: No

maxResults

The maximum number of results to return at one time. The default is 25.

Valid Range: Minimum value of 1. Maximum value of 250.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 200.

Required: No

nextToken

The string that specifies the next page of results.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 17880.

Pattern: .*

Required: No

orderByTime

The time direction to use in the result order.

Type: String

Valid Values: ASCENDING | DESCENDING

Required: No

propertyFilters

A list of objects that filter the property value history request.

Type: Array of PropertyFilter objects

Array Members: Minimum number of 1 item. Maximum number of 10 items.

Required: No

selectedProperties

A list of properties whose value histories the request retrieves.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 10 items.

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: .*

Required: Yes

startDateTime

This parameter has been deprecated.

The date and time of the earliest property value to return.

Type: Timestamp

Required: No

startTime

The ISO8601 DateTime of the earliest property value to return.

For more information about the ISO8601 DateTime format, see the data type PropertyValue.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 35.

Required: No

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "nextToken": "string",
   "propertyValues": [ 
      { 
         "entityPropertyReference": { 
            "componentName": "string",
            "componentPath": "string",
            "entityId": "string",
            "externalIdProperty": { 
               "string" : "string" 
            },
            "propertyName": "string"
         },
         "values": [ 
            { 
               "time": "string",
               "timestamp": number,
               "value": { 
                  "booleanValue": boolean,
                  "doubleValue": number,
                  "expression": "string",
                  "integerValue": number,
                  "listValue": [ 
                     "DataValue"
                  ],
                  "longValue": number,
                  "mapValue": { 
                     "string" : "DataValue"
                  },
                  "relationshipValue": { 
                     "targetComponentName": "string",
                     "targetEntityId": "string"
                  },
                  "stringValue": "string"
               }
            }
         ]
      }
   ]
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

nextToken

The string that specifies the next page of results.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 17880.

Pattern: .*

propertyValues

An object that maps strings to the property definitions in the component type. Each string in the mapping must be unique to this object.

Type: Array of PropertyValueHistory objects

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

Access is denied.

HTTP Status Code: 403

ConnectorFailureException

The connector failed.

HTTP Status Code: 424

ConnectorTimeoutException

The connector timed out.

HTTP Status Code: 424

InternalServerException

An unexpected error has occurred.

HTTP Status Code: 500

ResourceNotFoundException

The resource wasn't found.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 429

ValidationException

Failed

HTTP Status Code: 400