建立及讀取 IoT 中樞訊息

發行項
06/13/2024

為支援不同通訊協定間的流暢互通性，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 中樞非遙測事件結構描述。

共用方式為