將 IoT 數據匯出至 Blob 儲存體

發行項
03/05/2024

本文說明如何設定數據匯出以將數據傳送至 Blob 儲存體服務。

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

例如，您可以：

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

提示

當您開啟數據匯出時，您只會從該刻起取得數據。若要保留更多歷程記錄數據，請提早開啟數據匯出。若要在關閉數據匯出時手動匯出數據，請參閱如何使用IoT Central REST API來查詢裝置。

注意

在某些情況下，導出訊息最多可能需要 60 秒的時間。此時間是從IoT Central 從基礎IoT中樞接收訊息到傳遞至目的地端點時所測量。

必要條件

若要使用資料匯出功能，您必須具有數據匯出許可權。

若要瞭解如何使用IoT Central REST API管理數據匯出，請參閱如何使用IoT Central REST API來管理數據導出。

設定 Blob 儲存體匯出目的地

IoT Central 每分鐘導出一次數據，其中每個檔案都包含上一次匯出后的變更批次。匯出的數據會以 JSON 格式儲存。記憶體帳戶中匯出資料的預設路徑如下：

遙測： {container}/{app-id}/{partition_id}/{YYYY}/{MM}/{dd}/{hh}/{mm}/{filename}
属性變更： {container}/{app-id}/{partition_id}/{YYYY}/{MM}/{dd}/{hh}/{mm}/{filename}

若要流覽 Azure 入口網站中導出的檔案，請流覽至檔案，然後選取 [編輯 Blob]。

連線選項

Blob 儲存體目的地可讓您設定與 連接字串 或受控識別的連線。

提示

如果 Blob 儲存體目的地受到防火牆保護，您必須使用受控識別來連線到該目的地。

受控識別更安全，因為：

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

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

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

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

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

警告

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

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

如果您沒有要導出的現有 Azure 記憶體帳戶，請在 Azure Cloud Shell bash 環境中執行下列腳本。腳本會建立資源群組、Azure 儲存體帳戶和 Blob 容器。然後腳本會啟用IoT Central 應用程式的受控識別，並指派存取記憶體帳戶所需的角色：

# Replace the storage account name with your own unique value.
SA=yourstorageaccount$RANDOM

# Replace the IoT Central app name with the name of your
# IoT Central application.
CA=your-iot-central-app

CN=exportdata
RG=centralexportresources
LOCATION=eastus

az group create -n $RG --location $LOCATION
SAID=$(az storage account create --name $SA --resource-group $RG --location $LOCATION --sku Standard_LRS --query "id" --output tsv)
az storage container create --account-name $SA --resource-group $RG --name $CN

# This assumes your IoT Central application is in the 
# default `IOTC` resource group.
az iot central app identity assign --name $CA --resource-group IOTC --system-assigned
PI=$(az iot central app identity show --name $CA --resource-group IOTC --query "principalId" --output tsv)

az role assignment create --assignee $PI --role "Storage Blob Data Contributor" --scope $SAID

az role assignment list --assignee $PI --all -o table

echo "Endpoint URI: https://$SA.blob.core.windows.net/"
echo "Container: $CN"

您可以深入瞭解如何建立新的 Azure Blob 儲存體帳戶或 Azure Data Lake 儲存體 v2 儲存器帳戶。數據匯出只能將數據寫入支援區塊 Blob 的記憶體帳戶。下表顯示已知的相容記憶體帳戶類型：

效能層級	帳戶類型
標準	一般目的 V2
標準	一般目的 V1
標準	Blob 儲存體
進階	區塊 Blob 記憶體

若要進一步保護您的 Blob 容器，並只允許從具有受控識別的受信任服務存取，請參閱將數據匯出至 Azure 虛擬網絡上的安全目的地。

若要在 [數據匯出] 頁面上的 IoT Central 中建立 Blob 儲存體目的地：

選取 [+ 新增目的地]。
選取 [Azure Blob 儲存體] 作為目的地類型。
選取 [系統指派的受控識別 ] 作為授權類型。
輸入記憶體帳戶的端點 URI 和區分大小寫的容器名稱。端點 URI 看起來像： https://contosowaste.blob.core.windows.net。
選取 [儲存]。

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

如果您沒有要導出的現有 Azure 記憶體帳戶，請在 Azure Cloud Shell bash 環境中執行下列腳本。腳本會建立資源群組、Azure 儲存體帳戶和 Blob 容器。然後，它會列印在IoT Central 中設定資料匯出時要使用的連接字串：

# Replace the storage account name with your own unique value
SA=yourstorageaccount$RANDOM
CN=exportdata
RG=centralexportresources
LOCATION=eastus

az group create -n $RG --location $LOCATION
az storage account create --name $SA --resource-group $RG --location $LOCATION --sku Standard_LRS
az storage container create --account-name $SA --resource-group $RG --name $CN

CS=$(az storage account show-connection-string --resource-group $RG --name $SA --query "connectionString" --output tsv)

echo "Storage connection string: $CS"

效能層級	帳戶類型
標準	一般目的 V2
標準	一般目的 V1
標準	Blob 儲存體
進階	區塊 Blob 記憶體

若要在 [數據匯出] 頁面上的 IoT Central 中建立 Blob 儲存體目的地：

選取 [+ 新增目的地]。
選取 [Azure Blob 儲存體] 作為目的地類型。
選取 [連線 ion 字串] 作為授權類型。
貼上 Blob 儲存體資源的連接字串，並視需要輸入區分大小寫的容器名稱。
選取 [儲存]。

設定數據匯出

既然您有要匯出數據的目的地，請在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 中樞檔深入瞭解。

針對 Blob 儲存體，每分鐘會批處理並匯出一次訊息。

下列範例顯示匯出的遙測訊息：


{
    "applicationId": "1dffa667-9bee-4f16-b243-25ad4151475e",
    "messageSource": "telemetry",
    "deviceId": "1vzb5ghlsg1",
    "schema": "default@v1",
    "templateId": "urn:qugj6vbw5:___qbj_27r",
    "enqueuedTime": "2020-08-05T22:26:55.455Z",
    "telemetry": {
        "Activity": "running",
        "BloodPressure": {
            "Diastolic": 7,
            "Systolic": 71
        },
        "BodyTemperature": 98.73447010562934,
        "HeartRate": 88,
        "HeartRateVariability": 17,
        "RespiratoryRate": 13
    },
    "enrichments": {
      "userSpecifiedKey": "sampleValue"
    },
    "module": "VitalsModule",
    "component": "DeviceComponent",
    "messageProperties": {
      "messageProp": "value"
    }
}

訊息屬性

遙測訊息具有元數據的屬性，以及遙測承載。上一個代碼段顯示系統訊息的範例，例如 deviceId 和 enqueuedTime。若要深入了解系統訊息屬性，請參閱 D2C 的系統屬性 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。
messageTypecloudPropertyChange：、 devicePropertyDesiredChange或 devicePropertyReportedChange。
deviceId：傳送遙測訊息之裝置的標識碼。
schema：承載架構的名稱和版本。
enqueuedTime：IoT Central 偵測到此變更的時間。
templateId：指派給裝置之裝置範本的標識符。
properties：已變更的屬性陣列，包括屬性的名稱和變更的值。如果屬性是在元件或IoT Edge模組內建立模型，則會包含元件和模組資訊。
enrichments：在匯出上設定的任何擴充。

針對 Blob 儲存體，每分鐘會批處理並匯出一次訊息。

下列代碼段顯示匯出至 Blob 的屬性變更訊息儲存體：

{
    "applicationId": "fb74969c-8682-4708-af01-33499a7f7d98",
    "messageSource": "properties",
    "deviceId": "Pepjmh1Hcc",
    "enqueuedTime": "2023-03-02T10:35:39.281Z",
    "enrichments": {},
    "messageType": "devicePropertyReportedChange",
    "schema": "default@v1",
    "templateId": "dtmi:azureiot:ddzig4ascxz",
    "properties": [
        {
            "component": "device_info",
            "name": "swVersion",
            "value": "12"
        },
        {
            "component": "device_info",
            "name": "osName",
            "value": "Android"
        },
        {
            "component": "device_info",
            "name": "processorArchitecture",
            "value": "arm64-v8a"
        },
        {
            "component": "device_info",
            "name": "processorManufacturer",
            "value": "unknown"
        }
    ]
}

裝置連線能力變更格式

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

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

針對 Blob 儲存體，訊息會批處理並匯出每分鐘一次。

下列範例顯示 Azure Blob 儲存體中收到的導出裝置連線訊息。

{
  "applicationId": "1dffa667-9bee-4f16-b243-25ad4151475e",
  "messageSource": "deviceConnectivity",
  "messageType": "connected",
  "deviceId": "1vzb5ghlsg1",
  "schema": "default@v1",
  "templateId": "urn:qugj6vbw5:___qbj_27r",
  "enqueuedTime": "2021-04-05T22:26:55.455Z",
  "enrichments": {
    "userSpecifiedKey": "sampleValue"
  }
}

裝置生命周期變更格式

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

applicationId：IoT Central 應用程式的標識碼。
messageSource：訊息的來源 - deviceLifecycle。
messageType：發生的變更類型。其中一個：、、、provisionedenabled、disabled、displayNameChanged、和 deviceTemplateChanged。 deletedregistered
deviceId：已變更之裝置的標識碼。
schema：承載架構的名稱和版本。
templateId：指派給裝置之裝置範本的標識符。
enqueuedTime：此變更發生在IoT Central的時間。
enrichments：在匯出上設定的任何擴充。

針對 Blob 儲存體，每分鐘會批處理並匯出一次訊息。

下列範例顯示 Azure Blob 儲存體中收到的導出裝置生命週期訊息。

{
  "applicationId": "1dffa667-9bee-4f16-b243-25ad4151475e",
  "messageSource": "deviceLifecycle",
  "messageType": "registered",
  "deviceId": "1vzb5ghlsg1",
  "schema": "default@v1",
  "templateId": "urn:qugj6vbw5:___qbj_27r",
  "enqueuedTime": "2021-01-01T22:26:55.455Z",
  "enrichments": {
    "userSpecifiedKey": "sampleValue"
  }
}

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

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

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

針對 Blob 儲存體，訊息會批處理並匯出每分鐘一次。

下列範例顯示 Azure Blob 儲存體中收到的導出裝置生命週期訊息。

{
  "applicationId": "1dffa667-9bee-4f16-b243-25ad4151475e",
  "messageSource": "deviceTemplateLifecycle",
  "messageType": "created",
  "schema": "default@v1",
  "templateId": "urn:qugj6vbw5:___qbj_27r",
  "enqueuedTime": "2021-01-01T22:26:55.455Z",
  "enrichments": {
    "userSpecifiedKey": "sampleValue"
  }
}

稽核記錄檔格式

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

actor：修改實體之使用者的相關信息。
applicationId：IoT Central 應用程式的標識碼。
messageSource：訊息的來源 - audit。
messageType：發生的變更類型。的其中一個：updated、createddeleted、。
updated：只有在是 updated時才messageType存在。提供有關更新的詳細數據。
resource：已修改實體的詳細數據。
schema：承載架構的名稱和版本。
deviceId：已變更之裝置的標識碼。
enqueuedTime：此變更發生在IoT Central的時間。
enrichments：在匯出上設定的任何擴充。

下列範例顯示 Azure Blob 儲存體中收到的導出稽核記錄訊息：

{
  "actor": {
    "id": "test-audit",
    "type": "apiToken"
    },
  "applicationId": "570c2d7b-1111-2222-abcd-000000000000",
  "enqueuedTime": "2022-07-25T21:54:40.000Z",
  "enrichments": {},
  "messageSource": "audit",
  "messageType": "created",
  "resource": {
    "displayName": "Sensor 1",
    "id": "sensor",
    "type": "device"    
  },
  "schema": "default@v1"
}

下一步

既然您已瞭解如何匯出至 Blob 儲存體，建議的下一個步驟是瞭解如何匯出至服務匯流排。

將 IoT 數據匯出至 Blob 儲存體

必要條件

設定 Blob 儲存體 匯出目的地

連線選項

建立 Azure Blob 儲存體 目的地

設定數據匯出

監視導出

資料格式

遙測格式

訊息屬性

屬性變更格式

裝置連線能力變更格式

裝置生命周期變更格式

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

稽核記錄檔格式

下一步

其他資源

設定 Blob 儲存體匯出目的地

建立 Azure Blob 儲存體目的地