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

發行項
07/25/2023

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 參考。

提示

您可以使用 Postman 來試用本文中所述的 REST API 呼叫。下載 IoT Central Postman 集合並匯入 Postman 中。在該集合中，您必須設定變數，例如應用程式子網域和管理員權杖。

若要了解如何使用 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 Destination",
  "type": "blobstorage@v1",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
  "containerName": "central-data"
}

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

displayName：目的地的顯示名稱。
type：目的地物件的類型。其中一個： blobstorage@v1 、、 dataexplorer@v1eventhubs@v1 、 servicebusqueue@v1 、 servicebustopic@v1 、 webhook@v1 。
connectionString：用來存取目的地資源的連接字串。
containerName：對於 Blob 儲存體目的地應寫入資料的容器名稱。

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

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=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": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=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": "connectionString",
                "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=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

您可以使用此呼叫來執行匯出的累加式更新。範例要求本文看起來像下列更新 connectionString 目的地的範例：

{
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net"
}

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

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "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 欄位，只匯出 accelerometer-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 欄位，只匯出遙測值大於屬性的 temperaturetargetTemperature 訊息：

{
  "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": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage Destination",
    "type": "blobstorage@v1",
    "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
    "containerName": "central-data",
    "status": "waiting"
}

列出匯出定義

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

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 管理資料匯出

資料匯出

建立或更新目的地

依識別碼取得目的地

列出目的地

修補目的地

刪除目的地

建立或更新匯出定義

擴充

篩選器

依識別碼取得匯出

列出匯出定義

修補匯出定義

刪除匯出定義

下一步

其他資源