教學課程：使用 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 用於授權的持有人權杖。

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 權杖。
  • 管理員istrator 和操作員 API 權杖，以授權存取 IoT Central 應用程式中的功能。 在本教學課程中，您大部分的 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 的 Current 值 資料行。

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

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

    提示

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

    將 accessToken 值 複製到集合變數中 bearerTokenApp 的 Current 值 資料行。

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

Screenshot that shows the variables set manually in the Postman collection.

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

注意

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

建立應用程式

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

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

Screenshot that shows the Visualize tab with the application URL in Postman.

建立 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 代碼 。 讓此頁面保持開啟，直到裝置連線為止。

Screenshot that shows the QR code you use to connect the device.

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

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

Get the app for your Android phone on Google Play.Download the app for your phone from the App Store.

若要將 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 來讀取和設定裝置屬性。 下列要求會從裝置實作的 Device Info 元件傳回所有屬性值：

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

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

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

匯出遙測

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

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

  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解決方案，請參閱：

建立閘道裝置範本