View a markdown version of this page

裝置連線狀態查詢 - AWS IoT Core
運作方式功能優勢先決條件範例

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

裝置連線狀態查詢

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

運作方式

裝置連線查詢支援可用於最佳化的單一裝置連線狀態擷取。此 API 提供最新裝置特定連線資訊的低延遲、高輸送量存取。啟用連線索引後，您將可以存取此查詢 API，並以標準查詢收費。如需詳細資訊，請參閱 AWS IoT Device Management 定價

功能

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

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

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

    1. 中斷連線原因

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

    3. 工作階段資訊，包括持續作用持續時間

    4. 通訊端層級工作階段資訊，包括 IP 地址、連接埠和 VPC 端點 ID。只有在符合下列條件時，才能使用此資訊：

      1. 您可以在機群索引組態設定中啟用此選項。

      2. 叫用 API 時，您在 IAM 政策中具有對應的許可。

注意

機群索引會為裝置的連線狀態建立索引，其連線 clientId 與登錄中已註冊物件的 thingName 相同。

優勢

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

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

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

注意

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

先決條件

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

  1. 設定 AWS 帳戶

  2. 在您 AWS IoT Core 偏好的區域中，將裝置加入並註冊至

  3. 使用連線索引啟用機群索引。選用：透過啟用 includeSocketInformation選項選擇接收通訊端層級資訊。

注意

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

如需詳細設定說明，請參閱 AWS 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：在 AWS IoT 登錄檔中註冊的裝置名稱。這必須符合clientId用於連線至 AWS IoT Core 的 。

  • includeSocketInformation： includeSocketInformation 參數控制通訊端層級網路資訊是否包含在 API 回應中。設定為 true 時，回應會包含下列欄位：sourceIp, sourcePort, targetIp, targetPort, vpcEndpointId。當 includeSocketInformation 未指定或設定為 false 時，這些通訊端欄位會從回應中排除。若要限制特定 IAM 使用者存取通訊端資訊，您需要將includeSocketInformation條件索引鍵設定為 false，以在 IAM 政策中指定此資訊

回應欄位

  • thingName：在 AWS IoT 登錄檔中註冊的裝置名稱。這必須符合clientId用於連線至 AWS IoT Core 的 。

  • connected：布林值 true 表示此裝置目前已連線。

  • disconnectReason：中斷連線的原因。將NONE適用於已連線的裝置，以及從未連線UNKNOWN的裝置。對於中斷連線的裝置，這將指出中斷連線是用戶端啟動、伺服器啟動、身分驗證/授權問題還是網路問題。如需中斷連線原因代碼，請參閱 LifeCycleEvents

  • timestamp：代表裝置最近連線或中斷連線事件的時間戳記。

  • clientId：MQTT 用戶端的 clientId。

  • 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" 
      } 
    } 
  }] 
}