共用方式為

建立及讀取 IoT 中樞訊息

  • 發行項

為了支援通訊協議之間的互操作性，IoT 中樞 定義適用於所有裝置對應通訊協定的一組通用傳訊功能。 這些功能可用於 裝置到雲端訊息 和 雲端到裝置訊息。

注意

本文中提及的某些功能 (例如雲端對裝置傳訊、裝置對應項和裝置管理) 僅適用於 IoT 中樞的標準層。 如需有關基本和標準/免費 Azure IoT 中樞階層的詳細資訊，請參閱為您的解決方案選擇適合的 Azure IoT 中樞階層。

IoT 中樞使用串流傳訊模式實作裝置到雲端的傳訊。 IoT 中樞的裝置到雲端訊息更像事件中樞事件比 服務匯流排 訊息中，有大量事件通過多個讀取器可以讀取的服務傳遞。

IoT 中樞訊息包含：

  • 如本文稍後所述，預先決定的系統 屬性 集。

  • 應用程式屬性集。 應用程式可以定義並存取的字串屬性字典，而不需要還原序列化訊息本文。 IoT 中樞永遠不會修改這些屬性。

  • 訊息本文，可為任何資料類型。

每個裝置通訊協定實作設定屬性的方式不同。 如需詳細資訊，請參閱 MQTT 通訊協定指南 和 AMQP 通訊協定指南開發人員指南 以取得詳細數據。

當您使用 HTTPS 通訊協定傳送裝置到雲端訊息或傳送雲端到裝置訊息時，屬性名稱和值只能包含 ASCII 英數位元，加上 ! # $ % & ' * + - . ^ _ ` | ~ 。

使用 IoT 中樞進行的裝置到雲端的傳訊具有下列特性：

  • 裝置到雲端訊息會長期保留在 IoT 中樞的預設 messages/events 端點，最多達七天。

  • 裝置到雲端的訊息最多可以有 256 KB，而且可以分組為批次以將傳送最佳化。 批次最多可以有 256 KB。

  • IoT 中樞 不允許任意分割。 裝置到雲端的訊息會根據其來源 deviceId 進行分割。

  • 如控制 IoT 中樞的存取權所述，IoT 中樞會啟用每一裝置的驗證和存取控制。

  • 您可以使用進入應用程式屬性的資訊為訊息加上戳記。 如需詳細資訊，請參閱訊息擴充。

注意

每個 IoT 中樞通訊協定皆會提供訊息內容類型屬性；當資料路由傳送至自訂端點時，便會參考此屬性。 若要在目的地正確處理您的資料 (例如，將 JSON 視為可剖析字串，而不是 Base64 編碼的二進位資料)，您必須為訊息提供適當的內容類型和字元集。

若要在 IoT 中樞路由查詢中使用訊息本文，您必須為訊息提供有效的 JSON 物件，並將訊息的內容類型屬性設定為 application/json;charset=utf-8。

下列範例顯示有效的可路由傳送訊息本文：

{
    "timestamp": "2022-02-08T20:10:46Z",
    "tag_name": "spindle_speed",
    "tag_value": 100
}

裝置到雲端訊息的系統屬性

屬性 說明 使用者可設定？ 路由查詢
關鍵字
message-id 使用者可針對用於要求-回復模式之訊息設定的識別碼。 格式：ASCII 7 位英數位元加上 - : . + % _ # * ? ! ( ) , = @ ; $ '的區分大小寫字串（最多 128 個字元長）。 Yes messageId
iothub-enqueuedtime IoT 中樞收到裝置到雲端訊息的日期和時間。 No enqueuedTime
user-id 用來指定訊息來源的識別碼。 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

裝置到雲端訊息的應用程式屬性

應用程式屬性的常見用法是使用 iothub-creation-time-utc 屬性從裝置傳送時間戳記，以便在裝置傳送訊息時進行記錄。 此時間戳記的格式必須是不含時區資訊的 UTC。 例如，2021-04-21T11:30:16Z 有效，但 2021-04-21T11:30:16-07:00 無效。

{
  "applicationId":"00001111-aaaa-2222-bbbb-3333cccc4444",
  "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":{}
}

雲端到裝置訊息的系統屬性

屬性 說明 使用者可設定？
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中樞名稱。 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"
}

下一步