本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 设备连接状态查询
AWS IoT Fleet Indexing 支持单个设备连接查询，使您可以高效地检索特定设备的连接状态和相关元数据。此功能是对现有全实例集范围索引和查询能力的补充。
## 工作原理
设备连接查询支持可用于优化的单设备连接状态检索。此 API 提供对最新设备特定连接信息的低延迟、高吞吐量访问。一旦启用连接索引，您将可以访问此查询 API，该 API 将按标准查询收费。有关更多信息，请参阅 [AWS IoT 设备管理定价](https://aws.amazon.com/iot-device-management/pricing/#:~:text=Search%20queries%20(per%2010%2C000%20queries))。
## 功能
借助设备连接查询支持，您可以：
1. 使用设备的 `thingName` 查询其当前连接状态（已连接或已断开连接）。
1. 检索其他连接元数据，包括：
1. 断开连接原因
1. 最近连接或断开连接事件的时间戳。
1. 会话信息，包括保持活动时长
1. 套接字级别的会话信息，包括 IP 地址、端口和 VPC 端点 ID。此信息仅在满足以下条件时可用：
1. 您可以在舰队索引配置设置中启用此选项。
1. 调用 API 时，您在 IAM 策略中拥有相应的权限。
**注意**
实例集索引对设备的连接状态编制索引，该设备的连接 `clientId` 与[注册表](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry.html)中已注册事物的 `thingName` 相同。
## 优势
1. **低延迟：**反映最新的设备连接状态，并提供低延迟以反映来自 IoT Core 的连接状态变化。IoT Core 判定设备断开连接的情况有两种：一是设备主动发送断开连接请求，二是设备未发送断开连接请求而断开。IoT Core 将等待配置的保活时间的 1.5 倍后，才判定客户端已断开连接。连接状态 API 通常在 IoT Core 判定设备连接状态改变后一秒内反映这些变化。
1. **高吞吐量：**默认支持每秒 350 个事务（TPS），并可应要求调整至更高。
1. **数据保留：**启用舰队索引 (FI) ConnectivityIndexing 模式且事物未被删除时，可以无限期存储事件数据。如果禁用连接索引，记录将不会被保留。
**注意**
如果在此 API 启动之前已启用连接状态索引，则实例集索引会在 API 启动后开始跟踪连接状态变化，并基于这些变化反映更新后的状态。
## 先决条件
要使用设备连接查询支持，请执行以下操作：
1. [设置一个 AWS 账户](https://docs.aws.amazon.com/iot/latest/developerguide/setting-up.html)
1. AWS IoT Core 在您的首选地区注册设备并将其注册到该区域
1. 使用连接@@ [索引启用队列](https://docs.aws.amazon.com/iot/latest/developerguide/managing-index.html)索引。可选：通过启用该`includeSocketInformation`选项 Opt-in 来接收套接字级别信息。
**注意**
如果您已经启用了连接索引，则无需进行其他设置。
有关详细的设置说明，请参阅[《AWS IoT 开发人员指南》](https://docs.aws.amazon.com/iot/latest/developerguide/setting-up.html)
## 示例
**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`：在注册 AWS IoT 表中注册的设备的名称。这必须与`clientId`用于连接 AWS 物联网核心的相匹配。
+ `includeSocketInformation`：该`includeSocketInformation`参数控制 API 响应中是否包含套接字级别的网络信息。设置为 true 时，响应包含以下字段：`sourceIp, sourcePort, targetIp, targetPort, vpcEndpointId`。如果`includeSocketInformation`未指定或设置为 false，则这些套接字字段将从响应中排除。要限制特定的 IAM 用户访问套接字信息，您需要通过将`includeSocketInformation`条件键设置为 false 来在他们的 IAM 策略中指定这一点
**响应字段**
+ `thingName`：在注册 AWS IoT 表中注册的设备的名称。这必须与`clientId`用于连接 AWS 物联网核心的相匹配。
+ `connected`：布尔值 true，表示此设备当前已连接。
+ `disconnectReason`：断开连接的原因。`NONE`适用于已连接的设备和`UNKNOWN`从未连接过的设备。对于已断开连接的设备，这将表明断开连接是客户端启动的、服务器启动的、由于 authentication/authorization 问题还是网络问题。有关断开连接原因代码，请参阅 [LifeCycleEvents ](https://docs.aws.amazon.com//iot/latest/developerguide/life-cycle-events.html)
+ `timestamp`：表示设备最近的连接或断开连接事件的时间戳。
+ `clientId`: MQTT 客户端的客户端 ID。
+ `keepAliveDuration`：客户端在建立连接时指定的保持连接间隔（以秒为单位）。这决定了客户端发送保持活动状态消息以保持连接的频率。
+ `cleanSession`：表示客户端是否正在使用干净会话。
+ `sessionExpiry`：客户端在建立连接时指定的持续会话到期配置。这决定了客户端断开连接后会话将保持活动状态多长时间。
+ `sourceIp`：发起连接的客户机的 IP 地址。仅当设置`includeSocketInformation`为 true 且用户有权检索此信息时才会返回。
+ `sourcePort`：客户端用于连接的端口号。仅当设置`includeSocketInformation`为 true 且用户有权检索此信息时才会返回。
+ `targetIp`：发出连接请求的 IP 地址。仅当设置`includeSocketInformation`为 true 且用户有权检索此信息时才会返回
+ `targetPort`：客户端连接的 AWS 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"
}
}
}]
}
```