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

本教學課程說明如何使用 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 用於授權的持有人權杖。

• 在 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。

Postman

在本教學課程中，您會使用 Postman 進行 REST API 呼叫。 如果您不想下載並安裝 Postman，則可以使用線上版本。 您可以使用免費的 Postman 版本來完成教學課程中的所有步驟。

本教學課程使用預先定義的 Postman 集合，其中包含一些指令碼，以協助您完成各個步驟。

匯入 Postman 集合

若要匯入集合，請開啟Postman，然後選取 [匯入]。 在 [匯入] 對話方塊中，選取 [連結] 並貼上下列 URL，然後選取 [繼續]。

您的工作區現在包含 IoT Central REST 教學課程集合。 此集合包含您在教學課程中使用的所有 API。

集合會使用變數來參數化 REST API 呼叫。 若要查看變數，請選取 IoT Central REST 教學課程旁的 ...，然後選取 [編輯]。 然後選取 [變數]。 當您進行 API 呼叫或具有預設值時，許多變數都會自動設定。

授權 REST API

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

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

將值指派給 Postman 集合中的下列變數：

• bearerToken：執行下列 Azure CLI 命令，以產生可授權存取 的 https://management.azure.com 持有人權杖：

  az login
  az account get-access-token --resource https://management.azure.com
  

  提示

  即使您使用 Cloud Shell，您仍可能需要執行 az login。

  將 accessToken 值複製到集合變數中 bearerToken 的 [目前值] 資料行。

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

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

  提示

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

  將 accessToken 值複製到集合變數中 bearerTokenApp 的 [目前值] 資料行。

• subscriptionId：您的訂用帳戶識別碼包含在先前兩個命令的輸出中。 將 subscription 值複製到集合變數中 subscriptionId 的 [目前值] 資料行。

請務必將變更儲存至 Postman 集合。

注意

持有人權杖會在一小時後到期。

建立應用程式

您可以使用控制平面要求來建立和管理 IoT Central 應用程式。 使用下列 PUT 要求來建立您在本教學課程中使用的應用程式。 要求會使用持有人權杖來授權並產生隨機的應用程式名稱。

1. 在 Postman 中，開啟 IoT Central REST 教學課程集合，然後選取 [建立 IoT Central 應用程式] 要求。
2. 請選取傳送。
3. 檢查要求是否成功。 如果失敗，請確認您已在Postman集合中輸入 bearerToken 和 subscriptionId 變數值。
4. 選取 [視覺化] 以查看新 IoT Central 應用程式的 URL。 請記下此 URL，稍後在本教學課程中需要它。

建立 API 權杖

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

1. 在 Postman 中，開啟 IoT Central REST 教學課程集合，然後選取 [建立操作員權杖] 要求。
2. 請選取傳送。
3. 在 Postman 中，開啟 IoT Central REST 教學課程集合，然後選取 [建立管理員權杖] 要求。
4. 請選取傳送。

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

注意

Postman 中的指令碼會自動為您將這些 API 權杖新增至集合變數清單。

註冊裝置

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

1. 在 Postman 中，開啟 IoT Central REST 教學課程集合，然後選取 [新增裝置] 要求。
2. 請選取傳送。 在回應中，請注意裝置並未佈建。
3. 在 Postman 中，開啟 IoT Central REST 教學課程集合，然後選取 [取得裝置認證] 要求。
4. 請選取傳送。
5. [視覺化] 索引標籤會顯示裝置必須能夠連線的 [識別碼範圍] 和 [主索引鍵] 值。

佈建和連線裝置

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

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

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

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

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

1. 在您的智慧型手機上開啟 IoT PnP 應用程式。

2. 在歡迎頁面上，選取 [掃描 QR 代碼]。 將智慧型手機的相機指向 QR 代碼。 然後在建立連線時等候幾秒鐘。

3. 在應用程式的遙測資料頁面上，您可以看到應用程式正在傳送至 IoT Central 的資料。 在記錄頁面上，您可以看到連線的裝置和數則初始化訊息。

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

1. 在 Postman 中，開啟 IoT Central REST 教學課程集合，然後選取 [取得裝置] 要求。
2. 請選取傳送。 在回應中，請注意裝置現在已佈建。 IoT Central 也會根據裝置所傳送的型號標識碼，將裝置範本指派給裝置。

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

1. 在 Postman 中，開啟 IoT Central REST 教學課程集合，然後選取 [列出裝置範本] 要求。
2. 請選取傳送。

查詢和控制裝置

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

1. 在 Postman 中，開啟 IoT Central REST 教學課程集合，然後選取 [執行查詢] 要求。
2. 請選取傳送。

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

1. 在 Postman 中，開啟 IoT Central REST 教學課程集合，然後選取 [從元件取得屬性] 要求。
2. 請選取傳送。

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

1. 在 Postman 中，開啟 IoT Central REST 教學課程集合，然後選取 [呼叫命令] 要求。
2. 請選取傳送。

匯出遙測

您可以使用 REST API 來設定和管理 IoT Central 應用程式。 下列步驟示範如何設定資料匯出，以將遙測值傳送至 Webhook。 為了簡化設定，本文使用 RequestBin Webhook 作為目的地。 RequestBin 是非Microsoft服務。

若要建立資料匯出目的地的測試端點：

1. 瀏覽至 RequestBin。
2. 選取 [建立 RequestBin]。
3. 使用其中一個可用方法登入。
4. 複製 RequestBin 端點的 URL。
5. 在 Postman 中，開啟 IoT Central REST 教學課程集合並瀏覽至集合變數。
6. 將 RequestBin 端點的 URL 貼入集合變數中 webHookURL 的 [目前值] 資料行。
7. 儲存變更。

若要使用 REST API 在 IoT Central 應用程式中設定匯出目的地：

1. 在 Postman 中，開啟 IoT Central REST 教學課程集合，然後選取 [建立 Webhook 匯出目的地] 要求。
2. 請選取傳送。

若要使用 REST API 在 IoT Central 應用程式中設定匯出定義：

1. 在 Postman 中，開啟 IoT Central REST 教學課程集合，然後選取 [建立遙測匯出定義] 要求。
2. 請選取傳送。 請注意，狀態為 [未啟動]。

匯出可能需要幾分鐘的時間才能啟動。 若要使用 REST API 檢查匯出的狀態：

1. 在 Postman 中，開啟 IoT Central REST 教學課程集合，然後選取 [依識別碼取得匯出] 要求。
2. 請選取傳送。 當狀態狀況良好時，IoT Central 會將遙測傳送至您的 Webhook。

您智慧型手機上的應用程式不會傳送遙測資料，除非畫面已開啟，且顯示 IoT 隨插即用應用程式。

當您的智慧型手機應用程式傳送遙測時，請瀏覽至 RequestBin 以檢視匯出的遙測。

清除資源

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

1. 在 Postman 中，開啟 IoT Central REST 教學課程集合，然後選取 [刪除 IoT Central 應用程式] 要求。
2. 請選取傳送。

提示

此要求會使用您在教學課程開始時產生的持有人權杖。 持有人權杖會在一小時後到期。 您可能需要產生新的持有人權杖，以授權存取 https://apps.azureiotcentral.com。

下一步

如果您想要繼續進行這套 IoT Central 教學課程並深入了解如何建置 IoT Central 解決方案，請參閱：

建立閘道裝置範本