定义 Amazon IoT Events 警报 (CLI) - Amazon IoT SiteWise
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

定义 Amazon IoT Events 警报 (CLI)

您可以使用 Amazon Command Line Interface (Amazon CLI) 来定义监控资产属性的 Amazon IoT Events 警报。您可以在新的或现有的资产模型上定义警报。在资产模型上定义警报后,可以在 Amazon IoT Events 中创建警报并将其连接到资产模型。在此过程中,您将执行以下操作:

步骤 1:在资产模型上定义警报

向新的或现有的资产模型添加警报定义和关联属性。

在资产模型上定义警报 (CLI)
  1. 创建名为 asset-model-payload.json 的文件。按照其他部分中的步骤将资产模型的详细信息添加到文件中,但不要提交创建或更新资产模型的请求。在本节中,您将向 asset-model-payload.json 文件中的资产模型详细信息添加警报定义。

    注意

    您的资产模型必须定义至少一个资产属性,包括要通过警报监控的资产属性。

  2. 向资产模型添加警报复合模型 (assetModelCompositeModels)。Amazon IoT Events 警报复合模型指定 IOT_EVENTS 类型并指定警报源属性。在 Amazon IoT Events 中创建警报模型后,您可以添加警报源属性。

    重要

    警报复合模型必须与您稍后创建的 Amazon IoT Events 警报模型同名。警报模型名称只能包含字母数字字符。指定一个唯一的字母数字名称,这样您就可以对警报模型使用相同的名称。

    { ... "assetModelCompositeModels": [ { "name": "BoilerTemperatureHighAlarm", "type": "AWS/ALARM", "properties": [ { "name": "AWS/ALARM_TYPE", "dataType": "STRING", "type": { "attribute": { "defaultValue": "IOT_EVENTS" } } }, { "name": "AWS/ALARM_STATE", "dataType": "STRUCT", "dataTypeSpec": "AWS/ALARM_STATE", "type": { "measurement": {} } } ] } ] }
  3. 向资产模型添加警报阈值属性。指定用于此阈值的默认值。您可以基于此模型覆盖每个资产的此默认值。

    注意

    警报阈值属性必须为 INTEGERDOUBLE

    { ... "assetModelProperties": [ ... { "name": "Temperature Max Threshold", "dataType": "DOUBLE", "type": { "attribute": { "defaultValue": "105.0" } } } ] }
  4. 创建资产模型或更新现有资产模型。请执行以下操作之一:

    • 要创建资源模型,请运行以下命令。

      aws iotsitewise create-asset-model --cli-input-json file://asset-model-payload.json
    • 要更新现有资源模型,请运行以下命令。asset-model-id替换为资产模型的 ID。

      aws iotsitewise update-asset-model \ --asset-model-id asset-model-id \ --cli-input-json file://asset-model-payload.json

    运行命令之后,请记下响应中的 assetModelId

以下资产模型表示报告温度数据的锅炉。该资产模型定义了一个警报,用于检测锅炉何时过热。

{ "assetModelName": "Boiler Model", "assetModelDescription": "Represents a boiler.", "assetModelProperties": [ { "name": "Temperature", "dataType": "DOUBLE", "unit": "C", "type": { "measurement": {} } }, { "name": "Temperature Max Threshold", "dataType": "DOUBLE", "type": { "attribute": { "defaultValue": "105.0" } } }, { "name": "identityStoreId", "dataType": "STRING", "type": { "attribute": { "defaultValue": "d-123EXAMPLE" } } }, { "name": "userId", "dataType": "STRING", "type": { "attribute": { "defaultValue": "123EXAMPLE-a1b2c3d4-5678-90ab-cdef-33333EXAMPLE" } } }, { "name": "senderId", "dataType": "STRING", "type": { "attribute": { "defaultValue": "MyFactory" } } }, { "name": "fromAddress", "dataType": "STRING", "type": { "attribute": { "defaultValue": "my.factory@example.com" } } }, { "name": "emailSubject", "dataType": "STRING", "type": { "attribute": { "defaultValue": "[ALERT] High boiler temperature" } } }, { "name": "additionalMessage", "dataType": "STRING", "type": { "attribute": { "defaultValue": "Turn off the power before you check the alarm." } } } ], "assetModelHierarchies": [ ], "assetModelCompositeModels": [ { "name": "BoilerTemperatureHighAlarm", "type": "AWS/ALARM", "properties": [ { "name": "AWS/ALARM_TYPE", "dataType": "STRING", "type": { "attribute": { "defaultValue": "IOT_EVENTS" } } }, { "name": "AWS/ALARM_STATE", "dataType": "STRUCT", "dataTypeSpec": "AWS/ALARM_STATE", "type": { "measurement": {} } } ] } ] }

步骤 2:定义 Amazon IoT Events 警报模型

在 Amazon IoT Events 中创建警报模型。在 Amazon IoT Events 中,您可以使用表达式来指定警报模型中的值。您可以使用表达式指定 Amazon IoT SiteWise 中要评估的值并用作警报的输入。当 Amazon IoT SiteWise 向警报模型发送资产属性值时,Amazon IoT Events 会评估表达式以获取该属性的值或资产的 ID。您可以在警报模型中使用以下表达式:

  • 资产属性值

    要获取资产属性的值,请使用以下表达式。assetModelId替换为资产模型的 ID,并将 propertyID 替换为属性的 ID。

    $sitewise.assetModel.`assetModelId`.`propertyId`.propertyValue.value
  • 资产 ID

    要获取资产的 ID,请使用以下表达式。assetModelId替换为资产模型的 ID,并将 propertyID 替换为属性的 ID。

    $sitewise.assetModel.`assetModelId`.`propertyId`.assetId
注意

在创建警报模型时,您可以定义字面值,而不是评估为 Amazon IoT SiteWise 值的表达式。这可以减少您在资产模型上定义的属性数量。但是,如果您将值定义为文字,则无法根据资产模型自定义资产的该值。您的 Amazon IoT SiteWise Monitor 用户也无法自定义警报,因为他们只能在资产上配置警报设置。

创建 Amazon IoT Events 警报模型 (CLI)
  1. 在 Amazon IoT Events 中创建警报模型时,必须指定警报使用的每个属性的 ID,其中包括以下内容:

    • 复合资产模型中的警报状态属性

    • 警报监控的属性

    • 阈值属性

    • (可选)IAM Identity Center 身份存储 ID 属性

    • (可选)IAM Identity Center 用户 ID 属性

    • (可选)短信发送人 ID 属性

    • (可选)电子邮件发送人地址属性

    • (可选)电子邮件主题属性

    • (可选)附加消息属性

    运行以下命令以检索资产模型上这些属性的 ID。asset-model-id替换为上一步中的资产模型的 ID。

    aws iotsitewise describe-asset-model --asset-model-id asset-model-id

    此操作将返回包含资产模型详细信息的响应。记下警报使用的每个属性的 ID。在下一步中创建 Amazon IoT Events 警报模型时,您将使用这些 ID。

  2. 在 Amazon IoT Events 中创建警报模型。执行以下操作:

    1. 创建名为 alarm-model-payload.json 的文件。

    2. 将以下 JSON 对象复制到文件中。

    3. 为您的警报输入名称(alarmModelName)、说明(alarmModelDescription)和严重性(severity)。对于严重性,请指定一个反映贵公司严重性级别的整数。

      重要

      警报模型必须与您之前在资产模型上定义的警报复合模型同名。

      警报模型名称只能包含字母数字字符。

      { "alarmModelName": "BoilerTemperatureHighAlarm", "alarmModelDescription": "Detects when the boiler temperature is high.", "severity": 3 }
    4. 将比较规则 (alarmRule) 添加到警报中。此规则定义了要监控的属性 (inputProperty)、要比较的阈值 (threshold) 和要使用的比较运算符 (comparisonOperator)。

      • assetModelId替换为资产模型的 ID。

      • alarmPropertyId替换为警报监控的属性的 ID。

      • thresholdAttributeId替换为阈值属性的 ID。

      • GREATER 替换为运算符,用于将属性值与阈值进行比较。从以下选项中进行选择:

        • LESS

        • LESS_OR_EQUAL

        • EQUAL

        • NOT_EQUAL

        • GREATER_OR_EQUAL

        • GREATER

      { "alarmModelName": "BoilerTemperatureHighAlarm", "alarmModelDescription": "Detects when the boiler temperature is high.", "severity": 3, "alarmRule": { "simpleRule": { "inputProperty": "$sitewise.assetModel.`assetModelId`.`alarmPropertyId`.propertyValue.value", "comparisonOperator": "GREATER", "threshold": "$sitewise.assetModel.`assetModelId`.`thresholdAttributeId`.propertyValue.value" } } }
    5. 添加一个操作 (alarmEventActions),当警报状态发生更改时将警报状态发送给 Amazon IoT SiteWise。

      注意

      对于高级配置,您可以定义警报状态更改时要执行的其他操作。例如,您可以调用 Amazon Lambda 函数或发布到 MQTT 主题。有关更多信息,请参阅 Amazon IoT Events 开发人员指南中的使用其他 Amazon 服务

      • assetModelId替换为资产模型的 ID。

      • alarmPropertyId替换为警报监控的属性的 ID。

      • alarmStatePropertyId 替换为警报复合模型中警报状态属性的 ID。

      { "alarmModelName": "BoilerTemperatureHighAlarm", "alarmModelDescription": "Detects when the boiler temperature is high.", "severity": 3, "alarmRule": { "simpleRule": { "inputProperty": "$sitewise.assetModel.`assetModelId`.`alarmPropertyId`.propertyValue.value", "comparisonOperator": "GREATER", "threshold": "$sitewise.assetModel.`assetModelId`.`thresholdAttributeId`.propertyValue.value" } }, "alarmEventActions": { "alarmActions": [ { "iotSiteWise": { "assetId": "$sitewise.assetModel.`assetModelId`.`alarmPropertyId`.assetId", "propertyId": "'alarmStatePropertyId'" } } ] } }
    6. (可选)将警报功能 (alarmCapabilities) 添加到 alarm-model-payload.json 的有效负载中。在此对象中,您可以根据资产模型指定是否启用确认流程以及资产的默认启用状态。有关确认流的更多信息,请参阅 警报状态

      { "alarmModelName": "BoilerTemperatureHighAlarm", "alarmModelDescription": "Detects when the boiler temperature is high.", "severity": 3, "alarmRule": { "simpleRule": { "inputProperty": "$sitewise.assetModel.`assetModelId`.`alarmPropertyId`.propertyValue.value", "comparisonOperator": "GREATER", "threshold": "$sitewise.assetModel.`assetModelId`.`thresholdAttributeId`.propertyValue.value" } }, "alarmEventActions": { "alarmActions": [ { "iotSiteWise": { "assetId": "$sitewise.assetModel.`assetModelId`.`alarmPropertyId`.assetId", "propertyId": "'alarmStatePropertyId'" } } ] }, "alarmNotification": { "notificationActions": [ { "action": { "lambdaAction": { "functionArn": "alarmNotificationFunctionArn" } }, "smsConfigurations": [ { "recipients": [ { "ssoIdentity": { "identityStoreId": "$sitewise.assetModel.`assetModelId`.`identityStoreIdAttributeId`.propertyValue.value", "userId": "$sitewise.assetModel.`assetModelId`.`userIdAttributeId`.propertyValue.value" } } ], "senderId": "$sitewise.assetModel.`assetModelId`.`senderIdAttributeId`.propertyValue.value", "additionalMessage": "$sitewise.assetModel.`assetModelId`.`additionalMessageAttributeId`.propertyValue.value" } ], "emailConfigurations": [ { "from": "$sitewise.assetModel.`assetModelId`.`fromAddressAttributeId`.propertyValue.value", "recipients": { "to": [ { "ssoIdentity": { "identityStoreId": "$sitewise.assetModel.`assetModelId`.`identityStoreIdAttributeId`.propertyValue.value", "userId": "$sitewise.assetModel.`assetModelId`.`userIdAttributeId`.propertyValue.value" } } ] }, "content": { "subject": "$sitewise.assetModel.`assetModelId`.`emailSubjectAttributeId`.propertyValue.value", "additionalMessage": "$sitewise.assetModel.`assetModelId`.`additionalMessageAttributeId`.propertyValue.value" } } ] } ] }, "alarmCapabilities": { "initializationConfiguration": { "disabledOnInitialization": false }, "acknowledgeFlow": { "enabled": true } } }
    7. 添加 Amazon IoT Events 可以担任发送数据至 Amazon IoT SiteWise 的 IAM 服务角色 (roleArn) 。此角色需要 iotsitewise:BatchPutAssetPropertyValue 权限以及允许 iotevents.amazonaws.com 担任角色的信任关系。有关更多信息,请参阅《Amazon IoT Events 开发人员指南》中的警报服务角色

      • roleArn 替换为 Amazon IoT Events 可以代入执行这些操作的角色的 ARN。

      { "alarmModelName": "BoilerTemperatureHighAlarm", "alarmModelDescription": "Detects when the boiler temperature is high.", "severity": 3, "alarmRule": { "simpleRule": { "inputProperty": "$sitewise.assetModel.`assetModelId`.`alarmPropertyId`.propertyValue.value", "comparisonOperator": "GREATER", "threshold": "$sitewise.assetModel.`assetModelId`.`thresholdAttributeId`.propertyValue.value" } }, "alarmEventActions": { "alarmActions": [ { "iotSiteWise": { "assetId": "$sitewise.assetModel.`assetModelId`.`alarmPropertyId`.assetId", "propertyId": "'alarmStatePropertyId'" } } ] }, "alarmNotification": { "notificationActions": [ { "action": { "lambdaAction": { "functionArn": "alarmNotificationFunctionArn" } }, "smsConfigurations": [ { "recipients": [ { "ssoIdentity": { "identityStoreId": "$sitewise.assetModel.`assetModelId`.`identityStoreIdAttributeId`.propertyValue.value", "userId": "$sitewise.assetModel.`assetModelId`.`userIdAttributeId`.propertyValue.value" } } ], "senderId": "$sitewise.assetModel.`assetModelId`.`senderIdAttributeId`.propertyValue.value", "additionalMessage": "$sitewise.assetModel.`assetModelId`.`additionalMessageAttributeId`.propertyValue.value" } ], "emailConfigurations": [ { "from": "$sitewise.assetModel.`assetModelId`.`fromAddressAttributeId`.propertyValue.value", "recipients": { "to": [ { "ssoIdentity": { "identityStoreId": "$sitewise.assetModel.`assetModelId`.`identityStoreIdAttributeId`.propertyValue.value", "userId": "$sitewise.assetModel.`assetModelId`.`userIdAttributeId`.propertyValue.value" } } ] }, "content": { "subject": "$sitewise.assetModel.`assetModelId`.`emailSubjectAttributeId`.propertyValue.value", "additionalMessage": "$sitewise.assetModel.`assetModelId`.`additionalMessageAttributeId`.propertyValue.value" } } ] } ] }, "alarmCapabilities": { "initializationConfiguration": { "disabledOnInitialization": false }, "acknowledgeFlow": { "enabled": false } }, "roleArn": "arn:aws:iam::123456789012:role/MyIoTEventsAlarmRole" }
    8. 运行以下命令,从 alarm-model-payload.json 的有效负载中创建 Amazon IoT Events 警报模型。

      aws iotevents create-alarm-model --cli-input-json file://alarm-model-payload.json
    9. 操作将返回响应,其中包含警报模型的 ARN,alarmModelArn。复制此 ARN,以便下一步在资产模型的警报定义中进行设置。

步骤 3:启用 Amazon IoT SiteWise 和 Amazon IoT Events 之间的数据流

在 Amazon IoT SiteWise 和 Amazon IoT Events 中创建所需资源后,您可以启用资源之间的数据流以启用警报。在本节中,您将更新资产模型中的警报定义以使用您在上一步中创建的警报模型。

启用 Amazon IoT SiteWise 和 Amazon IoT Events 之间的数据流 (CLI)
  • 在资产模型中将警报模型设置为警报的来源。执行以下操作:

    1. 运行以下命令以检索现有资产模型定义。asset-model-id替换为资产模型的 ID。

      aws iotsitewise describe-asset-model --asset-model-id asset-model-id

      此操作将返回包含资产模型详细信息的响应。

    2. 创建一个名为 update-asset-model-payload.json 的文件,并将上一命令的响应复制到该文件中。

    3. update-asset-model-payload.json 文件中删除以下键/值对:

      • assetModelId

      • assetModelArn

      • assetModelCreationDate

      • assetModelLastUpdateDate

      • assetModelStatus

    4. 将警报源属性 (AWS/ALARM_SOURCE) 添加到您之前定义的警报复合模型中。alarmModelArn替换为警报模型的 ARN,后者设置警报源属性的值。

      { ... "assetModelCompositeModels": [ ... { "name": "BoilerTemperatureHighAlarm", "type": "AWS/ALARM", "properties": [ { "id": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE", "name": "AWS/ALARM_TYPE", "dataType": "STRING", "type": { "attribute": { "defaultValue": "IOT_EVENTS" } } }, { "id": "a1b2c3d4-5678-90ab-cdef-22222EXAMPLE", "name": "AWS/ALARM_STATE", "dataType": "STRUCT", "dataTypeSpec": "AWS/ALARM_STATE", "type": { "measurement": {} } }, { "name": "AWS/ALARM_SOURCE", "dataType": "STRING", "type": { "attribute": { "defaultValue": "alarmModelArn" } } } ] } ] }
    5. 运行以下命令,使用存储在 update-asset-model-payload.json 文件中的定义更新资产模型。asset-model-id替换为资产模型的 ID。

      aws iotsitewise update-asset-model \ --asset-model-id asset-model-id \ --cli-input-json file://update-asset-model-payload.json

现在,您的资产模型定义了一个在 Amazon IoT Events 中检测到的警报。报警根据该资产模型对所有资产中的目标属性进行监控。您可以为每项资产配置警报,以自定义每项资产的阈值或 IAM Identity Center 接收人等属性。有关更多信息,请参见 为资产配置警报