AWS IoT Events

(1)

AWS IoT Events

API Reference

AWS IoT Events: API Reference

(2)

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 Events

AWS IoT Events monitors your equipment or device ﬂeets for failures or changes in operation, and triggers actions when such events occur. You can use AWS IoT Events API operations to create, read, update, and delete inputs and detector models, and to list their versions.

AWS IoT Events Data

AWS IoT Events monitors your equipment or device ﬂeets for failures or changes in operation, and triggers actions when such events occur. You can use AWS IoT Events Data API commands to send inputs to detectors, list detectors, and view or update a detector's status.

For more information, see What is AWS IoT Events? in the AWS IoT Events Developer Guide.

(7)

Actions

The following actions are supported by AWS IoT Events:

• CreateAlarmModel (p. 4)

• CreateDetectorModel (p. 11)

• CreateInput (p. 22)

• DeleteAlarmModel (p. 25)

• DeleteDetectorModel (p. 27)

• DeleteInput (p. 29)

• DescribeAlarmModel (p. 31)

• DescribeDetectorModel (p. 37)

• DescribeDetectorModelAnalysis (p. 46)

• DescribeInput (p. 48)

• DescribeLoggingOptions (p. 50)

• GetDetectorModelAnalysisResults (p. 52)

• ListAlarmModels (p. 55)

• ListAlarmModelVersions (p. 57)

• ListDetectorModels (p. 60)

• ListDetectorModelVersions (p. 62)

• ListInputRoutings (p. 65)

• ListInputs (p. 68)

• ListTagsForResource (p. 70)

• PutLoggingOptions (p. 72)

• StartDetectorModelAnalysis (p. 74)

• TagResource (p. 83)

• UntagResource (p. 85)

• UpdateAlarmModel (p. 87)

• UpdateDetectorModel (p. 93)

• UpdateInput (p. 103)

The following actions are supported by AWS IoT Events Data:

• BatchAcknowledgeAlarm (p. 106)

• BatchDisableAlarm (p. 108)

• BatchEnableAlarm (p. 110)

• BatchPutMessage (p. 112)

• BatchResetAlarm (p. 114)

• BatchSnoozeAlarm (p. 116)

• BatchUpdateDetector (p. 118)

• DescribeAlarm (p. 121)

• DescribeDetector (p. 124)

• ListAlarms (p. 127)

• ListDetectors (p. 130)

(8)

AWS IoT Events

The following actions are supported by AWS IoT Events:

• CreateAlarmModel (p. 4)

• CreateDetectorModel (p. 11)

• CreateInput (p. 22)

• DeleteAlarmModel (p. 25)

• DeleteDetectorModel (p. 27)

• DeleteInput (p. 29)

• DescribeAlarmModel (p. 31)

• DescribeDetectorModel (p. 37)

• DescribeDetectorModelAnalysis (p. 46)

• DescribeInput (p. 48)

• DescribeLoggingOptions (p. 50)

• GetDetectorModelAnalysisResults (p. 52)

• ListAlarmModels (p. 55)

• ListAlarmModelVersions (p. 57)

• ListDetectorModels (p. 60)

• ListDetectorModelVersions (p. 62)

• ListInputRoutings (p. 65)

• ListInputs (p. 68)

• ListTagsForResource (p. 70)

• PutLoggingOptions (p. 72)

• StartDetectorModelAnalysis (p. 74)

• TagResource (p. 83)

• UntagResource (p. 85)

• UpdateAlarmModel (p. 87)

• UpdateDetectorModel (p. 93)

• UpdateInput (p. 103)

(9)

CreateAlarmModel

Service: AWS IoT Events

Creates an alarm model to monitor an AWS IoT Events input attribute. You can use the alarm to get notiﬁed when the value is outside a speciﬁed range. For more information, see Create an alarm model in the AWS IoT Events Developer Guide.

Request Syntax

POST /alarm-models HTTP/1.1 Content-type: application/json {

"alarmCapabilities": { "acknowledgeFlow": { "enabled": boolean },

"initializationConfiguration": { "disabledOnInitialization": boolean }

},

"alarmEventActions": { "alarmActions": [ {

"dynamoDB": {

"hashKeyField": "string", "hashKeyType": "string", "hashKeyValue": "string", "operation": "string", "payload": {

"contentExpression": "string", "type": "string"

},

"payloadField": "string", "rangeKeyField": "string", "rangeKeyType": "string", "rangeKeyValue": "string", "tableName": "string"

},

"dynamoDBv2": { "payload": {

},

"tableName": "string"

},

"firehose": {

"deliveryStreamName": "string", "payload": {

},

"separator": "string"

},

"iotEvents": {

"inputName": "string", "payload": {

} },

"iotSiteWise": { "assetId": "string",

(10)

CreateAlarmModel

"entryId": "string", "propertyAlias": "string", "propertyId": "string", "propertyValue": { "quality": "string", "timestamp": {

"offsetInNanos": "string", "timeInSeconds": "string"

},

"value": {

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

} } },

"iotTopicPublish": { "mqttTopic": "string", "payload": {

} },

"lambda": {

"functionArn": "string", "payload": {

} }, "sns": { "payload": {

},

"targetArn": "string"

}, "sqs": { "payload": {

},

"queueUrl": "string", "useBase64": boolean }

} ] },

"alarmModelDescription": "string", "alarmModelName": "string",

"alarmNotification": { "notificationActions": [ {

"action": {

"lambdaAction": {

}

(11)

CreateAlarmModel

"additionalMessage": "string", "subject": "string"

},

"from": "string", "recipients": { "to": [ {

"ssoIdentity": {

"identityStoreId": "string", "userId": "string"

} } ] } } ],

"smsConfigurations": [ {

"additionalMessage": "string", "recipients": [

{

"ssoIdentity": {

} } ],

"senderId": "string"

} ] } ] },

"alarmRule": { "simpleRule": {

"comparisonOperator": "string", "inputProperty": "string", "threshold": "string"

} },

"key": "string", "roleArn": "string", "severity": number, "tags": [

{

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

} ] }

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

alarmCapabilities (p. 4)

Contains the conﬁguration information of alarm state changes.

Type: AlarmCapabilities (p. 145) object

(12)

CreateAlarmModel

Required: No

alarmEventActions (p. 4)

Contains information about one or more alarm actions.

Type: AlarmEventActions (p. 146) object Required: No

alarmModelDescription (p. 4)

A description that tells you what the alarm model detects.

Type: String

Length Constraints: Maximum length of 128.

Required: No alarmModelName (p. 4)

A unique name that helps you identify the alarm model. You can't change this name after you create the alarm model.

Type: String

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

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

Required: Yes alarmNotiﬁcation (p. 4)

Contains information about one or more notiﬁcation actions.

Type: AlarmNotiﬁcation (p. 150) object Required: No

alarmRule (p. 4)

Deﬁnes when your alarm is invoked.

Type: AlarmRule (p. 151) object Required: Yes

key (p. 4)

An input attribute used as a key to create an alarm. AWS IoT Events routes inputs associated with this key to the alarm.

Type: String

Pattern: ^((`[\w\- ]+`)|([\w\-]+))(\.((`[\w- ]+`)|([\w\-]+)))*$

Required: No

(13)

CreateAlarmModel

Type: String

Required: Yes severity (p. 4)

A non-negative integer that reﬂects the severity level of the alarm.

Type: Integer

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

Required: No tags (p. 4)

A list of key-value pairs that contain metadata for the alarm model. The tags help you manage the alarm model. For more information, see Tagging your AWS IoT Events resources in the AWS IoT Events Developer Guide.

You can create up to 50 tags for one alarm model.

Type: Array of Tag (p. 213) objects Required: No

Response Syntax

HTTP/1.1 200

Content-type: application/json {

"alarmModelArn": "string", "alarmModelVersion": "string", "creationTime": number, "lastUpdateTime": number, "status": "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.

alarmModelArn (p. 8)

The ARN of the alarm model. For more information, see Amazon Resource Names (ARNs) in the AWS General Reference.

Type: String

alarmModelVersion (p. 8)

The version of the alarm model.

Type: String

(14)

CreateAlarmModel

creationTime (p. 8)

The time the alarm model was created, in the Unix epoch format.

Type: Timestamp lastUpdateTime (p. 8)

The time the alarm model was last updated, in the Unix epoch format.

Type: Timestamp status (p. 8)

The status of the alarm model. The status can be one of the following values:

• ACTIVE - The alarm model is active and it's ready to evaluate data.

• ACTIVATING - AWS IoT Events is activating your alarm model. Activating an alarm model can take up to a few minutes.

• INACTIVE - The alarm model is inactive, so it isn't ready to evaluate data. Check your alarm model information and update the alarm model.

• FAILED - You couldn't create or update the alarm model. Check your alarm model information and try again.

Type: String

Valid Values: ACTIVE | ACTIVATING | INACTIVE | FAILED

Errors

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

InternalFailureException An internal failure occurred.

HTTP Status Code: 500 InvalidRequestException

The request was invalid.

HTTP Status Code: 400 LimitExceededException

A limit was exceeded.

HTTP Status Code: 410 ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409 ResourceInUseException

The resource is in use.

(15)

CreateAlarmModel

HTTP Status Code: 503 ThrottlingException

The request could not be completed due to throttling.

HTTP Status Code: 429

CreateDetectorModel

Service: AWS IoT Events Creates a detector model.

Request Syntax

POST /detector-models HTTP/1.1 Content-type: application/json {

"detectorModelDefinition": { "initialStateName": "string", "states": [

{

"onEnter": { "events": [ {

"actions": [ {

"clearTimer": {

"timerName": "string"

},

"dynamoDB": {

},

"firehose": {

},

"iotEvents": {

(17)

CreateDetectorModel

"propertyAlias": "string", "propertyId": "string", "propertyValue": { "quality": "string", "timestamp": {

},

"value": {

} } },

} },

"lambda": {

} },

"resetTimer": {

},

"setTimer": {

"durationExpression": "string", "seconds": number,

},

"setVariable": { "value": "string", "variableName": "string"

},

"sns": { "payload": {

},

"sqs": { "payload": {

},

} ],

"condition": "string", "eventName": "string"

} ] },

"onExit": { "events": [

(18)

CreateDetectorModel

{

"actions": [ {

"clearTimer": {

},

"dynamoDB": {

},

"firehose": {

},

"iotEvents": {

} },

"iotSiteWise": { "assetId": "string", "entryId": "string", "propertyAlias": "string", "propertyId": "string", "propertyValue": { "quality": "string", "timestamp": {

},

"value": {

} }

(19)

CreateDetectorModel

"type": "string"

} },

"lambda": {

} },

"resetTimer": {

},

"setTimer": {

},

} ],

} ] },

"onInput": { "events": [ {

"actions": [ {

"clearTimer": {

},

"dynamoDB": {

},

(20)

CreateDetectorModel

},

"firehose": {

},

"iotEvents": {

} },

},

"value": {

} } },

} },

"lambda": {

} },

"resetTimer": {

},

"setTimer": {

"durationExpression": "string",

(21)

CreateDetectorModel

"variableName": "string"

},

} ],

"transitionEvents": [ {

"actions": [ {

"clearTimer": {

},

"dynamoDB": {

},

"firehose": {

},

"iotEvents": {

}

(22)

CreateDetectorModel

},

"value": {

} } },

} },

"lambda": {

} },

"resetTimer": {

},

"setTimer": {

},

(23)

CreateDetectorModel

} ] },

"stateName": "string"

} ] },

"detectorModelDescription": "string", "detectorModelName": "string", "evaluationMethod": "string", "key": "string",

"roleArn": "string", "tags": [

{

} ]}

URI Request Parameters

Request Body

detectorModelDeﬁnition (p. 11)

Information that deﬁnes how the detectors operate.

Type: DetectorModelDeﬁnition (p. 165) object Required: Yes

detectorModelDescription (p. 11)

A brief description of the detector model.

Type: String

Required: No

detectorModelName (p. 11)

The name of the detector model.

Type: String

Required: Yes

evaluationMethod (p. 11)

Information about the order in which events are evaluated and how actions are executed.

Default: BATCH

(24)

CreateDetectorModel

Type: String

Valid Values: BATCH | SERIAL Required: No

key (p. 11)

The input attribute key used to identify a device or system to create a detector (an instance of the detector model) and then to route each input received to the appropriate detector (instance).

This parameter uses a JSON-path expression in the message payload of each input to specify the attribute-value pair that is used to identify the device associated with the input.

Type: String

Pattern: ^((`[\w\- ]+`)|([\w\-]+))(\.((`[\w- ]+`)|([\w\-]+)))*$

Required: No roleArn (p. 11)

The ARN of the role that grants permission to AWS IoT Events to perform its operations.

Type: String

Required: Yes tags (p. 11)

Metadata that can be used to manage the detector model.

Response Syntax

HTTP/1.1 200

Content-type: application/json { "detectorModelConfiguration": { "creationTime": number, "detectorModelArn": "string",

"detectorModelDescription": "string", "detectorModelName": "string", "detectorModelVersion": "string", "evaluationMethod": "string", "key": "string",

"lastUpdateTime": number, "roleArn": "string", "status": "string"

} }

(25)

CreateDetectorModel

detectorModelConﬁguration (p. 19)

Information about how the detector model is conﬁgured.

Type: DetectorModelConﬁguration (p. 163) object

Errors

HTTP Status Code: 400 LimitExceededException

A limit was exceeded.

HTTP Status Code: 410 ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409 ResourceInUseException

The resource is in use.

HTTP Status Code: 409 ServiceUnavailableException

The service is currently unavailable.

CreateInput

Service: AWS IoT Events Creates an input.

Request Syntax

POST /inputs HTTP/1.1

Content-type: application/json { "inputDefinition": { "attributes": [ {

"jsonPath": "string"

} ] },

"inputDescription": "string", "inputName": "string",

"tags": [ {

} ]}

URI Request Parameters

Request Body

inputDeﬁnition (p. 22)

The deﬁnition of the input.

Type: InputDeﬁnition (p. 183) object Required: Yes

inputDescription (p. 22)

A brief description of the input.

Type: String

Required: No inputName (p. 22)

The name you want to give to the input.

Type: String

(28)

CreateInput

Pattern: ^[a-zA-Z][a-zA-Z0-9_]*$

Required: Yes tags (p. 22)

Metadata that can be used to manage the input.

Response Syntax

HTTP/1.1 201

Content-type: application/json { "inputConfiguration": { "creationTime": number, "inputArn": "string",

"inputDescription": "string", "inputName": "string", "lastUpdateTime": number, "status": "string"

}}

Response Elements

inputConﬁguration (p. 23)

Information about the conﬁguration of the input.

Type: InputConﬁguration (p. 181) object

Errors

(29)

CreateInput

ServiceUnavailableException

DeleteAlarmModel

Deletes an alarm model. Any alarm instances that were created based on this alarm model are also deleted. This action can't be undone.

Request Syntax

DELETE /alarm-models/alarmModelName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

alarmModelName (p. 25)

The name of the alarm model.

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 204

Response Elements

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

Errors

(31)

DeleteAlarmModel

HTTP Status Code: 409 ResourceNotFoundException

The resource was not found.

DeleteDetectorModel

Deletes a detector model. Any active instances of the detector model are also deleted.

Request Syntax

DELETE /detector-models/detectorModelName HTTP/1.1

URI Request Parameters

The name of the detector model to be deleted.

Required: Yes

Request Body

Response Syntax

HTTP/1.1 204

Response Elements

Errors

(33)

DeleteDetectorModel

ResourceNotFoundException The resource was not found.

DeleteInput

Service: AWS IoT Events Deletes an input.

Request Syntax

DELETE /inputs/inputName HTTP/1.1

URI Request Parameters

inputName (p. 29)

The name of the input to delete.

Pattern: ^[a-zA-Z][a-zA-Z0-9_]*$

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

Response Elements

Errors

(35)

DeleteInput

ResourceNotFoundException The resource was not found.

DescribeAlarmModel

Retrieves information about an alarm model. If you don't specify a value for the alarmModelVersion parameter, the latest version is returned.

Request Syntax

GET /alarm-models/alarmModelName?version=alarmModelVersion HTTP/1.1

URI Request Parameters

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

Content-type: application/json { "alarmCapabilities": { "acknowledgeFlow": { "enabled": boolean },

"initializationConfiguration": { "disabledOnInitialization": boolean }

},

"alarmEventActions": { "alarmActions": [ {

"dynamoDB": {

"hashKeyField": "string",

(37)

DescribeAlarmModel

"type": "string"

},

"firehose": {

},

"iotEvents": {

} },

},

"value": {

} } },

} },

"lambda": {

} }, "sns": { "payload": {

"contentExpression": "string",

(38)

DescribeAlarmModel

"type": "string"

},

}, "sqs": { "payload": {

},

} ] },

"alarmModelArn": "string",

"alarmModelDescription": "string", "alarmModelName": "string",

"alarmModelVersion": "string", "alarmNotification": { "notificationActions": [ {

"action": {

"lambdaAction": {

} } },

"emailConfigurations": [ {

"content": {

"additionalMessage": "string", "subject": "string"

},

"from": "string", "recipients": { "to": [ {

"ssoIdentity": {

} } ] } } ],

"smsConfigurations": [ {

"additionalMessage": "string", "recipients": [

{

"ssoIdentity": {

} } ],

(39)

DescribeAlarmModel

},

"alarmRule": { "simpleRule": {

"comparisonOperator": "string", "inputProperty": "string", "threshold": "string"

} },

"creationTime": number, "key": "string",

"lastUpdateTime": number, "roleArn": "string", "severity": number, "status": "string", "statusMessage": "string"

}

Response Elements

alarmCapabilities (p. 31)

Contains the conﬁguration information of alarm state changes.

Type: AlarmCapabilities (p. 145) object alarmEventActions (p. 31)

Contains information about one or more alarm actions.

Type: AlarmEventActions (p. 146) object alarmModelArn (p. 31)

The ARN of the alarm model. For more information, see Amazon Resource Names (ARNs) in the AWS General Reference.

Type: String

alarmModelDescription (p. 31)

The description of the alarm model.

Type: String

(40)

DescribeAlarmModel

alarmNotiﬁcation (p. 31)

Contains information about one or more notiﬁcation actions.

Type: AlarmNotiﬁcation (p. 150) object alarmRule (p. 31)

Deﬁnes when your alarm is invoked.

Type: AlarmRule (p. 151) object creationTime (p. 31)

The time the alarm model was created, in the Unix epoch format.

Type: Timestamp key (p. 31)

An input attribute used as a key to create an alarm. AWS IoT Events routes inputs associated with this key to the alarm.

Type: String

Pattern: ^((`[\w\- ]+`)|([\w\-]+))(\.((`[\w- ]+`)|([\w\-]+)))*$

lastUpdateTime (p. 31)

The time the alarm model was last updated, in the Unix epoch format.

Type: Timestamp roleArn (p. 31)

The ARN of the IAM role that allows the alarm to perform actions and access AWS resources. For more information, see Amazon Resource Names (ARNs) in the AWS General Reference.

Type: String

severity (p. 31)

A non-negative integer that reﬂects the severity level of the alarm.

Type: Integer

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

status (p. 31)

The status of the alarm model. The status can be one of the following values:

• ACTIVE - The alarm model is active and it's ready to evaluate data.

• ACTIVATING - AWS IoT Events is activating your alarm model. Activating an alarm model can take up to a few minutes.

• INACTIVE - The alarm model is inactive, so it isn't ready to evaluate data. Check your alarm model information and update the alarm model.

(41)

DescribeAlarmModel

Valid Values: ACTIVE | ACTIVATING | INACTIVE | FAILED statusMessage (p. 31)

Contains information about the status of the alarm model.

Type: String

Errors

HTTP Status Code: 400 ResourceNotFoundException

The resource was not found.

DescribeDetectorModel

Describes a detector model. If the version parameter is not speciﬁed, information about the latest version is returned.

Request Syntax

GET /detector-models/detectorModelName?version=detectorModelVersion HTTP/1.1

URI Request Parameters

The name of the detector model.

Required: Yes

detectorModelVersion (p. 37)

The version of the detector model.

Request Body

Response Syntax

HTTP/1.1 200

Content-type: application/json { "detectorModel": {

"detectorModelConfiguration": { "creationTime": number, "detectorModelArn": "string",

"detectorModelDescription": "string", "detectorModelName": "string", "detectorModelVersion": "string", "evaluationMethod": "string", "key": "string",

"lastUpdateTime": number, "roleArn": "string",

(43)

{

"onEnter": { "events": [ {

"actions": [ {

"clearTimer": {

},

"dynamoDB": {

},

"firehose": {

},

"iotEvents": {

} },

},

"value": {

} } },

"iotTopicPublish": {

(44)

"mqttTopic": "string", "payload": {

} },

"lambda": {

} },

"resetTimer": {

},

"setTimer": {

},

}, "sns": {

"payload": {

},

}, "sqs": {

"payload": {

},

} ],

} ] },

"onExit": { "events": [ {

"actions": [ {

"clearTimer": {

},

"dynamoDB": {

(45)

"rangeKeyType": "string", "rangeKeyValue": "string", "tableName": "string"

},

"firehose": {

},

"iotEvents": {

} },

},

"value": {

} } },

} },

"lambda": {

} },

"resetTimer": {

},

"setTimer": {

(46)

},

}, "sns": {

"payload": {

},

}, "sqs": {

"payload": {

},

} ],

} ] },

"onInput": { "events": [ {

"actions": [ {

"clearTimer": {

},

"dynamoDB": {

},

"firehose": {

"contentExpression": "string",

(47)

} },

},

"value": {

} } },

} },

"lambda": {

} },

"resetTimer": {

},

"setTimer": {

},

}, "sns": {

"payload": {

},

}, "sqs": {

"payload": {

},

AWS IoT Events

AWS IoT Events

API Reference

AWS IoT Events: API Reference

Table of Contents

Welcome

AWS IoT Events

AWS IoT Events Data

Actions

AWS IoT Events

CreateAlarmModel

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateDetectorModel

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Errors

See Also

CreateInput

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

DeleteAlarmModel

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

DeleteDetectorModel

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

DeleteInput

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

DescribeAlarmModel

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

DescribeDetectorModel

Request Syntax

URI Request Parameters

Request Body

Response Syntax