將 IoT 資料匯出至 Azure 資料總管

文章
06/27/2024

本文說明如何設定資料匯出，以將資料傳送至 Azure 資料總管。

使用此功能從 IoT Central 應用程式中連續匯出已篩選及擴充的 IoT 資料。資料匯出會即時將變更推送至雲端解決方案的其他部分，以進行經常性路徑深入解析、分析和儲存體。

例如，您可以：

以 JSON 格式近乎即時匯出遙測、屬性變更、裝置連線、裝置生命週期、裝置範本生命週期和稽核記錄資料。
篩選資料流以匯出符合自訂條件的資料。
使用來自裝置的自訂值和屬性值來擴充資料流。
轉換資料流以修改其圖形和內容。

提示

在您開啟資料匯出時，只會取得該時刻之後的資料。若要保留更多歷史資料，請儘早開啟資料匯出。若要在關閉資料匯出時手動匯出資料，請參閱如何使用 IoT Central REST API 來查詢裝置 (部分機器翻譯)。

注意

在某些情況下，匯出訊息最多可能需要 60 秒的時間。測量的時間範圍為：自 IoT Central 從基礎 IoT 中樞接收訊息，到將訊息傳遞至目的地端點。

必要條件

若要使用資料匯出功能，您必須具有資料匯出權限。

設定 Azure 資料總管匯出目的地

您可以使用 Azure 資料總管叢集或 Azure Synapse 資料總管集區。如需深入了解，請參閱 Azure Synapse 資料總管與 Azure 資料總管之間有何差異？。

IoT Central 會近乎即時地將資料匯出至 Azure 資料總管叢集中的資料庫資料表。資料位於訊息本文中，並以 JSON 格式編碼為 UTF-8。您可以在 IoT Central 中新增轉換，以匯出符合資料表結構描述的資料。

若要在 Azure 資料總管入口網站中查詢匯出的資料，請瀏覽至資料庫，然後選取 [查詢]。

下列影片將逐步引導您將資料匯出至 Azure 資料總管：

連線選項

Azure 資料總管目的地可讓您設定與服務主體或受控識別的連線。

受控識別更安全，因為：

您不會將資源認證儲存在 IoT Central 應用程式中的連接字串。
認證會自動繫結至 IoT Central 應用程式的存留期。
受控識別會自動定期輪替其安全性金鑰。

IoT Central 目前使用系統指派的受控識別。

當您設定受控識別時，設定會包含「範圍」和「角色」：

範圍會定義您可以使用受控識別的位置。例如，您可以使用 Azure 資源群組作為範圍。在此情況下，IoT Central 應用程式和目的地都必須位於相同的資源群組中。
角色會定義目的地服務中授與 IoT Central 應用程式的權限。例如，若要讓 IoT Central 應用程式將資料傳送至事件中樞，受控識別需要 Azure 事件中樞資料傳送者角色指派。

下列影片會提供有關系統指派受控識別的詳細資訊：

警告

若要匯出至 Blob 儲存體，請勿如影片所示使用儲存體帳戶參與者。請改為使用儲存體 Blob 資料參與者角色。

本文說明如何使用 Azure CLI 建立受控識別。您也可以使用 Azure 入口網站來建立受控識別。

如果您沒有現有 Azure 資料總管資料庫做為匯出目的地，請遵循下列步驟。您有兩個選項可建立 Azure 資料總管資料庫：

建立新的 Azure 資料總管叢集與資料庫。若要深入了解，請參閱 Azure 資料總管快速入門。記下叢集 URI 和您所建立資料庫的名稱，您在下列步驟中會需要這些值。
建立新的 Azure Synapse 資料總管集區和資料庫。若要深入了解，請參閱 Azure 資料總管快速入門。記下集區 URI 和您所建立資料庫的名稱，您在下列步驟中會需要這些值。

如需設定可讓 IoT Central 應用程式安全地將資料匯出至 Azure 資源的受控識別：

為您的 IoT Central 應用程式建立受控識別，以用來連線到您的資料庫。使用 Azure Cloud Shell 來執行下列命令：
```
az iot central app identity assign --name {your IoT Central app name} \
    --resource-group {resource group name} \
    --system-assigned
```
依命令記下 principalId 和 tenantId 輸出。您會在下列步驟中使用這些值。

設定資料庫權限以允許來自 IoT Central 應用程式的連線。使用 Azure Cloud Shell 來執行下列命令：

az kusto database-principal-assignment create --cluster-name {name of your cluster} \
    --database-name {name of your database}    \
    --resource-group {resource group name} \
    --principal-assignment-name {name of your IoT Central application} \
    --principal-id {principal id from the previous step} \
    --principal-type App --role Admin \
    --tenant-id {tenant id from the previous step}

提示

如果您使用 Azure Synapse，請參閱 az synapse kusto database-principal-assignment。

針對您要匯出的資料，使用適合的結構描述，在資料庫中建立資料表。下列範例查詢會建立名為 smartvitalspatch 的資料表。若要深入了解，請參閱轉換 IoT Central 應用程式內的資料以進行匯出：
```
.create table smartvitalspatch (
  EnqueuedTime:datetime,
  Message:string,
  Application:string,
  Device:string,
  Simulated:boolean,
  Template:string,
  Module:string,
  Component:string,
  Capability:string,
  Value:dynamic
)
```
(選擇性) 若要加速將資料內嵌至 Azure 資料總管資料庫：
1. 瀏覽至 Azure 資料總管叢集的 [設定] 頁面。然後啟用 [串流擷取] 選項。
2. 執行下列查詢來改變資料表原則，以啟用串流擷取：
```
.alter table smartvitalspatch policy streamingingestion enable
```

若要在 [資料匯出] 頁面上的 IoT Central 中建立 Azure 資料總管目的地：

選取 [+ 新增目的地]。
選取 [Azure 資料總管] 做為目的地類型。
輸入您的 Azure 資料總管叢集或集區 URL、資料庫名稱和資料表名稱。選取 [系統指派的受控識別] 作為授權類型。

提示

獨立 Azure 資料總管的叢集 URL 看起來像 https://<ClusterName>.<AzureRegion>.kusto.windows.net。 Azure Synapse 資料總管集區的叢集 URL 看起來像 https://<DataExplorerPoolName>.<SynapseWorkspaceName>.kusto.azuresynapse.net。

如果您沒有看到抵達目的地服務的資料，請參閱針對從 Azure IoT Central 應用程式匯出資料的問題進行疑難排解。

如果您沒有現有 Azure 資料總管資料庫做為匯出目的地，請遵循下列步驟：

您有兩個選項可建立 Azure 資料總管資料庫：
- 建立新的 Azure 資料總管叢集與資料庫。若要深入了解，請參閱 Azure 資料總管快速入門。記下叢集 URI 和您所建立資料庫的名稱，您在下列步驟中會需要這些值。
- 建立新的 Azure Synapse 資料總管集區和資料庫。若要深入了解，請參閱 Azure 資料總管快速入門。記下集區 URI 和您所建立資料庫的名稱，您在下列步驟中會需要這些值。
建立可用來將 IoT Central 應用程式連線至 Azure 資料總管的服務主體。使用 Azure Cloud Shell 來執行下列命令：
```
az ad sp create-for-rbac --skip-assignment --name "My SP for IoT Central" --scopes /subscriptions/<SubscriptionId>
```
記下命令輸出中的 appId、password 和 tenant 值，您在下列步驟中會需要這些值。
若要將服務主體新增至資料庫，請瀏覽至 Azure 資料總管入口網站，並在您的資料庫上執行下列查詢。以您先前記下的值取代預留位置：
```
.add database ['<YourDatabaseName>'] admins ('aadapp=<YourAppId>;<YourTenant>');
```
針對您要匯出的資料，使用適合的結構描述，在資料庫中建立資料表。下列範例查詢會建立名為 smartvitalspatch 的資料表。若要深入了解，請參閱轉換 IoT Central 應用程式內的資料以進行匯出：
```
.create table smartvitalspatch (
  EnqueuedTime:datetime,
  Message:string,
  Application:string,
  Device:string,
  Simulated:boolean,
  Template:string,
  Module:string,
  Component:string,
  Capability:string,
  Value:dynamic
)
```
(選擇性) 若要加速將資料內嵌至 Azure 資料總管資料庫：
1. 瀏覽至 Azure 資料總管叢集的 [設定] 頁面。然後啟用 [串流擷取] 選項。
2. 執行下列查詢來改變資料表原則，以啟用串流擷取：
```
.alter table smartvitalspatch policy streamingingestion enable
```

若要在 [資料匯出] 頁面上的 IoT Central 中建立 Azure 資料總管目的地：

選取 [+ 新增目的地]。
選取 [Azure 資料總管] 做為目的地類型。
輸入您的 Azure 資料總管叢集或集區 URL、資料庫名稱和資料表名稱。下表顯示要用於授權的服務主體值：

服務主體值目的地設定

appId ClientID

tenant 租用戶識別碼

password 用戶端密碼

提示

獨立 Azure 資料總管的叢集 URL 看起來像 https://<ClusterName>.<AzureRegion>.kusto.windows.net。 Azure Synapse 資料總管集區的叢集 URL 看起來像 https://<DataExplorerPoolName>.<SynapseWorkspaceName>.kusto.azuresynapse.net。

服務主體值	目的地設定
appId	ClientID
tenant	租用戶識別碼
password	用戶端密碼

設定資料匯出

現在您已擁有匯出資料的目的地，請在 IoT Central 應用程式中設定資料匯出：

登入您的 IoT Central 應用程式。
在左側窗格中，選取 [資料匯出]。

提示

如果您沒有在左窗格中看到 [資料匯出]，則表示您沒有在應用程式中設定資料匯出的權限。請連絡系統管理員來設定資料匯出。
選取 [+ 新增匯出]。
輸入新匯出的顯示名稱，並確定資料匯出為 [已啟用]。

選擇要匯出的資料類型。下表列出支援的資料匯出類型：

資料類型	描述	資料格式
遙測	近乎即時地從裝置匯出遙測訊息。每則匯出的訊息都包含原始裝置訊息的完整內容，且已標準化。	遙測訊息格式
屬性變更	近乎即時地將變更匯出至裝置和雲端屬性。針對唯讀裝置屬性，會匯出報告值的變更內容。針對讀寫屬性，會匯出報告和所需的值。	屬性變更訊息格式
裝置連線	匯出已連線和中斷連線的裝置事件。	裝置連線訊息格式
裝置生命週期	匯出註冊、刪除、佈建、啟用、停用、displayNameChanged 和 deviceTemplateChanged 事件的裝置。	裝置生命週期變更訊息格式
裝置範本生命週期	匯出已發佈的裝置範本變更，包括已建立、已更新和已刪除等變更。	裝置範本生命週期變更訊息格式
稽核記錄	應用程式內實體的使用者起始更新記錄。若要深入了解，請參閱使用稽核記錄來追蹤 IoT Central 應用程式中的活動	稽核記錄訊息格式

或者，新增篩選條件以減少匯出的資料量。每個資料匯出類型都有不同類型的篩選條件：

資料類型	可用的篩選條件
遙測	依裝置名稱、裝置識別碼、裝置範本，以及裝置是否為模擬進行篩選篩選資料流，使篩選出的遙測皆符合篩選的條件篩選資料流，使篩選出的遙測皆來自符合篩選條件屬性的裝置篩選資料流，使篩選出的遙測皆具有符合篩選條件的「訊息屬性」。訊息屬性 (也稱為應用程式屬性) 會在每則遙測訊息上以機碼值組包傳送。若要建立訊息屬性篩選條件，請輸入您要尋找的訊息屬性索引鍵，並指定條件。系統只會匯出具有符合指定篩選條件屬性的遙測訊息。深入了解 IoT 中樞的應用程式屬性文件
屬性變更	依裝置名稱、裝置識別碼、裝置範本，以及裝置是否為模擬進行篩選篩選資料流，使篩選出的屬性變更皆符合篩選的條件
裝置連線	依裝置名稱、裝置識別碼、裝置範本、組織，以及裝置是否為已模擬進行篩選篩選資料流，使篩選出的變更皆來自符合篩選條件屬性的裝置
裝置生命週期	依裝置名稱、裝置識別碼、裝置範本，以及裝置是否為已佈建、已啟用或已模擬進行篩選篩選資料流，使篩選出的變更皆來自符合篩選條件屬性的裝置
裝置範本生命週期	依裝置範本篩選
稽核記錄	N/A

或者，使用額外的機碼值組中繼資料來擴充匯出的訊息。下列擴充適用於遙測、屬性變更、裝置連線能力，以及裝置生命週期資料匯出類型：
- 自訂字串：將自訂靜態字串新增至每則訊息。輸入任何索引鍵，然後輸入任何字串值。
- 屬性，會新增至每則訊息中：
  - 裝置中繼資料，例如裝置名稱、裝置範本名稱、已啟用、組織、已佈建和已模擬。
  - 目前裝置對每則訊息的報告屬性或雲端屬性值。如果匯出訊息來自沒有指定屬性的裝置，則匯出訊息不會獲得擴充。

設定匯出目的地：

選取 [+ 目的地] 以新增您已建立的目的地，或選取 [建立新目的地]。
若要在匯出資料之前轉換您的資料，請選取 [+ 轉換]。若要深入了解，請參閱轉換 IoT Central 應用程式內的資料以進行匯出。
選取 [+ 目的地] 將最多五個目的地新增至單一匯出。
完成匯出設定後，請選取 [儲存]。幾分鐘之後，您的資料就會出現在目的地中。

監視您的匯出

在 IoT Central 中，[資料匯出] 頁面可讓您檢查匯出的狀態。您也可以使用 Azure 監視器來查看您要匯出的資料量，以及是否有任何匯出錯誤。您可以使用 REST API、PowerShell 中的查詢，或 Azure CLI 存取 Azure 入口網站圖表中的匯出和裝置健康情況計量。目前，您可以在 Azure 監視器中監視下列資料匯出計量：

套用篩選條件前，要匯出的訊息傳入數目。
通過篩選條件的訊息數目。
成功匯出至目的地的訊息數目。
找到的錯誤數目。

若要深入了解，請參閱監視應用程式健康情況。

資料格式

下列各節說明匯出資料的格式：

遙測格式

每則匯出的訊息都包含裝置在訊息本文中傳送的完整訊息，其標準化的形式。訊息採用 JSON 格式，並編碼為 UTF-8。每則訊息中的資訊包含：

applicationId：IoT Central 應用程式的識別碼。
messageSource：訊息的來源 - telemetry。
deviceId：傳送遙測訊息裝置的識別碼。
schema：承載結構的名稱和版本。
templateId：指派給裝置的裝置範本識別碼。
enqueuedTime：IoT Central 收到此訊息的時間。
enrichments：在匯出上設定的任何擴充。
module：傳送此訊息的 IoT Edge 模組。只有在訊息來自 IoT Edge 模組時，才會顯示此欄位。
component：傳送此訊息的元件。只有在訊息中傳送的功能已模型化為裝置範本中的元件時，才會顯示此欄位
messageProperties：裝置與訊息一起傳送的其他屬性。這些屬性有時稱為應用程式屬性。從 IoT 中樞文件深入了解。

訊息屬性

遙測訊息具有中繼資料的屬性，以及遙測承載。上一個程式碼片段顯示系統訊息的範例，例如 deviceId 和 enqueuedTime。若要深入了解系統訊息屬性，請參閱裝置到雲端 IoT 中樞訊息的系統屬性。

如果您需要將自訂中繼資料新增至遙測訊息，則可以將屬性新增至遙測訊息。例如，您需要在裝置建立訊息時，新增時間戳記。

下列程式碼片段示範在裝置上建立 iothub-creation-time-utc 屬性時，如何將屬性新增至訊息：

重要

此時間戳記的格式必須是不含時區資訊的 UTC。例如，2021-04-21T11:30:16Z 為有效，而 2021-04-21T11:30:16-07:00 為無效。

async function sendTelemetry(deviceClient, index) {
  console.log('Sending telemetry message %d...', index);
  const msg = new Message(
    JSON.stringify(
      deviceTemperatureSensor.updateSensor().getCurrentTemperatureObject()
    )
  );
  msg.properties.add("iothub-creation-time-utc", new Date().toISOString());
  msg.contentType = 'application/json';
  msg.contentEncoding = 'utf-8';
  await deviceClient.sendEvent(msg);
}

private static void sendTemperatureTelemetry() {
  String telemetryName = "temperature";
  String telemetryPayload = String.format("{\"%s\": %f}", telemetryName, temperature);

  Message message = new Message(telemetryPayload);
  message.setContentEncoding(StandardCharsets.UTF_8.name());
  message.setContentTypeFinal("application/json");
  message.setProperty("iothub-creation-time-utc", Instant.now().toString());

  deviceClient.sendEventAsync(message, new MessageIotHubEventCallback(), message);
  log.debug("My Telemetry: Sent - {\"{}\": {}°C} with message Id {}.", telemetryName, temperature, message.getMessageId());
  temperatureReadings.put(new Date(), temperature);
}

private async Task SendTemperatureTelemetryAsync()
{
  const string telemetryName = "temperature";

  string telemetryPayload = $"{{ \"{telemetryName}\": {_temperature} }}";
  using var message = new Message(Encoding.UTF8.GetBytes(telemetryPayload))
  {
      ContentEncoding = "utf-8",
      ContentType = "application/json",
  };
  message.Properties.Add("iothub-creation-time-utc", DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"));
  await _deviceClient.SendEventAsync(message);
  _logger.LogDebug($"Telemetry: Sent - {{ \"{telemetryName}\": {_temperature}°C }}.");
}

async def send_telemetry_from_thermostat(device_client, telemetry_msg):
    msg = Message(json.dumps(telemetry_msg))
    msg.custom_properties["iothub-creation-time-utc"] = datetime.now(timezone.utc).isoformat()
    msg.content_encoding = "utf-8"
    msg.content_type = "application/json"
    print("Sent message")
    await device_client.send_message(msg)

屬性變更格式

每個訊息或記錄都代表裝置和雲端屬性的變更。匯出訊息中的資訊包含：

applicationId：IoT Central 應用程式的識別碼。
messageSource：訊息的來源 - properties。
messageType：cloudPropertyChange、devicePropertyDesiredChange 或 devicePropertyReportedChange 任一項。
deviceId：傳送遙測訊息裝置的識別碼。
schema：承載結構的名稱和版本。
enqueuedTime：IoT Central 偵測到這項變更的時間。
templateId：指派給裝置的裝置範本識別碼。
properties：已變更的屬性陣列，包含已變更屬性和值的名稱。如果屬性是在元件或 IoT Edge 模組內建立模型，則會包含元件和模組資訊。
enrichments：在匯出上設定的任何擴充。

裝置連線能力變更格式

每則訊息或記錄都代表來自單一裝置的連線事件。匯出訊息中的資訊包含：

applicationId：IoT Central 應用程式的識別碼。
messageSource：訊息的來源 - deviceConnectivity。
messageType：connected 或 disconnected 任一項。
deviceId：已變更裝置的識別碼。
schema：承載結構的名稱和版本。
templateId：指派給裝置的裝置範本識別碼。
enqueuedTime：IoT Central 發生這項變更的時間。
enrichments：在匯出上設定的任何擴充。

裝置生命週期變更格式

每則訊息或記錄都代表單一裝置的一項變更。匯出訊息中的資訊包含：

applicationId：IoT Central 應用程式的識別碼。
messageSource：訊息的來源 - deviceLifecycle。
messageType：所發生變更的類型。下列其中一項：registered、deleted、provisioned、enabled、disabled、displayNameChanged 和 deviceTemplateChanged。
deviceId：已變更裝置的識別碼。
schema：承載結構的名稱和版本。
templateId：指派給裝置的裝置範本識別碼。
enqueuedTime：IoT Central 發生這項變更的時間。
enrichments：在匯出上設定的任何擴充。

裝置範本生命週期變更格式

每則訊息或記錄都代表單一已發佈裝置範本的一項變更。匯出訊息中的資訊包含：

applicationId：IoT Central 應用程式的識別碼。
messageSource：訊息的來源 - deviceTemplateLifecycle。
messageType：created、updated 或 deleted 任一項。
schema：承載結構的名稱和版本。
templateId：指派給裝置的裝置範本識別碼。
enqueuedTime：IoT Central 發生這項變更的時間。
enrichments：在匯出上設定的任何擴充。

稽核記錄檔格式

每個稽核記錄訊息都代表 IoT Central 應用程式內可稽核實體的使用者起始變更。匯出訊息中的資訊包含：

actor：修改實體的使用者相關資訊。
applicationId：IoT Central 應用程式的識別碼。
messageSource：訊息的來源 - audit。
messageType：所發生變更的類型。下列其中一項：updated、created 或 deleted。
updated：只有在 messageType 是 updated 時才存在。提供有關更新的詳細資料。
resource：已修改實體的詳細資料。
schema：承載結構的名稱和版本。
deviceId：已變更裝置的識別碼。
enqueuedTime：IoT Central 發生這項變更的時間。
enrichments：在匯出上設定的任何擴充。

下一步

既然您已了解如何匯出至 Azure 資料總管，建議的下一個步驟是了解如何匯出至 Webhook。

分享方式：