建立和讀取 IoT 中樞 訊息
為了支援跨通訊協定的無縫互操作性，IoT 中樞 定義所有裝置面向通訊協定中可用的一組通用傳訊功能。 這些可用於 裝置到雲端訊息路由 和 雲端到裝置訊息。
注意
本文所述的一些功能，例如雲端到裝置傳訊、裝置對應項和裝置管理，僅適用於標準層 IoT 中樞。 如需基本和標準/免費 IoT 中樞 層的詳細資訊，請參閱為您的解決方案選擇正確的 IoT 中樞 層。
IoT 中樞使用串流傳訊模式實作裝置到雲端的傳訊。 IoT 中樞的裝置到雲端訊息更像事件中樞事件比 服務匯流排 訊息中，有大量事件通過服務，可供多個讀取器讀取。
IoT 中樞訊息包含：
預先決定的系統屬性集，如下所示。
應用程式屬性集。 應用程式可以定義並存取的字串屬性字典，而不需要還原序列化訊息本文。 IoT 中樞永遠不會修改這些屬性。
訊息本文，其可以是任何類型的資料。
每個裝置通訊協定會以不同的方式實作設定屬性。 如需詳細資訊，請參閱相關的 MQTT 和 AMQP 開發人員指南。
屬性名稱和值只能包含 ASCII 英數位元，以及 {'!', '#', '$', '%, '&', ''', '*', '+', '-', '.', '^', '_', '`', '|', '~'} 當您使用 HTTPS 通訊協定傳送裝置到雲端訊息或傳送雲端到裝置訊息時。
使用 IoT 中樞進行的裝置到雲端的傳訊具有下列特性：
裝置到雲端訊息在IoT中樞的預設 訊息/事件 端點中保留最多七天。
裝置到雲端的訊息最多可以有 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 | 使用者可針對用於要求-回復模式之訊息設定的識別碼。 格式：ASCII 7 位英數位元 + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}的區分大小寫字串（長度最多 128 個字元）。 |
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 | 使用者可針對用於要求-回復模式之訊息設定的識別碼。 格式：ASCII 7 位英數位元 + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}的區分大小寫字串（長度最多 128 個字元）。 |
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 儲存體 | 服務匯流排 | Event Grid |
|---|---|---|---|---|
| 訊息 ID | message-id | messageId | MessageId | message-id |
| 使用者識別碼 | user-id | userId | UserId | user-id |
| 連線 ion 裝置識別碼 | iothub-connection-device-id | connectionDeviceId | iothub-connection-device-id | iothub-connection-device-id |
| 連線 ion 模組識別碼 | iothub-connection-module-id | connectionModuleId | iothub-connection-module-id | iothub-connection-module-id |
| 連線 ion 驗證產生識別碼 | 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 中樞 非遙測事件架構。