教學課程：使用 REST API 來管理 Azure IoT Central 應用程式

發行項
11/09/2024

本教學課程說明如何使用 Azure IoT Central REST API 來建立 IoT Central 應用程式並與其互動。本教學課程使用 REST API 完成許多您在快速入門中使用 Web UI 完成的步驟。這些步驟包括使用智慧型手機上的應用程式作為連線到 IoT Central 的 IoT 裝置。

在本教學課程中，您會了解如何：

授權 REST API。
建立 IoT Central 應用程式。
將裝置新增至您的應用程式。
查詢和控制裝置。
設定資料匯出。
刪除應用程式。

必要條件

若要完成本教學課程中的步驟，您需要：

啟用中的 Azure 訂用帳戶。如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。
您可以從其中一個官方應用程式市集安裝免費應用程式的 Android 或 iOS 智慧型手機。

Azure CLI

您可以使用 Azure CLI 進行 REST API 呼叫，併產生某些 REST API 用於授權的持有人令牌。

在 Azure Cloud Shell 中使用 Bash 環境。如需詳細資訊，請參閱 Azure Cloud Shell 中的 Bash 快速入門。
若要在本地執行 CLI 參考命令，請安裝 Azure CLI。若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。如需詳細資訊，請參閱〈如何在 Docker 容器中執行 Azure CLI〉。
- 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。請遵循您終端機上顯示的步驟，完成驗證程序。如需其他登入選項，請參閱使用 Azure CLI 登入。
- 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。如需擴充功能詳細資訊，請參閱使用 Azure CLI 擴充功能。
- 執行 az version 以尋找已安裝的版本和相依程式庫。若要升級至最新版本，請執行 az upgrade。

授權 REST API

您必須先設定授權，才能使用 REST API。本教學課程中的 REST API 呼叫會使用兩種授權類型的其中一種：

授權存取 https://apps.azureiotcentral.com 的持有人權杖。您可以使用此持有人權杖在 IoT Central 應用程式中建立 API 權杖。
授權存取 IoT Central 應用程式中功能的系統管理員和操作員 API 權杖。在本教學課程中，您會針對大部分的 API 呼叫使用這些權杖。這些權杖只會授權存取一個特定的 IoT Central 應用程式。

執行下列 Azure CLI 命令，以產生授權存取 https://apps.azureiotcentral.com的持有人令牌：

az account get-access-token --resource https://apps.azureiotcentral.com

提示

如果您已啟動殼層的新執行個體，請再次執行 az login。

記下 accessToken 值，您稍後會在教學課程中使用它。

注意

持有人權杖會在一小時後到期。如果過期，請執行相同的命令來產生新的持有人令牌。

建立資源群組

使用 Azure cli 建立資源群組，其中包含您在本教學課程中建立的 IoT Central 應用程式：

az group create --name iot-central-rest-tutorial --location eastus

建立 IoT Central 應用程式

使用下列命令，以隨機名稱產生IoT Central應用程式，以在本教學課程中使用：

appName=app-rest-$(date +%s)

az iot central app create --name $appName --resource-group iot-central-rest-tutorial --subdomain $appName

記下應用程式名稱，稍後在本教學課程中使用它。

建立 API 權杖

使用下列資料平面要求，在 IoT Central 應用程式中建立應用程式 API 權杖。本教學課程中的某些要求需要具有系統管理員權限的 API 權杖，但大部分可以使用操作員權限：

若要使用 Azure CLI 建立呼叫 operator-token 的操作員令牌，請執行下列命令。角色 GUID 是所有 IoT Central 應用程式中操作員角色的識別碼：

appName=<the app name generated previously>
bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/operator-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ae2c9854-393b-4f97-8c42-479d70ce626e"}]}'

記下命令傳回的操作員令牌，稍後在本教學課程中使用它。權杖看起來像 SharedAccessSignature sr=2...。

若要使用 Azure CLI 建立呼叫 admin-token 的管理員令牌，請執行下列命令。角色 GUID 是所有 IoT Central 應用程式中系統管理員角色的識別碼：

$appName=<the app name generated previously>
$bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/admin-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"}]}'

記下命令傳回的管理員令牌，您稍後會在教學課程中使用它。權杖看起來像 SharedAccessSignature sr=2...。

如果您想要在 IoT Central 應用程式中看到這些權杖，請開啟應用程式並瀏覽至 [安全性] > [權限] > [API 權杖]。

註冊裝置

您必須先向 IoT Central 註冊裝置，才能進行連線。使用下列要求在應用程式中註冊您的裝置，並擷取裝置認證。第一個要求會建立具有 phone-001 作為裝置識別碼的裝置：

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"displayName": "My phone app","simulated": false,"enabled": true}'

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/credentials?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

記下命令傳回的 idScope 和 primaryKey 值，您會在稍後的教學課程中使用它們。

佈建和連線裝置

若要避免需要在智慧型手機上手動輸入裝置認證，您可以使用 IoT Central 所產生的 QR 代碼。 QR 代碼會編碼裝置識別碼、識別碼範圍、主索引鍵。若要顯示 QR 代碼：

使用您先前記下的應用程式 URL 來開啟 IoT Central 應用程式。
在您的 IoT Central 應用程式中，瀏覽至 [裝置] > [我的手機應用程式] > [連線] > [QR 代碼]。讓此頁面保持開啟，直到裝置連線為止。

顯示您用來連接裝置的 QR 代碼的螢幕擷取畫面。

為了簡化設定，本文使用 IoT 隨插即用智慧手機應用程式作為 IoT 裝置。應用程式會傳送從智慧型手機感應器收集的遙測、回應從 IoT Central 叫用的命令，並將屬性值報告至 IoT Central。

從其中一個應用程式市集將應用程式安裝在您的智慧型手機上：

若要將 IoT 隨插即用應用程式連線到 IoT Central 應用程式：

在您的智慧型手機上開啟 IoT PnP 應用程式。
在歡迎頁面上，選取 [掃描 QR 代碼]。將智慧型手機的相機指向 QR 代碼。然後在建立連線時等候幾秒鐘。
在應用程式的遙測資料頁面上，您可以看到應用程式正在傳送至 IoT Central 的資料。在記錄頁面上，您可以看到連線的裝置和數則初始化訊息。

若要確認裝置現已佈建，您可以使用 REST API：

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

template記下命令傳回的值，稍後在教學課程中使用它。

您可以使用 REST API 來管理應用程式中的裝置範本。例如，若要檢視應用程式中的裝置範本：

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/deviceTemplates?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

查詢和控制裝置

您可以使用 REST API 從您的裝置查詢遙測。下列要求會從共用特定裝置範本識別碼的所有裝置傳回加速計資料：

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
deviceTemplateId=<the device template Id you made a note of previously>
q1='{"query": "SELECT $id as ID, $ts as timestamp, sensors.accelerometer FROM '
q2=' WHERE WITHIN_WINDOW(P1D) AND sensors.accelerometer <> NULL"}'
query="$q1 $deviceTemplateId $q2"
echo $query

az rest --method post --uri https://$appName.azureiotcentral.com/api/query?api-version=2022-10-31-preview --headers Authorization="$operatorToken" "Content-Type=application/json" --body "$query"

您可以使用 REST API 來讀取和設定裝置屬性。下列要求會從裝置實作的裝置資訊元件傳回所有屬性值：

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/components/device_info/properties?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

您可以使用 REST API 來呼叫裝置命令。下列要求會呼叫一個命令，讓智慧型手機上的切換開關亮起三秒兩次。若要讓命令執行，您的智慧型手機畫面必須開啟，且顯示 IoT 隨插即用應用程式：

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method post --uri https://$appName.azureiotcentral.com/api/devices/phone-001/commands/lightOn?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"duration": 3, "delay": 1, "pulses": 2}'

清除資源

如果您已完成本教學課程中使用的 IoT Central 應用程式，您可以將其刪除：

appName=<the app name generated previously>

az iot central app delete --name $appName --resource-group iot-central-rest-tutorial

共用方式為