共用方式為


教學課程:使用 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 權杖。
  • 授權存取 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 集合中手動設定變數的螢幕擷取畫面。

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

注意

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

建立應用程式

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

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

顯示 Postman 中 [視覺化] 索引標籤以及應用程式 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 代碼]。 讓此頁面保持開啟,直到裝置連線為止。

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

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

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

在 Google Play 上取得 Android 手機的應用程式。從 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 來讀取和設定裝置屬性。 下列要求會從裝置實作的裝置資訊元件傳回所有屬性值:

  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 解決方案,請參閱: