本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 裝置連線狀態查詢
<a name="device-connectivity-status"></a>

AWS IoT 機群索引支援個別裝置連線查詢，可讓您有效率地擷取特定裝置的連線狀態和相關中繼資料。此功能可補充現有的機群整體索引和查詢功能。

## 運作方式
<a name="w2aac37c21b5"></a>

裝置連線查詢支援可用於最佳化的單一裝置連線狀態擷取。此 API 提供最新裝置特定連線資訊的低延遲、高輸送量存取。啟用連線索引後，您將可以存取此查詢 API，並以標準查詢收費。如需詳細資訊，請參閱 [AWS IoT Device Management 定價](https://aws.amazon.com/iot-device-management/pricing/#:~:text=Search%20queries%20(per%2010%2C000%20queries))

## 功能
<a name="w2aac37c21b7"></a>

透過裝置連線查詢支援，您可以：

1. 使用 查詢指定裝置的目前連線狀態 （已連線或已中斷連線）`thingName`。

1. 擷取其他連線中繼資料，包括：

   1. 中斷連線原因

   1. 最近連線或中斷連線事件的時間戳記。

**注意**  
機群索引會為裝置的連線狀態建立索引，其連線 `clientId` 與[登錄](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry.html)中已註冊物件的 `thingName` 相同。

## 優勢
<a name="w2aac37c21b9"></a>

1. **低延遲：**反映最新的裝置連線狀態，並提供低延遲，以反映來自 IoT Core 的連線狀態變更。IoT Core 會在收到來自裝置的中斷連線請求時，或在裝置中斷連線但未傳送中斷連線請求的情況下，立即將裝置判斷為中斷連線。IoT 核心會等待所設定持續作用時間的 1.5 倍，然後再判斷用戶端是否中斷連線。連線狀態 API 通常會在 IoT Core 判斷裝置的連線狀態變更後一秒內反映這些變更。

1. **高輸送量：**預設支援每秒 350 筆交易 (TPS)，並可依請求調整至更高。

1. **資料保留：**啟用機群索引 (FI) ConnectivityIndexing 模式且未刪除物件時， 會無限期儲存事件資料。如果您停用連線索引，則不會保留記錄。

**注意**  
如果在啟動此 API 之前啟用連線狀態索引，機群索引會在 API 啟動後開始追蹤連線狀態變更，並根據這些變更反映更新的狀態。

## 先決條件
<a name="w2aac37c21c11"></a>

若要使用裝置連線查詢支援：

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)索引

**注意**  
如果您已啟用連線索引，則不需要額外的設定

如需詳細設定說明，請參閱 [AWS IoT 開發人員指南](https://docs.aws.amazon.com/iot/latest/developerguide/setting-up.html)

## 範例
<a name="w2aac37c21c13"></a>

```
aws iot get-thing-connectivity-data --thing-name myThingName
```

```
{
   "connected": true,
   "disconnectReason": "NONE",
   "thingName": "myThingName",
   "timestamp": "2024-12-19T10:00:00.000000-08:00"
}
```
+ `thingName`：請求所指示的裝置名稱。這也符合用來連線的 clientId AWS IoT Core。
+ `disconnectReason`：中斷連線的原因。連線裝置將為 NONE。
+ `connected`：布林值 true 表示此裝置目前已連線。
+ `timestamp`：代表裝置最近中斷連線的時間戳記，以毫秒為單位。

```
aws iot get-thing-connectivity-data --thing-name myThingName
```

```
{
   "connected": false,
   "disconnectReason": "CLIENT_INITIATED_DISCONNECT",
   "thingName": "myThingName",
   "timestamp": "2024-12-19T10:30:00.000000-08:00"
}
```
+ `thingName`：請求所指示的裝置名稱。這也符合用來連線的 clientId AWS IoT Core。
+ `disconnectReason`：中斷連線的原因為 CLIENT\$1INITIATED\$1DISCONNECT，指出用戶端 AWS IoT Core 會中斷連線。
+ `connected`：布林值 false 表示此裝置目前已中斷連線。
+ `timestamp`：代表裝置最近中斷連線的時間戳記，以毫秒為單位。

```
aws iot get-thing-connectivity-data --thing-name neverConnectedThing
```

```
{
   "connected": false,
   "disconnectReason": "UNKNOWN",
   "thingName": "neverConnectedThing"
}
```
+ `thingName`：請求所指示的裝置名稱。這也符合用來連線的 clientId AWS IoT Core。
+ `disconnectReason`：中斷連線的原因。對於從未連線或機群索引未儲存最後中斷連線原因的裝置，將會是「UNKNOWN」。
+ `connected`：布林值 false 表示此裝置目前已中斷連線。
+ `timestamp`：對於從未連線或機群索引未儲存最後一個時間戳記的裝置，不會傳回時間戳記。