建立及讀取 IoT 中樞訊息
為支援不同通訊協定間的流暢互通性,IoT 中樞會定義一組常用傳訊功能,供裝置對應的所有通訊協定使用。 裝置到雲端訊息路由和雲端到裝置訊息皆可使用這些功能。
注意
本文中提及的某些功能 (例如雲端對裝置傳訊、裝置對應項和裝置管理) 僅適用於 IoT 中樞的標準層。 如需有關基本和標準/免費 Azure IoT 中樞階層的詳細資訊,請參閱為您的解決方案選擇適合的 Azure IoT 中樞階層。
IoT 中樞使用串流傳訊模式實作裝置到雲端的傳訊。 IoT 中樞的裝置到雲端訊息與事件中樞事件較為相似 (而不像服務匯流排訊息) 因為會有大量的事件傳遞給該服務,並可由多個讀取器讀取。
IoT 中樞訊息包含:
預先決定的系統屬性集,如下所示。
應用程式屬性集。 應用程式可以定義並存取的字串屬性字典,而不需要還原序列化訊息本文。 IoT 中樞永遠不會修改這些屬性。
訊息本文,可為任何資料類型。
每個裝置通訊協定實作設定屬性的方式不同。 如需詳細資料,請參閱相關的 MQTT 和 AMQP 開發人員指南。
上述屬性名稱和值只能包含 ASCII 英數字元,而且 {'!', '#', '$', '%, '&', ''', '*', '+', '-', '.', '^', '_', '`', '|', '~'}
在您使用 HTTPS 通訊協定傳送裝置到雲端或雲端到裝置的訊息時也是如此。
使用 IoT 中樞進行的裝置到雲端的傳訊具有下列特性:
裝置到雲端訊息會長期保留在 IoT 中樞的預設 messages/events 端點,最多達七天。
裝置到雲端的訊息最多可以有 256 KB,而且可以分組為批次以將傳送最佳化。 批次最多可以有 256 KB。
IoT 中樞不允許任意分割。 裝置到雲端的訊息會根據其來源 deviceId 進行分割。
如控制 IoT 中樞的存取權所述,IoT 中樞會啟用每一裝置的驗證和存取控制。
您可以使用進入應用程式屬性的資訊為訊息加上戳記。 如需詳細資訊,請參閱訊息擴充。
了解如何使用不同通訊協定傳送的訊息編碼和解碼,請參閱 Azure IoT SDK。
注意
每個 IoT 中樞通訊協定皆會提供訊息內容類型屬性;當資料路由傳送至自訂端點時,便會參考此屬性。 若要在目的地正確處理資料 (例如將 JSON 視為可剖析的字串,而不是 Base64 編碼的二進位資料),則須為訊息提供適當的內容類型和字元集。
若要在 IoT 中樞路由查詢中使用訊息本文,則須為訊息提供有效的 JSON 物件,並將訊息的內容類型屬性設為 application/json;charset=utf-8
。
有效、可行的路由訊息本文應類似下例:
{
"timestamp": "2022-02-08T20:10:46Z",
"tag_name": "spindle_speed",
"tag_value": 100
}
D2C IoT 中樞訊息的系統屬性
屬性 | 說明 | 使用者可設定? | 路由查詢 關鍵字 |
---|---|---|---|
message-id | 使用者可針對用於要求-回復模式之訊息設定的識別碼。 格式:區分大小寫的字串,最長為 128 個字元,可使用 ASCII 7 位元英數字元和 {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''} 。 |
Yes | messageId |
iothub-enqueuedtime | IoT 中樞收到裝置到雲端訊息的日期和時間。 | No | enqueuedTime |
user-id | 用來指定訊息來源的識別碼。 當 IoT 中樞產生訊息時,它會設定為 {iot hub name} 。 |
Yes | userId |
iothub-connection-device-id | IoT 中樞在裝置到雲端的訊息上設定的識別碼。 它包含傳送訊息之裝置的 deviceId。 | No | connectionDeviceId |
iothub-connection-module-id | IoT 中樞在裝置到雲端的訊息上設定的識別碼。 它包含傳送訊息之裝置的 moduleId。 | No | connectionModuleId |
iothub-connection-auth-generation-id | IoT 中樞在裝置到雲端的訊息上設定的識別碼。 包含傳送訊息之裝置的 connectionDeviceGenerationId (依據裝置身分識別屬性)。 | No | connectionDeviceGenerationId |
iothub-connection-auth-method | IoT 中樞在裝置到雲端的訊息上設定的驗證方法。 此屬性包含用來驗證傳送訊息之裝置的驗證方法相關資訊。 | No | connectionAuthMethod |
iothub-app-iothub-creation-time-utc | 允許裝置在批次中傳送資料時傳送事件建立時間。 | Yes | creation-time-utc |
iothub-creation-time-utc | 允許裝置在依次傳送一封訊息時傳送事件建立時間。 | Yes | creation-time-utc |
dt-dataschema | 此值是由裝置到雲端訊息上的 IoT 中樞所設定。 其包含裝置連線中設定的裝置型號識別碼。 | No | $dt-dataschema |
dt-subject | 傳送裝置到雲端訊息的元件名稱。 | Yes | $dt-subject |
D2C IoT 中樞訊息的應用程式屬性
應用程式屬性的常見用法是使用 iothub-creation-time-utc
屬性從裝置傳送時間戳記,以便在裝置傳送訊息時進行記錄。 此時間戳記的格式必須是不含時區資訊的 UTC。 例如,2021-04-21T11:30:16Z
為有效,而 2021-04-21T11:30:16-07:00
為無效:
{
"applicationId":"5782ed70-b703-4f13-bda3-1f5f0f5c678e",
"messageSource":"telemetry",
"deviceId":"sample-device-01",
"schema":"default@v1",
"templateId":"urn:modelDefinition:mkuyqxzgea:e14m1ukpn",
"enqueuedTime":"2021-01-29T16:45:39.143Z",
"telemetry":{
"temperature":8.341033560421833
},
"messageProperties":{
"iothub-creation-time-utc":"2021-01-29T16:45:39.021Z"
},
"enrichments":{}
}
C2D IoT 中樞訊息的系統屬性
屬性 | 說明 | 使用者可設定? |
---|---|---|
message-id | 使用者可針對用於要求-回復模式之訊息設定的識別碼。 格式:區分大小寫的字串,最長為 128 個字元,可使用 ASCII 7 位元英數字元和 {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''} 。 |
Yes |
sequence-number | IoT 中樞指派給每個雲端到裝置的訊息的數字 (每個 device-queue 都是唯一的)。 | No |
打給 | 雲端到裝置 訊息中指定的目的地。 | No |
absolute-expiry-time | 訊息到期的日期和時間。 | Yes |
correlation-id | 回應訊息中的字串屬性,通常包含要求的 MessageId,其模式為要求-回復。 | Yes |
user-id | 用來指定訊息來源的識別碼。 當 IoT 中樞產生訊息時,它會設定為 {iot hub name} 。 |
Yes |
iothub-ack | 意見反應訊息產生器。 此屬性用於雲端到裝置的訊息,以要求 IoT 中樞產生意見反應訊息 (由於裝置取用訊息的結果)。 可能的值:none (預設值):不產生任何意見反應訊息、positive:如果訊息已完成,則接收意見反應訊息、negative:如果訊息已過期 (或達到傳遞計數上限),則接收意見反應訊息,而不會由裝置完成,或 full:positive 與 negative。 | Yes |
系統屬性名稱
系統屬性名稱會根據路由傳送訊息的目標端點而有所不同。 如需這些名稱的詳細資訊,請參閱下表。
系統屬性名稱 | 事件中樞 | Azure 儲存體 | 服務匯流排 | 事件方格 |
---|---|---|---|---|
訊息 ID | message-id | messageId | MessageId | message-id |
使用者識別碼 | user-id | userId | UserId | user-id |
Connection device id | iothub-connection-device-id | connectionDeviceId | iothub-connection-device-id | iothub-connection-device-id |
Connection module id | iothub-connection-module-id | connectionModuleId | iothub-connection-module-id | iothub-connection-module-id |
Connection auth generation id | iothub-connection-auth-generation-id | connectionDeviceGenerationId | iothub-connection-auth-generation-id | iothub-connection-auth-generation-id |
Connection auth method | iothub-connection-auth-method | connectionAuthMethod | iothub-connection-auth-method | iothub-connection-auth-method |
contentType | Content-Type | contentType | ContentType | iothub-content-type |
contentEncoding | content-encoding | contentEncoding | ContentEncoding | iothub-content-encoding |
iothub-enqueuedtime | iothub-enqueuedtime | enqueuedTime | N/A | iothub-enqueuedtime |
CorrelationId | correlation-id | correlationId | CorrelationId | correlation-id |
dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema |
dt-subject | dt-subject | dt-subject | dt-subject | dt-subject |
訊息大小
IoT 中樞以與通訊協定無關的方式測量訊息大小,只考慮實際承載。 以位元組為單位的大小會以下列值的總和計算:
- 本文大小 (以位元組為單位)。
- 訊息系統屬性之所有值的大小 (以位元組為單位)。
- 所有使用者屬性名稱與值的大小 (以位元組為單位)。
屬性名稱與值限制為 ASCII 字元,因此字串的長度等於位元組大小。
反詐騙屬性
為避免裝置到雲端的訊息中的裝置詐騙,IoT 中樞會為具有下列屬性的所有訊息加上戳記:
- iothub-connection-device-id
- iothub-connection-auth-generation-id
- iothub-connection-auth-method
前兩個屬性包含來源裝置的 deviceId 和 generationId (依據裝置身分識別屬性)。
iothub-connection-auth-method 屬性包含 JSON 已序列化物件,其具有下列屬性:
{
"scope": "{ hub | device | module }",
"type": "{ symkey | sas | x509 }",
"issuer": "iothub"
}
下一步
- 如需 IoT 中樞訊息大小限制的資訊,請參閱 IoT 中樞配額和節流。
- 若要了解如何以各種程式設計語言建立及讀取 IoT 中樞訊息,請參閱快速入門。
- 若要了解 IoT 中樞所產生的非遙測事件結構,請參閱 IoT 中樞非遙測事件結構描述。
意見反映
https://aka.ms/ContentUserFeedback。
即將推出:我們會在 2024 年淘汰 GitHub 問題,並以全新的意見反應系統取代並作為內容意見反應的渠道。 如需更多資訊,請參閱:提交及檢視以下的意見反映: