生命周期事件 - Amazon IoT Core
连接/断开连接事件连接尝试失败事件订阅/取消订阅事件
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

生命周期事件

Amazon IoT 可以在 MQTT 主题下发布生命周期事件。这些事件在默认情况下可用，且不能被禁用。

注意

生命周期消息可能不会按顺序发送。您可能会收到重复的消息。

thingName 仅当客户端使用独占事物功能连接时才会包含。

连接/断开连接事件

注意

借助 Amazon IoT Device Management 实例集索引，您可以搜索事物，运行聚合查询，并根据事物连接/断开连接事件创建动态组。有关更多信息，请参阅实例集索引。

Amazon IoT 在客户端建立连接或断开连接时将消息发布到以下 MQTT 主题：

  • $aws/events/presence/connected/clientId - 连接到消息代理的客户端。

  • $aws/events/presence/disconnected/clientId - 与消息代理断开连接的客户端。

下面是一系列 JSON 元素，发布到 $aws/events/presence/connected/clientId 主题的连接/断开连接消息中包含这些元素。

clientId

建立连接或断开连接的客户端的 ID。

注意

包含 # 或 + 的客户端 ID 不接收生命周期事件。

thingName

您的物联网事物的名称。thingName 仅当客户端使用独占事物功能连接时才会包含。

clientInitiatedDisconnect

如果客户端启动断开连接，则为 true。否则为 false。只能在断开连接消息中找到。

disconnectReason

客户端断开连接的原因。只能在断开连接消息中找到。下表包含有效值，以及在断开连接时代理是否会发送 Last Will and Testament（LWT）消息。

断开连接原因 描述 代理将发送 LWT 消息
AUTH_ERROR 客户端无法进行身份验证或授权失败。 是1
CLIENT_INITIATED_DISCONNECT 客户端指示它将断开连接。客户端可以通过发送 MQTT DISCONNECT 控制数据包或 Close frame（如果客户端使用的是 WebSocket 连接）来执行此操作。 否
CLIENT_ERROR 客户端出错，导致它断开连接。例如，如果客户端在同一连接上发送多个 MQTT CONNECT 数据包，或者客户端尝试使用超过有效载荷限制的有效载荷进行发布，则将断开连接。 是
CONNECTION_LOST 客户端-服务器连接被切断。在高网络延迟期间或互联网连接断开时，可能会发生此情况。 是
DUPLICATE_CLIENTID 客户端使用的是已在使用的客户端 ID。在这种情况下，已连接的客户端将因这一断开连接原因而断开连接。 是
FORBIDDEN_ACCESS 不允许连接客户端。例如，IP 地址被拒绝的客户端将无法连接。 是1
MQTT_KEEP_ALIVE_TIMEOUT 如果在 1.5 倍的客户端保持连接时间内没有客户端-服务器通信，则客户端将断开连接。 是
SERVER_ERROR 由于意外的服务器问题而断开连接。 是
SERVER_INITIATED_DISCONNECT 服务器出于操作原因而故意断开与客户端的连接。 是
API_INITIATED_DISCONNECT 客户端使用 DeleteConnection API 断开连接。 是2
THROTTLED 客户端由于超出限制而断开连接。 是
WEBSOCKET_TTL_EXPIRATION 由于 WebSocket 的连接时间超过其生存时间值，客户端断开连接。 是
CUSTOMAUTH_TTL_EXPIRATION 由于客户端的连接时间超过其自定义授权方的生存时间值，客户端断开连接。 是

1 如果设备在收到此错误之前连接处于活动状态。

2 为防止出现 Last Will and Testament（LWT）消息，设置 preventWillMessage=true 以覆盖 DeleteConnection API 的默认 LWT 发送行为。

eventType

事件类型。有效值为 connected 或 disconnected。

ipAddress

连接客户端的 IP 地址。该地址可以采用 IPv4 或 IPv6 格式。只能在连接消息中找到。

principalIdentifier

用于执行身份验证的凭证。对于 TLS 双向身份验证证书，这是证书 ID。对于其它连接，这是 IAM 凭证。

sessionIdentifier

Amazon IoT 中的全局唯一标识符，在会话持续时间内存在。

timestamp

事件发生时间的近似值。

versionNumber

生命周期事件的版本号。对于每个客户端 ID 连接，这是一个单调递增的长整数值。订阅者可以使用版本号来推断生命周期事件的顺序。

注意

客户端连接的连接和断开消息具有相同的版本号。

版本号可能会跳过值，而不保证对于每个事件始终增加 1。

如果客户端约一小时未连接，则版本号将重置为 0。对于持久会话，在客户端断开连接的时间超过为持久会话配置的生存时间（TTL）后，版本号将重置为 0。

连接消息具有以下结构。

{
    "clientId": "186b5",
    "thingName": "exampleThing",
    "timestamp": 1573002230757,
    "eventType": "connected",
    "sessionIdentifier": "00000000-0000-0000-0000-000000000000",
    "principalIdentifier": "12345678901234567890123456789012",
    "ipAddress": "192.0.2.0",
    "versionNumber": 0
}

断开连接消息具有以下结构。

{
    "clientId": "186b5",
    "thingName": "exampleThing",
    "timestamp": 1573002340451,
    "eventType": "disconnected",
    "sessionIdentifier": "00000000-0000-0000-0000-000000000000",
    "principalIdentifier": "12345678901234567890123456789012",
    "clientInitiatedDisconnect": true,
    "disconnectReason": "CLIENT_INITIATED_DISCONNECT",
    "versionNumber": 0
}

处理客户端断开连接

最佳实践是始终为生命周期事件实现等待状态，包括 Last Will and Testament（LWT）消息。收到断开连接消息后，您的代码应等待一段时间，并在采取措施之前验证设备是否仍处于脱机状态。实现此目标的一种方法是使用 SQS 延迟队列。当客户端收到 LWT 或生命周期事件时，您可以将消息列入队列进行排队（例如 5 秒）。当消息可用并被处理（通过 Lambda 或其它服务）时，您可以先检查设备是否仍处于离线状态，然后再采取进一步操作。

连接尝试失败事件

当客户端未被授权连接时，或者当配置了遗嘱消息且客户端未被授权发布到该遗嘱主题时，Amazon IoT 会发布一条消息到以下 MQTT 主题。

$aws/events/presence/connect_failed/clientId

以下是发布到 $aws/events/presence/connect_failed/clientId 主题的连接授权消息中包含的 JSON 元素列表。

clientId

尝试连接但失败的客户端的客户端 ID。

注意

包含 # 或 + 的客户端 ID 不接收生命周期事件。

thingName

您的物联网事物的名称。thingName 仅当客户端使用独占事物功能连接时才会包含。

timestamp

事件发生时间的近似值。

eventType

事件类型。有效值为 connect_failed。

connectFailureReason

连接失败的原因。有效值为 AUTHORIZATION_FAILED。

principalIdentifier

用于执行身份验证的凭证。对于 TLS 双向身份验证证书，这是证书 ID。对于其它连接，这是 IAM 凭证。

sessionIdentifier

Amazon IoT 中的全局唯一标识符，在会话持续时间内存在。

ipAddress

连接客户端的 IP 地址。该地址可以采用 IPv4 或 IPv6 格式。只能在连接消息中找到。

连接失败消息具有以下结构。

{
    "clientId": "186b5",
    "thingName": "exampleThing",
    "timestamp": 1460065214626,
    "eventType": "connect_failed",
    "connectFailureReason": "AUTHORIZATION_FAILED",
    "principalIdentifier": "12345678901234567890123456789012",
    "sessionIdentifier": "00000000-0000-0000-0000-000000000000",
    "ipAddress" : "192.0.2.0"
}

订阅/取消订阅事件

当客户端订阅或取消订阅 MQTT 主题时，Amazon IoT 将向以下 MQTT 主题发布消息：

$aws/events/subscriptions/subscribed/clientId

或 

$aws/events/subscriptions/unsubscribed/clientId

其中 clientId 是连接到 Amazon IoT 消息代理的 MQTT 客户端 ID。

发布到该主题的消息具有以下结构：

{
    "clientId": "186b5",
    "thingName": "exampleThing",
    "timestamp": 1460065214626,
    "eventType": "subscribed" | "unsubscribed",
    "sessionIdentifier": "00000000-0000-0000-0000-000000000000",
    "principalIdentifier": "12345678901234567890123456789012",
    "topics" : ["foo/bar","device/data","dog/cat"]
}

下面是一系列 JSON 元素，发布到 $aws/events/subscriptions/subscribed/clientId 和 $aws/events/subscriptions/unsubscribed/clientId 主题的已订阅/未订阅消息中包含这些元素。

clientId

订阅或取消订阅的客户端的 ID。

注意

包含 # 或 + 的客户端 ID 不接收生命周期事件。

thingName

您的物联网事物的名称。thingName 仅当客户端使用独占事物功能连接时才会包含。

eventType

事件类型。有效值为 subscribed 或 unsubscribed。

principalIdentifier

用于执行身份验证的凭证。对于 TLS 双向身份验证证书，这是证书 ID。对于其它连接，这是 IAM 凭证。

sessionIdentifier

Amazon IoT 中的全局唯一标识符，在会话持续时间内存在。

timestamp

事件发生时间的近似值。

主题

客户端已订阅的一系列 MQTT 主题。

注意

生命周期消息可能不会按顺序发送。您可能会收到重复的消息。