共用方式為

如何使用 Postman 將要求傳送至 Azure Digital Twins API

  • 發行項

Postman 是一個 REST 測試工具，可在桌面或外掛程式型 GUI 提供重要的 HTTP 要求功能。 您可以用來製作 HTTP 要求，並將提交至 Azure Digital Twins REST API。 本文說明如何設定 Postman REST 用戶端與 Azure Digital Twins API 互動。 本資訊是針對 Azure Digital Twins 服務。

本文包含下列步驟的相關資訊：

  1. 使用 Azure CLI 來取得持有人權杖，您將會用來在 Postman 中提出 API 要求。
  2. 設定 Postman 集合並且設定 Postman REST 用戶端以使用您的持有人權杖進行驗證。 設定集合時，您可以選擇下列其中一個選項：
    1. 匯入預先建置的 Azure Digital Twins API 要求集合。
    2. 從頭開始建立您自己的集合。
  3. 將要求新增至已設定的集合，並將其傳送至 Azure Digital Twins API。

Azure Digital Twins 有兩組 API 可供您使用：資料平面和控制平面。 如需這些 API 集合之間差異的詳細資訊，請參閱 Azure Digital Twins API 和 SDK。 本文包含這兩個 API 集合的資訊。

必要條件

若要繼續使用 Postman 來存取 Azure Digital Twins API，您需要設定 Azure Digital Twins 執行個體並下載 Postman。 本節的其餘部分會引導您完成這些步驟。

設定 Azure Digital Twins 執行個體

若要使用本文中的 Azure Digital Twins，您必須要有 Azure Digital Twins 執行個體，以及必要的使用權限。 如果您已經設定好 Azure Digital Twins 執行個體，您可以直接使用該執行個體，並跳至下一節。 否則，請依照設定執行個體和驗證中的指示進行。 指示中包含的資訊可協助您確認已成功完成每個步驟。

設定執行個體之後，請記下執行個體的主機名稱。 您可以在 Azure 入口網站中找到主機名稱。

下載 Postman

接下來，下載 Postman 用戶端的桌面版本。

取得持有人權杖

既然您已設定 Postman 和 Azure Digital Twins 執行個體，您必須取得 Postman 要求可用來授權 Azure Digital Twins API 的持有人權杖。

有數種可能的方法可以取得此權杖。 本文使用 Azure CLI 來登入您的 Azure 帳戶，並且取得權杖。

如果您已經在本機安裝 Azure CLI，您可以在電腦上啟動命令提示字元，以執行下列命令。 否則，您可以在瀏覽器中開啟 Azure Cloud Shell 視窗，並在該處執行命令。

  1. 首先，執行下列命令，確定您已使用適當的認證登入 Azure：

    az login

  2. 接下來，使用 az account get-access-token 命令以取得具有 Azure Digital Twins 服務存取權的持有人權杖。 在此命令中，您將會傳入 Azure Digital Twins 服務端點的資源識別碼，以取得可存取 Azure Digital Twins 資源的存取權杖。

    權杖的必要內容取決於您所使用的 API 集合，因此請使用下列索引標籤來選取資料平面和控制平面 API。

    若要取得與資料平面 API 搭配使用的權杖，請針對權杖內容使用下列靜態值：0b07f429-9f4b-4714-9392-cc5e8e80c8b0。 此值是 Azure Digital Twins 服務端點的資源識別碼。

    az account get-access-token --resource 0b07f429-9f4b-4714-9392-cc5e8e80c8b0

    注意

    如果您需要使用屬於執行個體不同 Microsoft Entra 租用戶的服務本文或使用者帳戶來存取 Azure Digital Twins 執行個體，則必須向 Azure Digital Twins 執行個體的「主」租用戶要求權杖。 如需此程序的詳細資訊，請參閱撰寫應用程式驗證程式碼。

  3. 複製結果中 accessToken 的值，並且儲存該值以在下一節中使用。 此值是您提供給 Postman 來授權要求的權杖值。

    Screenshot of the console showing the result of the az account get-access-token command. The accessToken field with its sample value highlighted.

提示

此權杖的有效時間至少五分鐘，最多 60 分鐘。 如果分配給目前權杖的時間用完，您可以重複本節的步驟，以取得新的權杖。

接下來，您將會設定 Postman 使用此權杖向 Azure Digital Twins 提出 API 要求。

關於 Postman 集合

Postman 中的要求儲存在集合中 (要求群組)。 建立集合來組合要求可將常用設定一次套用至許多要求。 如果打算針對 Azure Digital Twins API 建立多個要求，通用設定可以大幅簡化授權，因為您只需要為整個集合設定這些詳細資料一次。

使用 Azure Digital Twins 時，首先可以匯入為所有 Azure Digital Twins 要求預先建立的集合。 如果您要探索 API，且想要使用要求範例快速設定專案，您可能會想要匯入此集合。

或者，您也可以選擇從頭開始，建立自己的空白集合，並填入只呼叫您所需 API 的個別要求。

下列各節說明這兩個程序。 本文的其餘部分會在您的本機 Postman 應用程式中進行，因此請立即在電腦上開啟 Postman 應用程式。

匯入 Azure Digital Twins API 的集合

在 Postman 中開始使用 Azure Digital Twins 的快速方法是匯入針對 API 預先建置的要求集合。 請遵循下列步驟來匯入包含範例要求資料的常用 Azure Digital Twins 資料平面 API 要求集合。

  1. 從 Postman 主視窗中，選取 [匯入] 按鈕。 Screenshot of a newly opened Postman window. The 'Import' button is highlighted.

  2. 在後續的 [匯入] 視窗中，選取 [連結]，然後輸入下列 URL：https://raw.githubusercontent.com/microsoft/azure-digital-twins-postman-samples/main/postman_collection.json。 然後選取 [匯入] 以確認。

    Screenshot of Postman's 'Import' window, showing the file to import as a collection and the Import button.

現在，從 Postman 主要檢視的 [集合] 索引標籤中，可看到剛匯入的集合。

Screenshot of the main Postman window. The newly imported collection is highlighted in the 'Collections' tab.

提示

若要匯入特定版本 Azure Digital Twins API 的一組完整 API 呼叫 (包括控制平面或資料平面)，您也可以將 Swagger 檔案匯入為集合。 如需控制平面和資料平面 API 的 Swagger 檔案連結，請參閱 Azure Digital Twins API 和 SDK。

接下來，繼續進行下一節，將持有人權杖新增至集合以進行授權，並將其連線至您的 Azure Digital twins 執行個體。

設定授權

接下來，編輯您已建立的集合，以設定一些存取詳細資料。 醒目提示您已建立的集合，然後選取 [檢視更多動作] 圖示以顯示動作選項。 選取編輯。

Screenshot of Postman. The 'View more actions' icon for the imported collection is highlighted, and 'Edit' is highlighted in the options.

遵循下列步驟，將持有人權杖新增至集合以準備授權。 使用您在 [取得持有人權杖] 區段所收集權杖值的位置，以便將其用於集合中的所有 API 要求。

  1. 在集合的編輯對話方塊中，確定您位於 [授權] 索引標籤上。

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. 將 [類型] 設定為 [OAuth 2.0]，將存取權杖貼到 [存取權杖] 方塊中。 您必須針對所使用的 API 類型使用正確的權杖，因為資料平面 API 與控制平面 API 有不同的權杖。 選取 [儲存]。

    Screenshot of Postman edit dialog for the imported collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

    提示

    如果您想要將權杖與 Postman 雲端上的要求一起儲存，且可能會與其他人共用權杖，您可以選擇開啟權杖共用。

其他設定

您可以設定集合隨附的一些變數，以協助集合輕鬆連線至您的 Azure Digital Twins 資源。 當集合中的許多要求需要相同的值時 (例如 Azure Digital Twins 執行個體的主機名稱)，您可以將值儲存在變數中，以套用至集合中的每個要求。 Azure Digital Twins 集合隨附可在集合層級設定的預先建立變數。

  1. 仍在集合的編輯對話方塊中，移至 [變數] 索引標籤。

  2. 使用下表來設定集合中變數的值：

    變數 API 集合 描述
    digitaltwins-hostname 資料平面 您的 Azure Digital Twins 執行個體主機名稱。 您可以在入口網站中執行個體的概觀頁面上找到此值。
    subscriptionId 控制平面 您的 Azure 訂用帳戶識別碼。
    digitalTwinInstance 控制平面 Azure Digital Twins 執行個體的名稱。

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Variables' tab. The 'CURRENT VALUE' field is highlighted.

  3. 如果集合有額外變數，請一併填入並儲存這些值。

  4. 選取 [儲存]。

完成上述步驟時，集合也就設定完畢。 您可以關閉集合的編輯索引標籤。

探索要求

接下來，探索 Azure Digital Twins API 集合內的要求。 您可以展開集合，以檢視預先建立的要求 (依作業類別排序)。

不同的要求需要執行個體及其資料的不同資訊。 若要查看製作特定要求所需的一切資訊，請參閱 Azure Digital Twins REST API 參考文件中的要求詳細資料。

您可以使用下列步驟，在 Postman 集合中編輯要求的詳細資料：

  1. 從清單中選取要求，以提取可編輯的詳細資料。

  2. 範例集合中的大部分要求都會預先設定為執行，而不會做出任何進一步的變更。

  3. 下列螢幕擷取畫面顯示 DigitalTwinModels 新增 API。 在 [本文] 索引標籤上，您可以看到定義要新增模型的 JSON 承載：

  4. 在 [Params] 索引標籤中的 [路徑變數] 下，填入變數的值。

    Screenshot of Postman. The collection is expanded to show the body tab of a request.

  5. 若要執行要求，請使用 [傳送] 按鈕。

您也可以使用新增個別要求一節中所述的程序，將您自己的要求新增至集合。

建立您自己的集合

您也可以從頭開始建立自己的集合，而不是匯入所有 Azure Digital Twins API 的現有集合。 然後，您可以使用 Azure Digital Twins REST API 參考文件，將其填入個別要求。

建立 Postman 集合

  1. 若要建立集合，請選取主要 Postman 視窗中的 [新增] 按鈕。

    Screenshot of the main Postman window. The 'New' button is highlighted.

    選擇 [集合] 的類型。

    Screenshot of the 'Create New' dialog in Postman. The 'Collection' option is highlighted.

  2. 索引標籤隨即開啟。 填入新集合的詳細資料。 選取集合預設名稱旁的 [編輯] 圖示 ([新增集合])，將其取代為您自己選擇的名稱。

    Screenshot of the new collection's edit dialog in Postman. The Edit icon next to the name 'New Collection' is highlighted.

接下來，繼續進行下一節，將持有人權杖新增至集合以進行授權。

設定授權

遵循下列步驟，將持有人權杖新增至集合以準備授權。 使用您在 [取得持有人權杖] 區段所收集權杖值的位置，以便將其用於集合中的所有 API 要求。

  1. 仍在新集合的編輯對話方塊中，移至 [授權] 索引標籤。

    Screenshot of the new collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. 將 [類型] 設定為 [OAuth 2.0]，將存取權杖貼到 [存取權杖] 方塊中，然後選取 [儲存]。

    Screenshot of the Postman edit dialog for the new collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

完成上述步驟時，集合也就設定完畢。 您可以關閉新集合的編輯索引標籤。

從 Postman 主要檢視的 [集合] 索引標籤中，可看到新的集合。

Screenshot of the main Postman window. The newly created custom collection is highlighted in the 'Collections' tab.

新增個別要求

現在已設定您的集合，您可以將自己的要求新增至 Azure Digital Twin API。

  1. 若要建立要求，請再次使用 [新增] 按鈕。

    Screenshot of the main Postman window. The 'New' button is highlighted.

    選擇 [要求] 的類型。

    Screenshot of the 'Create New' dialog in Postman. The 'Request' option is highlighted.

  2. 此動作會開啟 [儲存要求] 視窗，您可以在其中輸入要求的名稱、提供選擇性描述，並且選擇其所屬的集合。 填寫詳細資料，並將要求儲存至您稍早建立的集合。

Screenshot of 'Save request' window in Postman showing the fields described. The 'Save to Azure Digital Twins collection' button is highlighted.

您現在可以在集合下檢視您的要求，並加以選取以提取其可編輯的詳細資料。

Screenshot of Postman. The Azure Digital Twins collection is expanded to show the request's details.

設定要求詳細資料

若要對其中一個 Azure Digital Twins API 提出 Postman 要求，您需要 API 的 URL 及其所需詳細資料的相關資訊。 您可以在 Azure Digital Twins REST API 參考文件中找到此資訊。

若要繼續進行範例查詢，本文會使用 Azure Digital Twins 查詢 API 來查詢執行個體中的所有數位對應項。

  1. 從參考文件取得要求 URL 和類型。 針對查詢 API，這目前為 POSThttps://digitaltwins-host-name/query?api-version=2020-10-31。

  2. 在 Postman 中，設定要求的類型並輸入要求 URL，並且視需要在 URL 中填入預留位置。 從必要條件區段使用執行個體的主機名稱。

    Screenshot of the new request's details in Postman. The query URL from the reference documentation has been filled into the request URL box.

  3. 檢查 [Params] 索引標籤中針對要求顯示的參數是否符合參考文件中所述的參數。 針對 Postman 中的此要求，在上一個步驟中輸入要求 URL 時，會自動填入 api-version 參數。 針對查詢 API，這是唯一的必要參數，因此這個步驟已完成。

  4. 在 [授權] 索引標籤中，將 [類型] 設定為 [從父系繼承驗證]。 這表示此要求會使用您稍早為整個集合設定的授權。

  5. 檢查 [標頭] 索引標籤中針對要求顯示的標頭是否符合參考文件中所述的標頭。 針對此要求，已自動填入數個標頭。 針對查詢 API，不需要任何標頭選項，因此這個步驟已完成。

  6. 檢查 [本文] 索引標籤中針對要求顯示的本文是否符合參考文件中所述的需求。 針對查詢 API，需要 JSON 本文才能提供查詢文字。 以下是此要求的範例本文，該要求會查詢執行個體中的所有數位對應項：

    Screenshot of the new request's details in Postman, on the Body tab. It contains a raw JSON body with a query of 'SELECT * FROM DIGITALTWINS'.

    如需製作 Azure Digital Twins 查詢的詳細資訊，請參閱查詢對應項圖表。

  7. 請查看參考文件，以取得您要求類型可能需要的任何其他欄位。 針對查詢 API，Postman 要求中現在已符合所有需求，因此這個步驟已完成。

  8. 使用 [傳送] 按鈕來傳送已完成的要求。 Screenshot of Postman showing the details of the new request. The Send button is highlighted.

傳送要求之後，回應詳細資料會出現在要求下方的 Postman 視窗中。 您可以檢視回應的狀態碼和任何本文文字。

Screenshot of the sent request in Postman. Below the request details, the response is shown. Status is 200 OK and body shows query results.

您也可以比較回應與參考文件中提供的預期回應資料，以驗證結果或深入了解任何發生的錯誤。

下一步

若要深入了解 Digital Twins API，請參閱 Azure Digital Twins API 和 SDK，或檢視 REST API 的參考文件。