如何使用 IoT Central REST API 管理資料匯出

發行項
10/22/2024

IoT Central REST API 可讓您開發與 IoT Central 應用程式整合的用戶端應用程式。您可以使用 REST API 在 IoT Central 應用程式中建立和管理資料匯出。

每個 IoT Central REST API 呼叫都需要授權標頭。若要深入了解，請參閱如何驗證和授權 IoT Central REST API 呼叫。

如需 IoT Central REST API 的參考文件，請參閱 Azure IoT Central REST API 參考。

若要了解如何使用 IoT Central UI 管理資料匯出，請參閱將 IoT 資料匯出至 Blob 儲存體。

資料匯出

您可以使用 IoT Central 資料匯出功能，將遙測、屬性變更、裝置連線活動、裝置生命週期事件和裝置範本生命週期事件串流至目的地，例如Azure 事件中樞、Azure 服務匯流排、Azure Blob 儲存體和 Webhook 端點。

每個資料匯出定義都可以將資料傳送至一或多個目的地。建立匯出定義之前，請先建立目的地定義。

建立或更新目的地

可使用下列要求來建立或更新目的地定義：

PUT https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

destinationId 是目的地的唯一識別碼。

下列範例顯示建立 Blob 儲存體目的地的要求本文：

{
  "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data"
    }
}

要求本文有一些必要欄位：

displayName：目的地的顯示名稱。
type：目的地物件的類型。下列其中一個值：blobstorage@v1、dataexplorer@v1、eventhubs@v1、servicebusqueue@v1、servicebustopic@v1、webhook@v1。
authorization：目的地的授權詳細資料。支援的授權類型為 systemAssignedManagedIdentity 和 connectionString。

此要求的回應如下列範例所示：

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data"
    },
    "status": "waiting"
}

依識別碼取得目的地

可使用下列要求，從您的應用程式擷取目的地的詳細資料：

GET https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

此要求的回應如下列範例所示：

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data"
    },
    "status": "waiting"
}

列出目的地

可使用下列要求，從您的應用程式擷取目的地清單：

GET https://{your app subdomain}/api/dataExport/destinations?api-version=2022-10-31-preview

此要求的回應如下列範例所示：

{
    "value": [
        {
            "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
            "displayName": "Blob Storage Destination",
            "type": "blobstorage@v1",
            "authorization": {
              "type": "systemAssignedManagedIdentity",
              "endpointUri": "https://yourapplication.blob.core.windows.net/",
              "containerName": "central-data"
            },
            "status": "waiting"
        },
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9",
            "displayName": "Webhook destination",
            "type": "webhook@v1",
            "url": "https://eofnjsh68jdytan.m.pipedream.net",
            "headerCustomizations": {},
            "status": "error"
        }
    ]
}

修補目的地

PATCH https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

您可以使用此呼叫對某項匯出執行累加式更新。範例要求本文如下列範例所示，更新目的地的 containerName：

{
  "containerName": "central-data-analysis"
}

此要求的回應如下列範例所示：

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data-analysis"
    },
    "status": "waiting"
}

刪除目的地

可使用下列要求來刪除目的地：

DELETE https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

建立或更新匯出定義

可使用下列要求來建立或更新資料匯出定義：

PUT https://{your app subdomain}/api/dataExport/exports/{exportId}?api-version=2022-10-31-preview

下列範例顯示的是建立裝置遙測匯出定義的要求本文：

{
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value"
        }
    },
    "destinations": [
        {
            "id": "8dbcdb53-c6a7-498a-a976-a824b694c150"
        }
    ]
}

要求本文有一些必要欄位：

displayName：匯出的顯示名稱。
enabled：切換以啟動/停止匯出的資料傳送。
source：要匯出的資料類型。
destinations：匯出應傳送資料的目的地清單。目的地識別碼必須已存在於應用程式中。

有一些選擇性欄位可供使用，以便將更多詳細資料新增至匯出。

enrichments：要包含在每個已傳送訊息的額外資訊片段。數據會以一組索引鍵/值組表示，其中索引鍵是輸出訊息中顯示的擴充名稱，而值會識別要傳送的數據。
filter：定義應從來源匯出哪些事件的查詢。

此要求的回應如下列範例所示：

{
    "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value"
        }
    },
    "destinations": [
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
    ],
    "status": "starting"
}

擴充

您可以將下列三種類型的擴充新增至匯出：自訂字串、系統屬性和自訂屬性：

下列範例示範如何使用 enrichments 節點，將自訂字串新增至外寄郵件：

"enrichments": {
  "My custom string": {
    "value": "My value"
  },
  //...
}

下列範例示範如何使用 enrichments 節點，將系統屬性新增至外寄郵件：

"enrichments": {
  "Device template": {
    "path": "$templateDisplayName"
  },
  //...
}

您可以新增下列系統屬性：

屬性	說明
`$enabled`	是否已啟用裝置？
`$displayName`	裝置名稱。
`$templateDisplayName`	裝置範本名稱。
`$organizations`	裝置所屬的組織。
`$provisioned`	是否已佈建裝置？
`$simulated`	是否已模擬裝置？

下列範例示範如何使用 enrichments 節點，將自訂屬性新增至外寄郵件。自訂屬性是在與裝置相關聯的裝置範本中定義的屬性：

"enrichments": {
  "Device model": {
    "target": "dtmi:azure:DeviceManagement:DeviceInformation;1",
    "path": "model"
  },
  //...
}

篩選

您可以根據遙測或屬性值來篩選匯出的訊息。

下列範例示範如何使用 [filter] 欄位，僅匯出加速計-X 遙測值大於 0 的訊息：

{
  "id": "export-001",
  "displayName": "Enriched Export",
  "enabled": true,
  "source": "telemetry",
  "filter": "SELECT * FROM dtmi:eclipsethreadx:devkit:gsgmxchip;1 WHERE accelerometerX > 0",
  "destinations": [
    {
      "id": "dest-001"
    }
  ],
  "status": "healthy"
}

下列範例示範如何使用 [filter] 欄位，僅匯出 temperature 遙測值大於 targetTemperature 屬性的訊息：

{
  "id": "export-001",
  "displayName": "Enriched Export",
  "enabled": true,
  "source": "telemetry",
  "filter": "SELECT * FROM dtmi:eclipsethreadx:devkit:gsgmxchip;1 AS A, dtmi:contoso:Thermostat;1 WHERE A.temperature > targetTemperature",
  "destinations": [
    {
      "id": "dest-001"
    }
  ],
  "status": "healthy"
}

依識別碼取得匯出

可使用下列要求，從您的應用程式擷取匯出定義的詳細資料：

GET https://{your app subdomain}/api/dataExport/exports/{exportId}?api-version=2022-10-31-preview

此要求的回應如下列範例所示：

{
  "id": "802894c4-33bc-4f1e-ad64-e886f315cece",
  "displayName": "Enriched Export",
  "enabled": true,
  "source": "telemetry",
  "enrichments": {
    "Custom data": {
      "value": "My value"
    }
  },
  "destinations": [
    {
      "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
    }
  ],
  "status": "healthy"
}

列出匯出定義

可使用下列要求，從您的應用程式擷取匯出清單：

GET https://{your app subdomain}/api/dataExport/exports?api-version=2022-10-31-preview

此要求的回應如下列範例所示：

{
  "value": [
    {
      "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
      "displayName": "Enriched Export",
      "enabled": true,
      "source": "telemetry",
      "enrichments": {
        "Custom data": {
          "value": "My value"
        }
      },
      "destinations": [
        {
          "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
      ],
      "status": "starting"
    },
    {
      "id": "802894c4-33bc-4f1e-ad64-e886f315cece",
      "displayName": "Enriched Export",
      "enabled": true,
      "source": "telemetry",
      "enrichments": {
        "Custom data": {
          "value": "My value"
        }
      },
      "destinations": [
        {
          "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
      ],
      "status": "healthy"
    }
  ]
}

修補匯出定義

PATCH https://{your app subdomain}/dataExport/exports/{exportId}?api-version=2022-10-31-preview

您可以使用此呼叫對某項匯出執行累加式更新。範例要求本文會如下列範例所示，會將 enrichments 更新至匯出：

{
    "enrichments": {
        "Custom data": {
            "value": "My value 2"
        }
    }
}

此要求的回應如下列範例所示：

{
    "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value 2"
        }
    },
    "destinations": [
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
    ],
    "status": "healthy"
}

刪除匯出定義

可使用下列要求來刪除匯出定義：

DELETE https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

下一步

現在您已了解如何使用 REST API 匯出資料，下一個建議步驟請參考如何使用 IoT Central REST API 來管理裝置範本。

共用方式為

如何使用 IoT Central REST API 管理資料匯出

資料匯出

建立或更新目的地

依識別碼取得目的地

列出目的地

修補目的地

刪除目的地

建立或更新匯出定義

擴充

篩選

依識別碼取得匯出

列出匯出定義

修補匯出定義

刪除匯出定義

下一步

意見反應

其他資源