AWS IoT Things Graph

(1)

AWS IoT Things Graph

API Reference

API Version 2018-09-06

(2)

AWS IoT Things Graph: 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

AWS IoT Things Graph provides an integrated set of tools that enable developers to connect devices and services that use diﬀerent standards, such as units of measure and communication protocols. AWS IoT Things Graph makes it possible to build IoT applications with little to no code by connecting devices and services and deﬁning how they interact at an abstract level.

For more information about how AWS IoT Things Graph works, see the User Guide.

This document was last published on March 6, 2022.

API Version 2018-09-06 1

(10)

Actions

The following actions are supported:

• AssociateEntityToThing (p. 3)

• CreateFlowTemplate (p. 5)

• CreateSystemInstance (p. 7)

• CreateSystemTemplate (p. 11)

• DeleteFlowTemplate (p. 13)

• DeleteNamespace (p. 15)

• DeleteSystemInstance (p. 17)

• DeleteSystemTemplate (p. 19)

• DeploySystemInstance (p. 21)

• DeprecateFlowTemplate (p. 24)

• DeprecateSystemTemplate (p. 26)

• DescribeNamespace (p. 28)

• DissociateEntityFromThing (p. 31)

• GetEntities (p. 33)

• GetFlowTemplate (p. 36)

• GetFlowTemplateRevisions (p. 38)

• GetNamespaceDeletionStatus (p. 41)

• GetSystemInstance (p. 43)

• GetSystemTemplate (p. 46)

• GetSystemTemplateRevisions (p. 48)

• GetUploadStatus (p. 51)

• ListFlowExecutionMessages (p. 54)

• ListTagsForResource (p. 57)

• SearchEntities (p. 60)

• SearchFlowExecutions (p. 63)

• SearchFlowTemplates (p. 66)

• SearchSystemInstances (p. 69)

• SearchSystemTemplates (p. 72)

• SearchThings (p. 75)

• TagResource (p. 78)

• UndeploySystemInstance (p. 80)

• UntagResource (p. 82)

• UpdateFlowTemplate (p. 84)

• UpdateSystemTemplate (p. 87)

• UploadEntityDeﬁnitions (p. 90)

(11)

AssociateEntityToThing

Associates a device with a concrete thing that is in the user's registry.

A thing can be associated with only one device at a time. If you associate a thing with a new device id, its previous association will be removed.

Request Syntax

{

"entityId": "string", "namespaceVersion": number, "thingName": "string"

}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters (p. 116).

The request accepts the following data in JSON format.

entityId (p. 3)

The ID of the device to be associated with the thing.

The ID should be in the following format.

urn:tdm:REGION/ACCOUNT ID/default:device:DEVICENAME Type: String

Length Constraints: Maximum length of 160.

Pattern: ^urn:tdm:(([a-z]{2}-(gov-)?[a-z]{4,9}-[0-9]{1,3}/

[0-9]+/)*[\p{Alnum}_]+(/[\p{Alnum}_]+)*):([\p{Alpha}]*):([\p{Alnum}_]+(/

[\p{Alnum}_]+)*)$

Required: Yes namespaceVersion (p. 3)

The version of the user's namespace. Defaults to the latest version of the user's namespace.

Type: Long Required: No thingName (p. 3)

The name of the thing to which the entity is to be associated.

Type: String

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

Pattern: [a-zA-Z0-9:_-]+

Required: Yes

(12)

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. 118).

InternalFailureException

HTTP Status Code: 500 InvalidRequestException

HTTP Status Code: 400 ResourceNotFoundException

HTTP Status Code: 400 ThrottlingException

HTTP Status Code: 400

CreateFlowTemplate

Creates a workflow template. Workflows can be created only in the user's namespace. (The public namespace contains only entities.) The workflow can contain only entities in the specified namespace.

The workﬂow is validated against the entities in the latest version of the user's namespace unless another namespace version is speciﬁed in the request.

Request Syntax

{ "compatibleNamespaceVersion": number, "definition": {

"language": "string", "text": "string"

}}

Request Parameters

compatibleNamespaceVersion (p. 5)

The namespace version in which the workﬂow is to be created.

If no value is speciﬁed, the latest version is used by default.

Type: Long Required: No deﬁnition (p. 5)

The workﬂow DefinitionDocument.

Type: DeﬁnitionDocument (p. 94) object Required: Yes

Response Syntax

{

"summary": { "arn": "string", "createdAt": number, "id": "string",

"revisionNumber": number }}

Response Elements

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

(14)

Errors

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

summary (p. 5)

The summary object that describes the created workﬂow.

Type: FlowTemplateSummary (p. 104) object

Errors

HTTP Status Code: 400 LimitExceededException

HTTP Status Code: 400 ResourceAlreadyExistsException

CreateSystemInstance

Creates a system instance.

This action validates the system instance, prepares the deployment-related resources. For Greengrass deployments, it updates the Greengrass group that is specified by the greengrassGroupName parameter. It also adds a file to the S3 bucket specified by the s3BucketName parameter. You need to call DeploySystemInstance after running this action.

For Greengrass deployments, since this action modiﬁes and adds resources to a Greengrass group and an S3 bucket on the caller's behalf, the calling identity must have write permissions to both the speciﬁed Greengrass group and S3 bucket. Otherwise, the call will fail with an authorization error.

For cloud deployments, this action requires a flowActionsRoleArn value. This is an IAM role that has permissions to access AWS services, such as AWS Lambda and AWS IoT, that the ﬂow uses when it executes.

If the deﬁnition document doesn't specify a version of the user's namespace, the latest version will be used by default.

Request Syntax

{ "definition": {

},

"flowActionsRoleArn": "string", "greengrassGroupName": "string", "metricsConfiguration": { "cloudMetricEnabled": boolean, "metricRuleRoleArn": "string"

},

"s3BucketName": "string", "tags": [

{

"key": "string", "value": "string"

} ],

"target": "string"

}

Request Parameters

deﬁnition (p. 7)

A document that deﬁnes an entity.

(16)

Response Syntax

ﬂowActionsRoleArn (p. 7)

The ARN of the IAM role that AWS IoT Things Graph will assume when it executes the ﬂow. This role must have read and write access to AWS Lambda and AWS IoT and any other AWS services that the ﬂow uses when it executes. This value is required if the value of the target parameter is CLOUD.

Type: String

Required: No

greengrassGroupName (p. 7)

The name of the Greengrass group where the system instance will be deployed. This value is required if the value of the target parameter is GREENGRASS.

Type: String Required: No

metricsConﬁguration (p. 7)

An object that speciﬁes whether cloud metrics are collected in a deployment and, if so, what role is used to collect metrics.

Type: MetricsConﬁguration (p. 105) object Required: No

s3BucketName (p. 7)

The name of the Amazon Simple Storage Service bucket that will be used to store and deploy the system instance's resource ﬁle. This value is required if the value of the target parameter is GREENGRASS.

Type: String Required: No tags (p. 7)

Metadata, consisting of key-value pairs, that can be used to categorize your system instances.

Type: Array of Tag (p. 114) objects

Array Members: Minimum number of 0 items. Maximum number of 50 items.

Required: No target (p. 7)

The target type of the deployment. Valid values are GREENGRASS and CLOUD.

Type: String

Valid Values: GREENGRASS | CLOUD Required: Yes

Response Syntax

{

(17)

"summary": { "arn": "string", "createdAt": number,

"greengrassGroupId": "string", "greengrassGroupName": "string", "greengrassGroupVersionId": "string", "id": "string",

"status": "string", "target": "string", "updatedAt": number }

}

Response Elements

summary (p. 8)

The summary object that describes the new system instance.

Type: SystemInstanceSummary (p. 109) object

Errors

HTTP Status Code: 400 LimitExceededException

CreateSystemTemplate

Creates a system. The system is validated against the entities in the latest version of the user's namespace unless another namespace version is speciﬁed in the request.

Request Syntax

{ "compatibleNamespaceVersion": number, "definition": {

}}

Request Parameters

compatibleNamespaceVersion (p. 11)

The namespace version in which the system is to be created.

If no value is speciﬁed, the latest version is used by default.

Type: Long Required: No deﬁnition (p. 11)

The DefinitionDocument used to create the system.

Response Syntax

{

"revisionNumber": number }}

Response Elements

(20)

Errors

summary (p. 11)

The summary object that describes the created system.

Type: SystemTemplateSummary (p. 113) object

Errors

DeleteFlowTemplate

Deletes a workflow. Any new system or deployment that contains this workflow will fail to update or deploy. Existing deployments that contain the workflow will continue to run (since they use a snapshot of the workflow taken at the time of deployment).

Request Syntax

{ "id": "string"

}

Request Parameters

id (p. 13)

The ID of the workﬂow to be deleted.

urn:tdm:REGION/ACCOUNT ID/default:workflow:WORKFLOWNAME Type: String

[\p{Alnum}_]+)*)$

Required: Yes

Response Elements

Errors

HTTP Status Code: 400 ResourceInUseException

(22)

See Also

DeleteNamespace

Deletes the speciﬁed namespace. This action deletes all of the entities in the namespace. Delete the systems and ﬂows that use entities in the namespace before performing this action. This action takes no request parameters.

Response Syntax

{ "namespaceArn": "string", "namespaceName": "string"

}

Response Elements

namespaceArn (p. 15)

The ARN of the namespace to be deleted.

Type: String

namespaceName (p. 15)

The name of the namespace to be deleted.

Type: String

Errors

InternalFailureException HTTP Status Code: 500 ThrottlingException

DeleteSystemInstance

Deletes a system instance. Only system instances that have never been deployed, or that have been undeployed can be deleted.

Users can create a new system instance that has the same ID as a deleted system instance.

Request Syntax

{ "id": "string"

}

Request Parameters

id (p. 17)

The ID of the system instance to be deleted.

Type: String

[\p{Alnum}_]+)*)$

Required: Yes

Response Elements

Errors

(26)

See Also

ThrottlingException

DeleteSystemTemplate

Deletes a system. New deployments can't contain the system after its deletion. Existing deployments that contain the system will continue to work because they use a snapshot of the system that is taken when it is deployed.

Request Syntax

{ "id": "string"

}

Request Parameters

id (p. 19)

The ID of the system to be deleted.

urn:tdm:REGION/ACCOUNT ID/default:system:SYSTEMNAME Type: String

[\p{Alnum}_]+)*)$

Required: Yes

Response Elements

Errors

(28)

See Also

DeploySystemInstance

Greengrass and Cloud Deployments

Deploys the system instance to the target speciﬁed in CreateSystemInstance.

Greengrass Deployments

If the system or any workﬂows and entities have been updated before this action is called, then the deployment will create a new Amazon Simple Storage Service resource ﬁle and then deploy it.

Since this action creates a Greengrass deployment on the caller's behalf, the calling identity must have write permissions to the speciﬁed Greengrass group. Otherwise, the call will fail with an authorization error.

For information about the artifacts that get added to your Greengrass core device when you use this API, see AWS IoT Things Graph and AWS IoT Greengrass.

Request Syntax

{

"id": "string"

}

Request Parameters

id (p. 21)

The ID of the system instance. This value is returned by the CreateSystemInstance action.

urn:tdm:REGION/ACCOUNT ID/default:deployment:DEPLOYMENTNAME Type: String

[\p{Alnum}_]+)*)$

Required: Yes

Response Syntax

{ "greengrassDeploymentId": "string", "summary": {

"arn": "string",

(30)

Response Elements

"createdAt": number,

"status": "string", "target": "string", "updatedAt": number }

}

Response Elements

greengrassDeploymentId (p. 21)

The ID of the Greengrass deployment used to deploy the system instance.

Type: String summary (p. 21)

An object that contains summary information about a system instance that was deployed.

Type: SystemInstanceSummary (p. 109) object

Errors

DeprecateFlowTemplate

Deprecates the specified workflow. This action marks the workflow for deletion. Deprecated flows can't be deployed, but existing deployments will continue to run.

Request Syntax

{

"id": "string"

}

Request Parameters

id (p. 24)

The ID of the workﬂow to be deleted.

[\p{Alnum}_]+)*)$

Required: Yes

Response Elements

Errors

(33)

DeprecateSystemTemplate

Deprecates the speciﬁed system.

Request Syntax

{ "id": "string"

}

Request Parameters

id (p. 26)

The ID of the system to delete.

[\p{Alnum}_]+)*)$

Required: Yes

Response Elements

Errors

(35)

ThrottlingException

DescribeNamespace

Gets the latest version of the user's namespace and the public version that it is tracking.

Request Syntax

{

"namespaceName": "string"

}

Request Parameters

The name of the user's namespace. Set this to aws to get the public namespace.

Type: String

Required: No

Response Syntax

{

"namespaceArn": "string", "namespaceName": "string", "namespaceVersion": number, "trackingNamespaceName": "string", "trackingNamespaceVersion": number }

Response Elements

namespaceArn (p. 28)

The ARN of the namespace.

Type: String

The name of the namespace.

Type: String

(37)

namespaceVersion (p. 28)

The version of the user's namespace to describe.

Type: Long

trackingNamespaceName (p. 28)

The name of the public namespace that the latest namespace version is tracking.

Type: String

trackingNamespaceVersion (p. 28)

The version of the public namespace that the latest version is tracking.

Type: Long

Errors

DissociateEntityFromThing

Dissociates a device entity from a concrete thing. The action takes only the type of the entity that you need to dissociate because only one entity of a particular type can be associated with a thing.

Request Syntax

{

"entityType": "string", "thingName": "string"

}

Request Parameters

entityType (p. 31)

The entity type from which to disassociate the thing.

Type: String

Required: Yes thingName (p. 31)

The name of the thing to disassociate.

Type: String

Pattern: [a-zA-Z0-9:_-]+

Required: Yes

Response Elements

Errors

(40)

See Also

GetEntities

Gets deﬁnitions of the speciﬁed entities. Uses the latest version of the user's namespace by default. This API returns the following TDM entities.

• Properties

• States

• Events

• Actions

• Capabilities

• Mappings

• Devices

• Device Models

• Services

This action doesn't return deﬁnitions for systems, ﬂows, and deployments.

Request Syntax

{

"ids": [ "string" ], "namespaceVersion": number }

Request Parameters

ids (p. 33)

An array of entity IDs.

The IDs should be in the following format.

urn:tdm:REGION/ACCOUNT ID/default:device:DEVICENAME Type: Array of strings

[\p{Alnum}_]+)*)$

Required: Yes

Type: Long

(42)

Response Syntax

Required: No

Response Syntax

{ "descriptions": [ {

"arn": "string", "createdAt": number, "definition": {

},

"id": "string", "type": "string"

} ]}

Response Elements

descriptions (p. 34)

An array of descriptions for the speciﬁed entities.

Type: Array of EntityDescription (p. 96) objects

Errors

GetFlowTemplate

Gets the latest version of the DefinitionDocument and FlowTemplateSummary for the speciﬁed workﬂow.

Request Syntax

{ "id": "string",

"revisionNumber": number }

Request Parameters

id (p. 36)

The ID of the workﬂow.

[\p{Alnum}_]+)*)$

Required: Yes revisionNumber (p. 36)

The number of the workﬂow revision to retrieve.

Type: Long Required: No

Response Syntax

{ "description": { "definition": {

},

(45)

"revisionNumber": number },

"validatedNamespaceVersion": number }

}

Response Elements

description (p. 36)

The object that describes the speciﬁed workﬂow.

Type: FlowTemplateDescription (p. 102) object

Errors

GetFlowTemplateRevisions

Gets revisions of the specified workflow. Only the last 100 revisions are stored. If the workflow has been deprecated, this action will return revisions that occurred before the deprecation. This action won't work for workflows that have been deleted.

Request Syntax

{

"id": "string", "maxResults": number, "nextToken": "string"

}

Request Parameters

id (p. 38)

The ID of the workﬂow.

[\p{Alnum}_]+)*)$

Required: Yes maxResults (p. 38)

The maximum number of results to return in the response.

Type: Integer

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

Required: No nextToken (p. 38)

The string that speciﬁes the next page of results. Use this when you're paginating results.

(47)

Response Syntax

{

"nextToken": "string", "summaries": [ {

"arn": "string", "createdAt": number, "id": "string",

]}

Response Elements

nextToken (p. 39)

The string to specify as nextToken when you request the next page of results.

Type: String summaries (p. 39)

An array of objects that provide summary data about each revision.

Type: Array of FlowTemplateSummary (p. 104) objects

Errors

GetNamespaceDeletionStatus

Gets the status of a namespace deletion task.

Response Syntax

{ "errorCode": "string", "errorMessage": "string", "namespaceArn": "string", "namespaceName": "string", "status": "string"

}

Response Elements

errorCode (p. 41)

An error code returned by the namespace deletion task.

Type: String

Valid Values: VALIDATION_FAILED errorMessage (p. 41)

An error code returned by the namespace deletion task.

Type: String namespaceArn (p. 41)

The ARN of the namespace that is being deleted.

Type: String

The name of the namespace that is being deleted.

Type: String

status (p. 41)

The status of the deletion request.

Type: String

Valid Values: IN_PROGRESS | SUCCEEDED | FAILED

Errors

(50)

See Also

GetSystemInstance

Gets a system instance.

Request Syntax

{ "id": "string"

}

Request Parameters

id (p. 43)

The ID of the system deployment instance. This value is returned by CreateSystemInstance.

urn:tdm:REGION/ACCOUNT ID/default:deployment:DEPLOYMENTNAME Type: String

[\p{Alnum}_]+)*)$

Required: Yes

Response Syntax

{ "description": { "definition": {

},

"flowActionsRoleArn": "string", "metricsConfiguration": { "cloudMetricEnabled": boolean, "metricRuleRoleArn": "string"

},

"s3BucketName": "string", "summary": {

"arn": "string", "createdAt": number,

(52)

Response Elements

"status": "string", "target": "string", "updatedAt": number },

"validatedDependencyRevisions": [ {

"id": "string",

],

"validatedNamespaceVersion": number }}

Response Elements

An object that describes the system instance.

Type: SystemInstanceDescription (p. 106) object

Errors

GetSystemTemplate

Gets a system.

Request Syntax

{ "id": "string",

Request Parameters

id (p. 46)

The ID of the system to get. This ID must be in the user's namespace.

[\p{Alnum}_]+)*)$

Required: Yes revisionNumber (p. 46)

The number that speciﬁes the revision of the system to get.

Type: Long Required: No

Response Syntax

{

"description": { "definition": {

},

"revisionNumber": number

(55)

},

"validatedNamespaceVersion": number }}

Response Elements

An object that contains summary data about the system.

Type: SystemTemplateDescription (p. 111) object

Errors

GetSystemTemplateRevisions

Gets revisions made to the speciﬁed system template. Only the previous 100 revisions are stored. If the system has been deprecated, this action will return the revisions that occurred before its deprecation.

This action won't work with systems that have been deleted.

Request Syntax

{

"id": "string", "maxResults": number, "nextToken": "string"

}

Request Parameters

id (p. 48)

The ID of the system template.

[\p{Alnum}_]+)*)$

Required: Yes maxResults (p. 48)

Type: Integer

(57)

Response Syntax

{

"nextToken": "string", "summaries": [ {

"arn": "string", "createdAt": number, "id": "string",

]}

Response Elements

Type: String summaries (p. 49)

An array of objects that contain summary data about the system template revisions.

Type: Array of SystemTemplateSummary (p. 113) objects

Errors

GetUploadStatus

Gets the status of the speciﬁed upload.

Request Syntax

{ "uploadId": "string"

}

Request Parameters

uploadId (p. 51)

The ID of the upload. This value is returned by the UploadEntityDefinitions action.

Type: String

Required: Yes

Response Syntax

{ "createdDate": number,

"failureReason": [ "string" ], "namespaceArn": "string", "namespaceName": "string", "namespaceVersion": number, "uploadId": "string", "uploadStatus": "string"

}

Response Elements

createdDate (p. 51)

The date at which the upload was created.

Type: Timestamp failureReason (p. 51)

The reason for an upload failure.

Type: Array of strings

(60)

Errors

namespaceArn (p. 51) The ARN of the upload.

Type: String

The name of the upload's namespace.

Type: String

Type: Long uploadId (p. 51)

The ID of the upload.

Type: String

uploadStatus (p. 51)

The status of the upload. The initial status is IN_PROGRESS. The response show all validation failures if the upload fails.

Type: String

Valid Values: IN_PROGRESS | SUCCEEDED | FAILED

Errors

ListFlowExecutionMessages

Returns a list of objects that contain information about events in a ﬂow execution.

Request Syntax

{

"flowExecutionId": "string", "maxResults": number, "nextToken": "string"

}

Request Parameters

ﬂowExecutionId (p. 54)

The ID of the ﬂow execution.

Type: String Required: Yes maxResults (p. 54)

Type: Integer

Response Syntax

{ "messages": [ {

"eventType": "string", "messageId": "string", "payload": "string", "timestamp": number }

],

"nextToken": "string"

(63)

}

Response Elements

messages (p. 54)

A list of objects that contain information about events in the speciﬁed ﬂow execution.

Type: Array of FlowExecutionMessage (p. 99) objects nextToken (p. 54)

Type: String

Errors

ListTagsForResource

Lists all tags on an AWS IoT Things Graph resource.

Request Syntax

{

"maxResults": number, "nextToken": "string", "resourceArn": "string"

}

Request Parameters

maxResults (p. 57)

The maximum number of tags to return.

Type: Integer

The token that speciﬁes the next page of results to return.

Type: String Required: No resourceArn (p. 57)

The Amazon Resource Name (ARN) of the resource whose tags are to be returned.

Type: String

Required: Yes

Response Syntax

{

"nextToken": "string", "tags": [

{

"key": "string", "value": "string"

} ]

(66)

Response Elements

}

Response Elements

The token that speciﬁes the next page of results to return.

Type: String tags (p. 57)

List of tags returned by the ListTagsForResource operation.

Type: Array of Tag (p. 114) objects

AWS IoT Things Graph

AWS IoT Things Graph

API Reference

API Version 2018-09-06

AWS IoT Things Graph: API Reference

Table of Contents

Welcome

Actions

AssociateEntityToThing

Request Syntax

Request Parameters

Response Elements

Errors

See Also

CreateFlowTemplate

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

CreateSystemInstance

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

CreateSystemTemplate

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

DeleteFlowTemplate

Request Syntax

Request Parameters

Response Elements

Errors

See Also

DeleteNamespace

Response Syntax

Response Elements

Errors

See Also

DeleteSystemInstance

Request Syntax

Request Parameters

Response Elements

Errors

See Also

DeleteSystemTemplate

Request Syntax

Request Parameters

Response Elements

Errors

See Also

DeploySystemInstance

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

DeprecateFlowTemplate

Request Syntax

Request Parameters

Response Elements

Errors

See Also

DeprecateSystemTemplate

Request Syntax

Request Parameters

Response Elements

Errors

See Also

DescribeNamespace

Request Syntax

Request Parameters