IoT 中樞資料連線

發行項
02/07/2024

Azure IoT 中樞是裝載於雲端的受控服務，可作為IoT應用程式與其所管理裝置之間雙向通訊的中央訊息中樞。 Azure Data Explorer 會使用其與裝置到雲端訊息的內建端點相容的事件中樞，從客戶管理的 IoT 中樞持續擷取。

IoT 擷取管線會經歷數個步驟。首先，您會建立 IoT 中樞，併為其註冊裝置。接著，您會在 Azure Data Explorer 中建立目標數據表，其中特定格式的數據將會使用指定的擷取屬性來擷取。 IoT 中樞連線必須知道事件路由，才能連線到 Azure Data Explorer 數據表。資料會根據事件系統屬性對應，以選取的屬性進行內嵌。您可以透過 Azure 入口網站、使用 C# 或 Python 以程式設計方式，或使用 Azure Resource Manager 範本來管理此程序。

如需 Azure Data Explorer 中數據擷取的一般資訊，請參閱 Azure Data Explorer 數據擷取概觀。

資料格式

數據會以 EventData 物件的形式從事件中樞端點讀取。
請參閱支援的格式。

注意

IoT 中樞不支援.raw格式。
請參閱支援的壓縮。

內嵌屬性

擷取屬性會指示擷取程式在何處路由數據，以及如何處理數據。您可以使用 EventData.Properties 來指定事件的擷取屬性。您可以設定下列屬性：

屬性	描述
資料庫	名稱 (目標資料庫的區分大小寫) 。如果您想要將數據傳送至與建立數據連線的資料庫不同的資料庫， (默認資料庫) ，可以使用此屬性。若要將數據路由傳送至多個資料庫，您必須先將連線設定為多資料庫連線。如需詳細資訊，請參閱事件路由。
資料表	現有目標資料表的名稱 (區分大小寫)。覆寫 `Data Connection` 窗格上的 `Table` 集。
格式	資料格式覆寫 `Data Connection` 窗格上的 `Data format` 集。
IngestionMappingReference	要使用的現有內嵌對應名稱。覆寫 `Data Connection` 窗格上的 `Column mapping` 集。
編碼	資料編碼，預設值為 UTF8。可為任何 .NET 支援的編碼。

注意

只會內嵌在建立資料連線之後排入佇列的事件。

事件路由

當您建立叢集的數據連線時，您可以指定傳送內嵌數據的路由。預設路由是與目標資料庫相關聯的連接字串中指定的目標數據表。數據的預設 路由也稱為靜態路由。您可以使用事件資料屬性來指定資料的替代路由。

將事件數據路由傳送至替代資料庫

默認會關閉將數據路由傳送至替代資料庫。若要將數據傳送至不同的資料庫，您必須先將連接設定為多資料庫連線。如需如何在 Azure 入口網站中執行這項操作的範例，請參閱開啟多資料庫路由。用來允許資料庫路由的使用者、群組、服務主體或受控識別至少必須具有叢集的 參與者 角色和寫入許可權。

若要指定替代資料庫，請設定 資料庫擷取屬性。

警告

指定替代資料庫而不將連線設定為多資料庫數據聯機會導致擷取失敗。

開啟多資料庫路由

您必須先允許將數據路由傳送至多個資料庫，才能設定替代目標資料庫。使用下列步驟來允許將資料路由傳送至替代資料庫：

在 Azure 入口網站中，流覽至您的叢集。
選取 [資料庫>數據連線]。
建立或編輯數據連線，然後在 [ 數據連線 ] 窗格的 [ 數據路由設定] 底下，開啟 [允許將數據路由至其他資料庫] (多資料庫數據連線) 選項。

將事件數據路由傳送至替代數據表

您也可以使用事件屬性，為每個事件指定目標資料表屬性。連線會動態路由 EventData.Properties 中指定的資料，並覆寫這個事件的靜態屬性。若要指定替代數據表，請設定 Table擷取屬性。

注意

如果 [我的數據] 包含選取的路由資訊 ，您必須在事件屬性中提供必要的路由資訊。

事件系統屬性對應

系統屬性是用來儲存 IoT 中樞服務在收到事件時所設定之屬性的集合。 Azure Data Explorer IoT 中樞聯機會將選取的屬性內嵌在數據表的數據登陸中。

注意

針對 csv 對應，屬性會依照下表所列的順序，在記錄的開頭加入。針對 json 對應，會根據下表中的屬性名稱來新增屬性。

系統屬性

IoT 中樞公開下列裝置到雲端 IoT 中樞訊息的系統屬性：

屬性	Description
message-id	使用者可設定的訊息識別碼，用於「要求-回覆」模式。格式：區分大小寫的字串，最長為 128 個字元，可使用 ASCII 7 位元英數字元和 `{'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}`。
iothub-enqueuedtime	IoT 中樞收到裝置到雲端訊息的日期和時間。
user-id	用來指定訊息來源的識別碼。當訊息由 IoT 中樞產生時，此值會設定為 `{iot hub name}`。
iothub-connection-device-id	由 IoT 中樞在裝置到雲端訊息上設定的識別碼。它包含傳送訊息之裝置的 deviceId 。
iothub-connection-module-id	由 IoT 中樞在裝置到雲端訊息上設定的識別碼。包含傳送訊息之裝置的 moduleId 。
iothub-connection-auth-generation-id	由 IoT 中樞在裝置到雲端訊息上設定的識別碼。包含傳送訊息之裝置的 connectionDeviceGenerationId (依據裝置身分識別屬性)。
iothub-connection-auth-method	由 IoT 中樞在裝置到雲端訊息上設定的驗證方法。這個屬性包含用來驗證傳送訊息之裝置的驗證方法的相關資訊。
iothub-app-iothub-creation-time-utc	允許裝置在批次中傳送資料時傳送事件建立時間。
iothub-creation-time-utc	允許裝置在依次傳送一封訊息時傳送事件建立時間。
dt-dataschema	此值是由裝置到雲端訊息上的 IoT 中樞所設定。其包含裝置連線中設定的裝置型號識別碼。
dt-subject	傳送裝置到雲端訊息的元件名稱。

如果您在資料表的 [資料來源] 區段中選取了 [事件系統屬性]，則必須在資料表結構描述和對應中包含屬性。

結構描述對應範例

資料表結構描述對應範例

如果您的資料包含三個資料行 (Timespan、Metric 和 Value) 且您包含的屬性為 iothub-connection-device-id 和 sequence-number，請使用下列命令來建立或修改資料表結構描述：

    .create-merge table TestTable (TimeStamp: datetime, Metric: string, Value: int, IotHubDeviceId:long, IotHubSequenceNumber:long)

CSV 對應範例

執行下列命令，以將資料新增至記錄的開頭。請注意序數值。

    .create table TestTable ingestion csv mapping "CsvMapping1"
    '['
    '   { "column" : "TimeStamp", "Properties":{"Ordinal":"2"}},'
    '   { "column" : "Metric", "Properties":{"Ordinal":"3"}},'
    '   { "column" : "Value", "Properties":{"Ordinal":"4"}},'
    '   { "column" : "IotHubDeviceId", "Properties":{"Ordinal":"0"}},'
    '   { "column" : "IotHubSequenceNumber", "Properties":{"Ordinal":"1"}}'
    ']'

JSON 對應範例

使用系統屬性對應來新增資料。執行下列命令：

    .create table TestTable ingestion json mapping "JsonMapping1"
    '['
    '    { "column" : "TimeStamp", "Properties":{"Path":"$.timestamp"}},'
    '    { "column" : "Metric", "Properties":{"Path":"$.metric"}},'
    '    { "column" : "Value", "Properties":{"Path":"$.metric_value"}},'
    '    { "column" : "IotHubDeviceId", "Properties":{"Path":"$.iothub-connection-device-id"}},'
    '    { "column" : "IotHubSequenceNumber", "Properties":{"Path":"$.sequence-number"}}'
    ']'

事件使用者屬性對應

不支援使用使用者屬性擴充 IoT 中樞事件承載。請考慮在事件主體上游內嵌用戶屬性。

IoT 中樞連線

注意

為了獲得最佳效能，請在與 Azure Data Explorer 叢集相同的區域中建立所有資源。

建立 IoT 中樞

如果您還沒有，請建立IoT中樞。 IoT 中樞的連線可以透過 Azure 入口網站、以程式設計方式使用 C# 或 Python 或 Azure Resource Manager 範本來管理。

注意

計數 device-to-cloud partitions 無法變更，因此設定分割區計數時，您應該考慮長期調整。
每個取用者的取用者群組必須是唯一的。建立專用於 Azure Data Explorer 連線的取用者群組。在 Azure 入口網站中尋找您的資源，然後移至 Built-in endpoints 以新增取用者群組。
資料聯機會使用 IoT 中樞 Built-in endpoint。如果您設定任何其他 Message routing endpoint，除非路由建立至該端點，否則訊息會停止流向 Built-in endpoint 。若要確保新增新的路由時，訊息會繼續流向內建端點，請設定端點的 events 路由。如需詳細資訊，請參閱 IoT 中樞針對訊息路由進行疑難解答。

傳送事件

請參閱模擬裝置併產生數據的範例專案。

後續步驟

建立 IoT 中樞數據連線