AWS IoT SiteWise

(1)

AWS IoT SiteWise

API Reference

API Version 2019-12-02

(2)

AWS IoT SiteWise: API Reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Welcome

Welcome to the AWS IoT SiteWise API Reference. AWS IoT SiteWise is an AWS service that connects Industrial Internet of Things (IIoT) devices to the power of the AWS Cloud. For more information, see the AWS IoT SiteWise User Guide. For information about AWS IoT SiteWise quotas, see Quotas in the AWS IoT SiteWise User Guide.

This document was last published on March 6, 2022.

(18)

Actions

The following actions are supported:

• AssociateAssets (p. 4)

• AssociateTimeSeriesToAssetProperty (p. 7)

• BatchAssociateProjectAssets (p. 10)

• BatchDisassociateProjectAssets (p. 13)

• BatchPutAssetPropertyValue (p. 16)

• CreateAccessPolicy (p. 20)

• CreateAsset (p. 24)

• CreateAssetModel (p. 28)

• CreateDashboard (p. 35)

• CreateGateway (p. 39)

• CreatePortal (p. 42)

• CreateProject (p. 47)

• DeleteAccessPolicy (p. 51)

• DeleteAsset (p. 53)

• DeleteAssetModel (p. 56)

• DeleteDashboard (p. 59)

• DeleteGateway (p. 61)

• DeletePortal (p. 63)

• DeleteProject (p. 66)

• DeleteTimeSeries (p. 68)

• DescribeAccessPolicy (p. 71)

• DescribeAsset (p. 74)

• DescribeAssetModel (p. 78)

• DescribeAssetProperty (p. 84)

• DescribeDashboard (p. 89)

• DescribeDefaultEncryptionConﬁguration (p. 92)

• DescribeGateway (p. 94)

• DescribeGatewayCapabilityConﬁguration (p. 97)

• DescribeLoggingOptions (p. 100)

• DescribePortal (p. 102)

• DescribeProject (p. 107)

• DescribeStorageConﬁguration (p. 110)

• DescribeTimeSeries (p. 113)

• DisassociateAssets (p. 117)

• DisassociateTimeSeriesFromAssetProperty (p. 120)

• GetAssetPropertyAggregates (p. 123)

• GetAssetPropertyValue (p. 127)

• GetAssetPropertyValueHistory (p. 130)

• GetInterpolatedAssetPropertyValues (p. 134)

• ListAccessPolicies (p. 140)

(19)

• ListAssetModels (p. 143)

• ListAssetRelationships (p. 146)

• ListAssets (p. 149)

• ListAssociatedAssets (p. 152)

• ListDashboards (p. 156)

• ListGateways (p. 159)

• ListPortals (p. 162)

• ListProjectAssets (p. 165)

• ListProjects (p. 168)

• ListTagsForResource (p. 171)

• ListTimeSeries (p. 174)

• PutDefaultEncryptionConﬁguration (p. 177)

• PutLoggingOptions (p. 180)

• PutStorageConﬁguration (p. 182)

• TagResource (p. 186)

• UntagResource (p. 189)

• UpdateAccessPolicy (p. 191)

• UpdateAsset (p. 194)

• UpdateAssetModel (p. 197)

• UpdateAssetProperty (p. 203)

• UpdateDashboard (p. 206)

• UpdateGateway (p. 209)

• UpdateGatewayCapabilityConﬁguration (p. 211)

• UpdatePortal (p. 214)

• UpdateProject (p. 218)

(20)

AssociateAssets

Associates a child asset with the given parent asset through a hierarchy deﬁned in the parent asset's model. For more information, see Associating assets in the AWS IoT SiteWise User Guide.

Request Syntax

POST /assets/assetId/associate HTTP/1.1 Content-type: application/json

{ "childAssetId": "string", "clientToken": "string", "hierarchyId": "string"

}

URI Request Parameters

The request uses the following URI parameters.

assetId (p. 4)

The ID of the parent asset.

Length Constraints: Fixed length of 36.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Required: Yes

Request Body

The request accepts the following data in JSON format.

childAssetId (p. 4)

The ID of the child asset to be associated.

Type: String

Required: Yes clientToken (p. 4)

A unique case-sensitive identiﬁer that you can provide to ensure the idempotency of the request.

Don't reuse this client token if a new idempotent request is required.

Type: String

Length Constraints: Minimum length of 36. Maximum length of 64.

Pattern: \S{36,64}

(21)

Response Syntax

Required: No hierarchyId (p. 4)

The ID of a hierarchy in the parent asset's model. Hierarchies allow diﬀerent groupings of assets to be formed that all come from the same asset model. For more information, see Asset hierarchies in the AWS IoT SiteWise User Guide.

Type: String

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements

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

Errors

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

ConﬂictingOperationException

Your request has conﬂicting operations. This can occur if you're trying to perform more than one operation on the same resource at the same time.

HTTP Status Code: 409 InternalFailureException

AWS IoT SiteWise can't process your request right now. Try again later.

HTTP Status Code: 500 InvalidRequestException

The request isn't valid. This can occur if your request contains malformed JSON or unsupported characters. Check your request and try again.

HTTP Status Code: 400 LimitExceededException

You've reached the limit for a resource. For example, this can occur if you're trying to associate more than the allowed number of child assets or attempting to create more than the allowed number of properties for an asset model.

For more information, see Quotas in the AWS IoT SiteWise User Guide.

HTTP Status Code: 410 ResourceNotFoundException

The requested resource can't be found.

(22)

See Also

HTTP Status Code: 404 ThrottlingException

Your request exceeded a rate limit. For example, you might have exceeded the number of AWS IoT SiteWise assets that can be created per second, the allowed number of messages per second, and so on.

HTTP Status Code: 429

AssociateTimeSeriesToAssetProperty

Associates a time series (data stream) with an asset property.

Request Syntax

POST /timeseries/associate/?alias=alias&assetId=assetId&propertyId=propertyId HTTP/1.1 Content-type: application/json

{

"clientToken": "string"

}

URI Request Parameters

alias (p. 7)

The alias that identiﬁes the time series.

Length Constraints: Minimum length of 1.

Pattern: [^\u0000-\u001F\u007F]+

Required: Yes assetId (p. 7)

The ID of the asset in which the asset property was created.

Required: Yes propertyId (p. 7)

The ID of the asset property.

Required: Yes

Request Body

clientToken (p. 7)

Type: String

(24)

Response Syntax

Pattern: \S{36,64}

Required: No

Response Syntax

HTTP/1.1 200

Response Elements

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

Errors

BatchAssociateProjectAssets

Associates a group (batch) of assets with an AWS IoT SiteWise Monitor project.

Request Syntax

POST /projects/projectId/assets/associate HTTP/1.1 Content-type: application/json

{

"assetIds": [ "string" ], "clientToken": "string"

}

URI Request Parameters

projectId (p. 10)

The ID of the project to which to associate the assets.

Required: Yes

Request Body

assetIds (p. 10)

The IDs of the assets to be associated to the project.

Type: Array of strings

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

Type: String

Pattern: \S{36,64}

(27)

Response Syntax

Required: No

Response Syntax

HTTP/1.1 200

Content-type: application/json {

"errors": [ {

"assetId": "string", "code": "string", "message": "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.

errors (p. 11)

A list of associated error information, if any.

Type: Array of AssetErrorDetails (p. 231) objects

Errors

InternalFailureException

(28)

See Also

BatchDisassociateProjectAssets

Disassociates a group (batch) of assets from an AWS IoT SiteWise Monitor project.

Request Syntax

POST /projects/projectId/assets/disassociate HTTP/1.1 Content-type: application/json

{

"assetIds": [ "string" ], "clientToken": "string"

}

URI Request Parameters

projectId (p. 13)

The ID of the project from which to disassociate the assets.

Required: Yes

Request Body

assetIds (p. 13)

The IDs of the assets to be disassociated from the project.

Type: Array of strings

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

Type: String

Pattern: \S{36,64}

(30)

Response Syntax

Required: No

Response Syntax

HTTP/1.1 200

"errors": [ {

"assetId": "string", "code": "string", "message": "string"

} ] }

Response Elements

errors (p. 14)

A list of associated error information, if any.

Type: Array of AssetErrorDetails (p. 231) objects

Errors

(31)

See Also

BatchPutAssetPropertyValue

Sends a list of asset property values to AWS IoT SiteWise. Each value is a timestamp-quality-value (TQV) data point. For more information, see Ingesting data using the API in the AWS IoT SiteWise User Guide.

To identify an asset property, you must specify one of the following:

• The assetId and propertyId of an asset property.

• A propertyAlias, which is a data stream alias (for example, /company/windfarm/3/turbine/7/

temperature). To deﬁne an asset property's alias, see UpdateAssetProperty.

Important

With respect to Unix epoch time, AWS IoT SiteWise accepts only TQVs that have a timestamp of no more than 7 days in the past and no more than 10 minutes in the future. AWS IoT SiteWise rejects timestamps outside of the inclusive range of [-7 days, +10 minutes] and returns a TimestampOutOfRangeException error.

For each asset property, AWS IoT SiteWise overwrites TQVs with duplicate timestamps unless the newer TQV has a diﬀerent quality. For example, if you store a TQV {T1, GOOD, V1}, then storing {T1, GOOD, V2} replaces the existing TQV.

AWS IoT SiteWise authorizes access to each BatchPutAssetPropertyValue entry individually. For more information, see BatchPutAssetPropertyValue authorization in the AWS IoT SiteWise User Guide.

Request Syntax

POST /properties HTTP/1.1 Content-type: application/json { "entries": [

{

"assetId": "string", "entryId": "string", "propertyAlias": "string", "propertyId": "string", "propertyValues": [ {

"quality": "string", "timestamp": {

"offsetInNanos": number, "timeInSeconds": number },

"value": {

"booleanValue": boolean, "doubleValue": number, "integerValue": number, "stringValue": "string"

} } ] } ]}

URI Request Parameters

The request does not use any URI parameters.

(33)

Request Body

entries (p. 16)

The list of asset property value entries for the batch put request. You can specify up to 10 entries per request.

Type: Array of PutAssetPropertyValueEntry (p. 303) objects Required: Yes

Response Syntax

HTTP/1.1 200

"errorEntries": [ {

"entryId": "string", "errors": [

{

"errorCode": "string", "errorMessage": "string", "timestamps": [

{

"offsetInNanos": number, "timeInSeconds": number }

] } ] } ] }

Response Elements

errorEntries (p. 17)

A list of the errors (if any) associated with the batch put request. Each error entry contains the entryId of the entry that failed.

Type: Array of BatchPutAssetPropertyErrorEntry (p. 258) objects

Errors

(34)

See Also

HTTP Status Code: 404 ServiceUnavailableException

The requested service is unavailable.

CreateAccessPolicy

Creates an access policy that grants the speciﬁed identity (AWS SSO user, AWS SSO group, or IAM user) access to the speciﬁed AWS IoT SiteWise Monitor portal or project resource.

Request Syntax

POST /access-policies HTTP/1.1 Content-type: application/json { "accessPolicyIdentity": { "group": {

"id": "string"

},

"iamRole": { "arn": "string"

},

"iamUser": { "arn": "string"

},

"user": { "id": "string"

} },

"accessPolicyPermission": "string", "accessPolicyResource": {

"portal": { "id": "string"

},

"project": { "id": "string"

} },

"clientToken": "string", "tags": {

"string" : "string"

}}

URI Request Parameters

Request Body

accessPolicyIdentity (p. 20)

The identity for this access policy. Choose an AWS SSO user, an AWS SSO group, or an IAM user.

Type: Identity (p. 278) object Required: Yes

accessPolicyPermission (p. 20)

The permission level for this access policy. Note that a project ADMINISTRATOR is also known as a project owner.

(37)

Response Syntax

Type: String

Valid Values: ADMINISTRATOR | VIEWER Required: Yes

accessPolicyResource (p. 20)

The AWS IoT SiteWise Monitor resource for this access policy. Choose either a portal or a project.

Type: Resource (p. 305) object Required: Yes

Type: String

Pattern: \S{36,64}

Required: No tags (p. 20)

A list of key-value pairs that contain metadata for the access policy. For more information, see Tagging your AWS IoT SiteWise resources in the AWS IoT SiteWise User Guide.

Type: String to string map

Map Entries: Maximum number of 50 items.

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

Value Length Constraints: Minimum length of 0. Maximum length of 256.

Required: No

Response Syntax

HTTP/1.1 201

Content-type: application/json { "accessPolicyArn": "string", "accessPolicyId": "string"

}

Response Elements

accessPolicyArn (p. 21)

The ARN of the access policy, which has the following format.

(38)

Errors

arn:${Partition}:iotsitewise:${Region}:${Account}:access-policy/

${AccessPolicyId}

Type: String

Pattern: .*

accessPolicyId (p. 21)

The ID of the access policy.

Type: String

Errors

(39)

See Also

CreateAsset

Creates an asset from an existing asset model. For more information, see Creating assets in the AWS IoT SiteWise User Guide.

Request Syntax

POST /assets HTTP/1.1

Content-type: application/json { "assetModelId": "string", "assetName": "string", "clientToken": "string", "tags": {

"string" : "string"

} }

URI Request Parameters

Request Body

assetModelId (p. 24)

The ID of the asset model from which to create the asset.

Type: String

Required: Yes assetName (p. 24)

A unique, friendly name for the asset.

Type: String

Pattern: [^\u0000-\u001F\u007F]+

Type: String

(41)

Response Syntax

Pattern: \S{36,64}

A list of key-value pairs that contain metadata for the asset. For more information, see Tagging your AWS IoT SiteWise resources in the AWS IoT SiteWise User Guide.

Required: No

Response Syntax

HTTP/1.1 202

Content-type: application/json { "assetArn": "string", "assetId": "string", "assetStatus": { "error": {

"code": "string", "details": [ {

"code": "string", "message": "string"

} ],

"message": "string"

},

"state": "string"

}}

Response Elements

assetArn (p. 25)

The ARN of the asset, which has the following format.

arn:${Partition}:iotsitewise:${Region}:${Account}:asset/${AssetId}

Type: String

Pattern: .*

(42)

Errors

assetId (p. 25)

The ID of the asset. This ID uniquely identiﬁes the asset within AWS IoT SiteWise and can be used with other AWS IoT SiteWise APIs.

Type: String

assetStatus (p. 25)

The status of the asset, which contains a state (CREATING after successfully calling this operation) and any error message.

Type: AssetStatus (p. 251) object

Errors

HTTP Status Code: 410 ResourceAlreadyExistsException

The resource already exists.

(43)

See Also

ThrottlingException

CreateAssetModel

Creates an asset model from specified property and hierarchy definitions. You create assets from asset models. With asset models, you can easily create assets of the same type that have standardized definitions. Each asset created from a model inherits the asset model's property and hierarchy

deﬁnitions. For more information, see Deﬁning asset models in the AWS IoT SiteWise User Guide.

Request Syntax

POST /asset-models HTTP/1.1 Content-type: application/json { "assetModelCompositeModels": [ {

"description": "string", "name": "string", "properties": [ {

"dataType": "string", "dataTypeSpec": "string", "name": "string",

"type": {

"attribute": {

"defaultValue": "string"

},

"measurement": {

"processingConfig": { "forwardingConfig": { "state": "string"

} } },

"metric": {

"expression": "string", "processingConfig": {

"computeLocation": "string"

},

"variables": [ {

"name": "string", "value": {

"hierarchyId": "string", "propertyId": "string"

} } ],

"window": { "tumbling": {

"interval": "string", "offset": "string"

} } },

"transform": {

"computeLocation": "string", "forwardingConfig": { "state": "string"

} },

(45)

Request Syntax

"variables": [ {

} } ] } },

"unit": "string"

} ],

"type": "string"

} ],

"assetModelDescription": "string", "assetModelHierarchies": [ {

"childAssetModelId": "string", "name": "string"

} ],

"assetModelName": "string", "assetModelProperties": [ {

"dataType": "string", "dataTypeSpec": "string", "name": "string",

"type": {

"attribute": {

"defaultValue": "string"

},

"measurement": {

"processingConfig": { "forwardingConfig": { "state": "string"

} } },

"metric": {

"computeLocation": "string"

},

"variables": [ {

} } ],

"window": { "tumbling": {

"interval": "string", "offset": "string"

} } },

"transform": {

"computeLocation": "string",

(46)

URI Request Parameters

"forwardingConfig": { "state": "string"

} },

"variables": [ {

} } ] } },

"unit": "string"

} ],

"clientToken": "string", "tags": {

"string" : "string"

}}

URI Request Parameters

Request Body

assetModelCompositeModels (p. 28)

The composite asset models that are part of this asset model. Composite asset models are asset models that contain specific properties. Each composite model has a type that defines the properties that the composite model supports. Use composite asset models to define alarms on this asset model.

Type: Array of AssetModelCompositeModelDeﬁnition (p. 236) objects Required: No

assetModelDescription (p. 28) A description for the asset model.

Type: String

Pattern: [^\u0000-\u001F\u007F]+

Required: No

assetModelHierarchies (p. 28)

The hierarchy deﬁnitions of the asset model. Each hierarchy speciﬁes an asset model whose assets can be children of any other assets created from this asset model. For more information, see Asset hierarchies in the AWS IoT SiteWise User Guide.

You can specify up to 10 hierarchies per asset model. For more information, see Quotas in the AWS IoT SiteWise User Guide.

(47)

Response Syntax

Type: Array of AssetModelHierarchyDeﬁnition (p. 239) objects Required: No

assetModelName (p. 28)

A unique, friendly name for the asset model.

Type: String

Pattern: [^\u0000-\u001F\u007F]+

Required: Yes

assetModelProperties (p. 28)

The property deﬁnitions of the asset model. For more information, see Asset properties in the AWS IoT SiteWise User Guide.

You can specify up to 200 properties per asset model. For more information, see Quotas in the AWS IoT SiteWise User Guide.

Type: Array of AssetModelPropertyDeﬁnition (p. 242) objects Required: No

Type: String

Pattern: \S{36,64}

A list of key-value pairs that contain metadata for the asset model. For more information, see Tagging your AWS IoT SiteWise resources in the AWS IoT SiteWise User Guide.

Required: No

Response Syntax

HTTP/1.1 202

(48)

Response Elements

"assetModelArn": "string", "assetModelId": "string", "assetModelStatus": { "error": {

"code": "string", "details": [ {

"code": "string", "message": "string"

} ],

"message": "string"

},

"state": "string"

}}

Response Elements

assetModelArn (p. 31)

The ARN of the asset model, which has the following format.

arn:${Partition}:iotsitewise:${Region}:${Account}:asset-model/

${AssetModelId}

Type: String

Pattern: .*

assetModelId (p. 31)

The ID of the asset model. You can use this ID when you call other AWS IoT SiteWise APIs.

Type: String

assetModelStatus (p. 31)

The status of the asset model, which contains a state (CREATING after successfully calling this operation) and any error message.

Type: AssetModelStatus (p. 244) object

Errors

(49)

See Also

HTTP Status Code: 410 ResourceAlreadyExistsException

The resource already exists.

CreateDashboard

Creates a dashboard in an AWS IoT SiteWise Monitor project.

Request Syntax

POST /dashboards HTTP/1.1 Content-type: application/json { "clientToken": "string",

"dashboardDefinition": "string", "dashboardDescription": "string", "dashboardName": "string", "projectId": "string", "tags": {

"string" : "string"

}}

URI Request Parameters

Request Body

Type: String

Pattern: \S{36,64}

Required: No

dashboardDeﬁnition (p. 35)

The dashboard deﬁnition speciﬁed in a JSON literal. For detailed information, see Creating dashboards (CLI) in the AWS IoT SiteWise User Guide.

Type: String

Pattern: .+

Required: Yes

dashboardDescription (p. 35) A description for the dashboard.

Type: String

(52)

Response Syntax

Pattern: [^\u0000-\u001F\u007F]+

Required: No dashboardName (p. 35)

A friendly name for the dashboard.

Type: String

Pattern: [^\u0000-\u001F\u007F]+

Required: Yes projectId (p. 35)

The ID of the project in which to create the dashboard.

Type: String

Required: Yes tags (p. 35)

A list of key-value pairs that contain metadata for the dashboard. For more information, see Tagging your AWS IoT SiteWise resources in the AWS IoT SiteWise User Guide.

Required: No

Response Syntax

HTTP/1.1 201

"dashboardArn": "string", "dashboardId": "string"

}

AWS IoT SiteWise

AWS IoT SiteWise

API Reference

API Version 2019-12-02

AWS IoT SiteWise: API Reference

Table of Contents

Welcome

Actions

AssociateAssets

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

AssociateTimeSeriesToAssetProperty

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

BatchAssociateProjectAssets

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

BatchDisassociateProjectAssets

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

BatchPutAssetPropertyValue

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateAccessPolicy

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateAsset

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateAssetModel

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateDashboard

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements