View a markdown version of this page

设备连接状态查询 - Amazon IoT Core
工作原理功能优势先决条件示例
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

设备连接状态查询

Amazon IoT Fleet Indexing 支持单个设备连接查询，使您可以高效地检索特定设备的连接状态和相关元数据。此功能是对现有全实例集范围索引和查询能力的补充。

工作原理

设备连接查询支持可用于优化的单设备连接状态检索。此 API 提供对最新设备特定连接信息的低延迟、高吞吐量访问。一旦启用连接索引，您将可以访问此查询 API，该 API 将按标准查询收费。有关更多信息，请参阅 Amazon IoT 设备管理定价。

功能

借助设备连接查询支持，您可以：

  1. 使用设备的 thingName 查询其当前连接状态（已连接或已断开连接）。

  2. 检索其他连接元数据，包括：

    1. 断开连接原因

    2. 最近连接或断开连接事件的时间戳。

    3. 会话信息，包括保持活动时长

    4. 套接字级别的会话信息，包括 IP 地址、端口和 VPC 端点 ID。此信息仅在满足以下条件时可用：

      1. 您可以在舰队索引配置设置中启用此选项。

      2. 调用 API 时，您在 IAM 策略中拥有相应的权限。

注意

实例集索引对设备的连接状态编制索引，该设备的连接 clientId 与注册表中已注册事物的 thingName 相同。

优势

  1. 低延迟：反映最新的设备连接状态，并提供低延迟以反映来自 IoT Core 的连接状态变化。IoT Core 判定设备断开连接的情况有两种：一是设备主动发送断开连接请求，二是设备未发送断开连接请求而断开。IoT Core 将等待配置的保活时间的 1.5 倍后，才判定客户端已断开连接。连接状态 API 通常在 IoT Core 判定设备连接状态改变后一秒内反映这些变化。

  2. 高吞吐量：默认支持每秒 350 个事务（TPS），并可应要求调整至更高。

  3. 数据保留：启用舰队索引 (FI) ConnectivityIndexing 模式且事物未被删除时，可以无限期存储事件数据。如果禁用连接索引，记录将不会被保留。

注意

如果在此 API 启动之前已启用连接状态索引，则实例集索引会在 API 启动后开始跟踪连接状态变化，并基于这些变化反映更新后的状态。

先决条件

要使用设备连接查询支持，请执行以下操作：

  1. 设置一个 Amazon 账户

  2. Amazon IoT Core 在您的首选地区注册设备并将其注册到该区域

  3. 使用连接@@ 索引启用队列索引。可选：通过启用该includeSocketInformation选项 Opt-in 来接收套接字级别信息。

注意

如果您已经启用了连接索引，则无需进行其他设置。

有关详细的设置说明，请参阅《Amazon IoT 开发人员指南》

示例

CLI 命令：

aws iot get-thing-connectivity-data --include-socket-information --thing-name myThingName

响应：

{
   "thingName": "myThingName",
   "connected": true,
   "timestamp": "2024-12-19T10:00:00.000000-08:00",
   "disconnectReason": "NONE",
   "sourceIp": "192.0.2.1",
   "sourcePort": 52123,
   "targetIp": "198.51.100.1",
   "targetPort": 8883,
   "vpcEndpointId": "vpce-1234567890abcdef0",
   "keepAliveDuration": 60,
   "cleanSession": true,
   "clientId": "myThingName"
}

API 参数

  • thingName：在注册 Amazon IoT 表中注册的设备的名称。这必须与clientId用于连接 Amazon 物联网核心的相匹配。

  • includeSocketInformation：该includeSocketInformation参数控制 API 响应中是否包含套接字级别的网络信息。设置为 true 时，响应包含以下字段：sourceIp, sourcePort, targetIp, targetPort, vpcEndpointId。如果includeSocketInformation未指定或设置为 false，则这些套接字字段将从响应中排除。要限制特定的 IAM 用户访问套接字信息，您需要通过将includeSocketInformation条件键设置为 false 来在他们的 IAM 策略中指定这一点

响应字段

  • thingName：在注册 Amazon IoT 表中注册的设备的名称。这必须与clientId用于连接 Amazon 物联网核心的相匹配。

  • connected：布尔值 true，表示此设备当前已连接。

  • disconnectReason：断开连接的原因。NONE适用于已连接的设备和UNKNOWN从未连接过的设备。对于已断开连接的设备，这将表明断开连接是客户端启动的、服务器启动的、由于 authentication/authorization 问题还是网络问题。有关断开连接原因代码，请参阅 LifeCycleEvents

  • timestamp：表示设备最近的连接或断开连接事件的时间戳。

  • clientId: MQTT 客户端的客户端 ID。

  • keepAliveDuration：客户端在建立连接时指定的保持连接间隔（以秒为单位）。这决定了客户端发送保持活动状态消息以保持连接的频率。

  • cleanSession：表示客户端是否正在使用干净会话。

  • sessionExpiry：客户端在建立连接时指定的持续会话到期配置。这决定了客户端断开连接后会话将保持活动状态多长时间。

  • sourceIp：发起连接的客户机的 IP 地址。仅当设置includeSocketInformation为 true 且用户有权检索此信息时才会返回。

  • sourcePort：客户端用于连接的端口号。仅当设置includeSocketInformation为 true 且用户有权检索此信息时才会返回。

  • targetIp：发出连接请求的 IP 地址。仅当设置includeSocketInformation为 true 且用户有权检索此信息时才会返回

  • targetPort：客户端连接的 Amazon IoT Core 端点的端口号。仅当设置includeSocketInformation为 true 且用户有权检索此信息时才会返回。

  • vpcEndpointId：客户端通过的 VPC 终端节点的 ID（如果适用）。仅当设置includeSocketInformation为 true 且用户有权检索此信息时才会返回。

所需权限

要使用该 GetThingConnectivityData API，您需要获得以下 IAM 权限

iot:GetThingConnectivityData

您可以使用基于资源的策略将此权限范围限定为特定的事物。使用iot:IncludeSocketInformation条件对套接字信息实施精细的访问控制。以下策略示例演示了您拒绝用户访问套接字信息的场景。请注意，此示例仅在授予操作访问权限的策略时起作用 GetThingConnectivityData。

授权策略示例

{
  "Version": "2012-10-17",
  "Statement": [ 
  { 
    "Effect": "Allow",
    "Action": [ "iot:GetThingConnectivityData" ],
    "Resource": [ "arn:aws:iot:us-east-1:123456789012:thing/*"],
    "Condition": { 
      "Bool": { 
        "iot:IncludeSocketInformation": "false" 
      } 
    } 
  }] 
}