Share via

MQTT 用戶端生命週期事件

  • 發行項

用戶端生命週期事件可讓應用程式回應用戶端連線狀態或用戶端資源作業的相關事件。 這可讓您：

  • 監視用戶端的連線狀態。 例如，您可以建置相關應用程式來分析用戶端的連線，以達到最佳行為。
  • 以風險降低動作因應用戶端中斷連線。 例如，您可以建置會在每次用戶端中斷連線時起始自動風險降低流程或建立支援票證的應用程式。
  • 追蹤用戶端連結到的命名空間。 例如，在您起始容錯移轉後，確認用戶端連線至正確的命名空間。

事件類型

事件方格命名空間會發佈下列事件類型：

事件類型 說明
Microsoft.EventGrid.MQTTClientSessionConnected 在 MQTT 用戶端的工作階段連線至事件方格時發佈。
Microsoft.EventGrid.MQTTClientSessionDisconnected 在 MQTT 用戶端的工作階段與事件方格中斷連線時發佈。
Microsoft.EventGrid.MQTTClientCreatedOrUpdated 在事件方格命名空間中建立或更新 MQTT 用戶端時發佈。
Microsoft.EventGrid.MQTTClientDeleted 從事件方格命名空間中刪除 MQTT 用戶端時發佈。

結構描述

用戶端生命週期事件會為您提供關於已連線或中斷連線的用戶端和工作階段的所有資訊。 此外也提供一個可用於診斷案例的 disconnectionReason，因為藉此您可以自動執行緩解動作。

此範例事件顯示當 MQTT 用戶端的工作階段連線至事件方格時引發的事件結構描述：

[{
  "specversion": "1.0",
  "id": "5249c38a-a048-46dd-8f60-df34fcdab06c",
  "time": "2023-07-29T01:23:49.6454046Z",
  "type": "Microsoft.EventGrid.MQTTClientSessionConnected",
  "source": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myrg/providers/Microsoft.EventGrid/namespaces/myns",
  "subject": "clients/client1/sessions/session1",
  "data": {
    "namespaceName": "myns",
    "clientAuthenticationName": "client1",
    "clientSessionName": "session1",
    "sequenceNumber": 1
  }
}]

此範例事件顯示當 MQTT 用戶端的工作階段與事件方格中斷連線時引發的事件結構描述：

[{
  "specversion": "1.0",
  "id": "e30e5174-787d-4e19-8812-580148bfcf7b",
  "time": "2023-07-29T01:27:40.2446871Z",
  "type": "Microsoft.EventGrid.MQTTClientSessionDisconnected",
  "source": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myrg/providers/Microsoft.EventGrid/namespaces/myns",
  "subject": "clients/client1/sessions/session1",
  "data": {
    "namespaceName": "myns",
    "clientAuthenticationName": "client1",
    "clientSessionName": "session1",
    "sequenceNumber": 1,
    "disconnectionReason": "ClientInitiatedDisconnect"
  }
}]

此範例事件顯示在事件方格命名空間中建立或更新 MQTT 用戶端時引發的事件結構描述：

[{
  "specversion": "1.0",
  "id": "383d1562-c95f-4095-936c-688e72c6b2bb",
  "time": "2023-07-29T01:14:35.8928724Z",
  "type": "Microsoft.EventGrid.MQTTClientCreatedOrUpdated",
  "source": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myrg/providers/Microsoft.EventGrid/namespaces/myns",
  "subject": "clients/client1",
  "data": {
    "createdOn": "2023-07-29T01:14:34.2048108Z",
    "updatedOn": "2023-07-29T01:14:34.2048108Z",
    "namespaceName": "myns",
    "clientName": "client1",
    "clientAuthenticationName": "client1",
    "state": "Enabled",
    "attributes": {
      "attribute1": "value1"
    }
  }
}]

此範例事件顯示從事件方格命名空間中刪除 MQTT 用戶端時引發的事件結構描述：

[{
  "specversion": "1.0",
  "id": "2a93aaf9-66c2-4f8e-9ba3-8d899c10bf17",
  "time": "2023-07-29T01:30:52.5620566Z",
  "type": "Microsoft.EventGrid.MQTTClientDeleted",
  "source": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myrg/providers/Microsoft.EventGrid/namespaces/myns",
  "subject": "clients/client1",
  "data": {
    "namespaceName": "myns",
    "clientName": "client1",
    "clientAuthenticationName": "client1"
  }
}]

中斷連線原因：

下列清單詳細說明 disconnectionReason 的不同值及其描述：

中斷連線原因 描述
ClientAuthenticationError 用戶端因任何驗證原因而中斷連線 (例如憑證過期、用戶端已停用或用戶端設定已變更)
ClientAuthorizationError 用戶端因任何授權原因而中斷連線 (例如，因為主題空間、權限繫結或用戶端群組的設定有所變更)
ClientError 用戶端傳送了不正確的要求，或使用了其中一個導致服務終止連線的不支援功能。
ClientInitiatedDisconnect 用戶端透過 MQTT 的 DISCONNECT 封包或透過 WebSocket 的 MQTT 關閉框架，起始正常中斷連線。
ConnectionLost 用戶端-伺服器連線中斷。
IpForbidden 用戶端的 IP 位址遭到 IP 篩選或私人連結設定封鎖。
QuotaExceeded 用戶端超過一或多個節流限制，導致服務終止連線。
ServerError 連線因為未預期的伺服器錯誤而終止
ServerInitiatedDisconnect 伺服器因任何操作原因而起始正常中斷連線
SessionOverflow 未認可 QoS1 訊息的用戶端佇列達到其限制，導致伺服器終止連線
SessionTakenOver 用戶端以相同的驗證名稱重新連線，導致上一個連線終止。

如需每個屬性的詳細描述，請參閱事件方格命名空間的事件結構描述。

提示

處理連線狀態的高波動率：收到用戶端中斷連線事件時，請等候一段時間 (例如 30 秒) 並確認用戶端仍處於離線，再採取緩解動作。 在處理快速變動的狀態時，此最佳化可提升效率。

組態

Azure 入口網站設定

使用下列步驟發出用戶端生命週期事件：

  1. 在命名空間中，移至 [事件] 索引標籤。
  2. 選取 [+事件訂用帳戶]。
    • 提供事件方格訂用帳戶的名稱。
    • 選取您想要用於事件取用的事件結構描述。
    • 篩選 [事件類型] 底下的事件。
    • 填入您的端點詳細資料。
  3. 選取 建立。

Azure CLI 設定

使用下列步驟發出用戶端生命週期事件：

  1. 建立系統主題
az eventgrid system-topic create --resource-group <Resource Group > --name <System Topic Name> --location \<Region> --topic-type Microsoft.EventGrid.Namespaces --source /subscriptions//resourceGroups/<Resource Group >/providers/Microsoft.EventGrid/namespaces/<Namespace Name>
  1. 建立事件方格訂用帳戶
  az eventgrid system-topic event-subscription create --name <Specify Event Subscription Name> -g <Resource Group> --system-topic-name <System Topic Name> --endpoint <Endpoint>

行為：

  • 用戶端生命週期事件沒有延遲保證。 用戶端連線狀態事件會指出用戶端工作階段連線的上次報告狀態，而不是即時連線狀態。
  • 有可能發佈重複的用戶端生命週期事件。
  • 用戶端生命週期事件的時間戳記會指出服務偵測到事件的時間，這可能與事件的實際時間不同。
  • 不保證用戶端生命週期事件的順序，事件可能不會依序到達。 不過，連線狀態事件的序號可用來判斷事件的原始順序。
  • 對於「用戶端已建立或更新」事件和「用戶端已刪除」事件：
    • 如果用戶端資源在短時間內有多次狀態變更，則會針對用戶端的最終狀態發出一個事件。
    • 範例 1：如果用戶端建立後在 3 秒內更新了兩次，EG 只會發出一個 MQTTClientCreatedOrUpdated 事件，其中包含用戶端中繼資料的最終值。
    • 範例 2：如果用戶端建立後在 5 秒內遭到刪除，則 EG 只會發出 MQTTClientDeleted 事件。

排序連線狀態事件：

MQTTClientSessionConnected 和 MQTTClientSessionDisconnected 事件的序號可用來判斷用戶端工作階段連線的上次報告狀態，因為序號會隨著每個新事件遞增。 MQTTClientSessionDisconnected 的序號一律與相同連線的 MQTTClientSessionConnected 事件的序號相符。 例如，下列事件和序號是相同用戶端依正確順序排列的事件範例：

  • MQTTClientSessionConnected > "sequenceNumber": 1
  • MQTTClientSessionDisconnected > "sequenceNumber": 1
  • MQTTClientSessionConnected > "sequenceNumber": 2
  • MQTTClientSessionDisconnected > "sequenceNumber": 2

以下是排序事件的範例邏輯：針對每個用戶端：

  • 儲存第一個事件的序號和連線狀態。
  • 針對每個新的 MQTTClientSessionConnected 事件：
    • 如果新序號大於舊序號，則更新序號和連線狀態以符合新事件。
  • 針對每個新的 MQTTClientSessionDisconnected 事件：
    • 如果新序號大於或等於舊序號，則更新序號和連線狀態以符合新事件。

下一步