共用方式為

建立及讀取 IoT 中樞訊息

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

附註

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

IoT 中樞使用串流訊息模式實作裝置到雲端傳訊。 IoT 中樞的從裝置到雲端的訊息更像是事件中樞事件，而不是服務總線訊息，因為有大量事件通過此服務，並可供多個讀取器讀取。

IoT 中樞訊息包含：

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

  • 一組 應用程式屬性。 應用程式可以定義的字串屬性字典，而且不需將訊息本文還原序列化即可加以存取。 IoT 中樞不會修改這些屬性。

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

每個裝置通訊協定實作設定屬性的方式不同。 如需詳細資訊，請參閱 使用 MQTT 通訊協定與 IoT 中樞通訊 和使用 AMQP 通訊協定與 IoT 中樞通訊。

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

IoT 中樞的裝置對雲端傳訊具有下列特性：

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

  • 裝置到雲端訊息最多可以 256 KB，而且可以分批分組以優化傳送。 批次最多可達 256 KB。

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

  • 如 使用 Microsoft Entra ID 控制 IoT 中樞的存取中所述，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
}

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

屬性 描述 使用者可設定？ 路由查詢
關鍵字
訊息識別碼 使用者可設定的訊息識別碼，用於「要求-回覆」模式。 格式：ASCII 7 位英數字元加上 - : . + % _ # * ? ! ( ) , = @ ; $ ' 的區分大小寫字串 (最多 128 個字元長)。 是的 訊息ID
iothub-enqueuedtime IoT 中樞接收 裝置到雲端 訊息的日期和時間。 否 enqueuedTime
用戶ID 用來指定訊息來源的識別碼。 是的 使用者ID
iothub-connection-device-id 由 IoT 中樞在裝置到雲端訊息上設定的識別碼。 它包含傳送訊息之裝置的 deviceId 。 否 connectionDeviceId
iothub-connection-module-id（IoT Hub連線模組識別碼） 由 IoT 中樞在裝置到雲端訊息上設定的識別碼。 包含傳送訊息之裝置的 moduleId 。 否 連接模組ID
iothub-connection-auth-generation-id 由 IoT 中樞在裝置到雲端訊息上設定的識別碼。 包含傳送訊息之裝置的 connectionDeviceGenerationId (依據裝置身分識別屬性)。 否 連接裝置生成ID
iothub-connection-auth-method 由 IoT 中樞在裝置到雲端訊息上設定的驗證方法。 這個屬性包含用來驗證傳送訊息之裝置的驗證方法的相關資訊。 否 connectionAuthMethod
iothub-app-iothub-creation-time-utc (創建時間-UTC) 允許裝置在批次中傳送資料時傳送事件建立時間。 是的 創建時間-UTC
iothub-creation-time-utc 允許裝置在依次傳送一封訊息時傳送事件建立時間。 是的 creation-time-utc
dt-資料架構 IoT 中樞會在裝置到雲端訊息上設定此值。 包含裝置連線中所設定的裝置模型識別碼。 否 $dt-dataschema
dt-subject 傳送裝置到雲端訊息的元件名稱。 是的 $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":{}
}

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

屬性 描述 使用者可設定？
訊息識別碼 使用者可設定的訊息識別碼，用於「要求-回覆」模式。 格式：ASCII 7 位英數字元加上 - : . + % _ # * ? ! ( ) , = @ ; $ ' 的區分大小寫字串 (最多 128 個字元長)。 是的
序列號 IoT 中樞指派給每則雲端到裝置訊息的數字 (對每個裝置佇列而言都是唯一的)。 否
to 雲端到裝置訊息中指定的目的地。 否
絕對到期時間 訊息到期的日期和時間。 是的
關聯識別碼 回應訊息中的字串屬性，通常包含採用「要求-回覆」模式之要求的 MessageId。 是的
用戶ID 用來指定訊息來源的識別碼。 當IoT中樞產生訊息時，使用者標識碼是IoT中樞名稱。 是的
iothub-ack 意見反應訊息產生器。 這個屬性是在雲端到裝置訊息中使用，可要求 IoT 中樞因為裝置取用訊息而產生意見反應訊息。 可能的值︰none (預設值)︰不會產生任何意見反應訊息；positive︰如果訊息已完成，則會收到意見反應訊息；negative︰如果訊息未由裝置完成就到期 (或已達到最大傳遞計數) 則會收到意見反應訊息；或者 full︰positive 和 negative。 是的

系統屬性名稱

系統屬性名稱會根據路由傳送訊息的目標端點而有所不同。

系統屬性名稱 事件中樞 Azure 儲存體 服務匯流排 事件方格
訊息 ID 訊息識別碼 訊息ID 訊息編號 訊息識別碼
User id 用戶ID 使用者ID UserId 用戶ID
連接裝置識別碼 iothub-connection-device-id connectionDeviceId iothub-connection-device-id iothub-connection-device-id
連接模組識別碼 iothub-connection-module-id 連接模組ID "IoT中樞連接模組識別碼" IoTHub-連接模組ID
Connection auth generation id iothub-connection-auth-generation-id connectionDeviceGenerationId iothub-connection-auth-generation-id iothub-connection-auth-generation-id
連接驗證方法 iothub-connection-auth-method connectionAuthMethod iothub-connection-auth-method iothub-connection-auth-method
內容類型 Content-Type 內容類型 內容類型 iothub-content-type
contentEncoding 內容編碼 (content-encoding) contentEncoding 內容編碼 iothub-內容編碼
iothub-enqueuedtime iothub-enqueuedtime enqueuedTime N/A iothub-enqueuedtime
CorrelationId 關聯識別碼 correlationId CorrelationId 關聯識別碼
dt-dataschema dt-數據結構 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（IoT中心連接身份驗證方法）

前兩個屬性包含來源裝置的 deviceId 和 generationId (依據裝置身分識別屬性)。

iothub-connection-auth-method 屬性包含具有下列屬性的 JSON 序列化物件︰

{
  "scope": "{ hub | device | module }",
  "type": "{ symkey | sas | x509 }",
  "issuer": "iothub"
}

後續步驟

  • Last updated on