IoT 中樞資料連線

2024-07-03

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

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

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

資料格式

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

注意

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

內嵌屬性

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

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

注意

只有在您建立數據連線之後才會加入佇列的事件才會內嵌。

事件路由

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

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

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

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

警告

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

開啟多資料庫路由

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

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

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

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

注意

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

事件系統屬性對應

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

注意

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

系統屬性

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

屬性	說明
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 數據總管叢集相同的區域中建立所有資源。

建立 IoT 中樞

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

注意

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

傳送事件

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

後續步驟

建立 IoT 中樞數據連線