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

發行項
08/08/2024

Visual Studio 2022 支援 .http 檔案，可用來建構、儲存和直接從應用程式傳送 HTTP 要求。使用 Visual Studio 的這項功能，是製作 HTTP 要求並將其提交至 Azure Digital Twins REST API 的其中一種方式。本文說明如何在Visual Studio中設定 .http 可與 Azure Digital Twins API 介面互動的檔案。

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

使用代表 Azure Digital Twins 實例的變數，設定 Visual Studio 專案和 .http 檔案。
使用 Azure CLI 取得持有人令牌，您可以在 Visual Studio 中提出 API 要求。
使用 Azure Digital Twins REST API 檔作為資源，在檔案中.http製作要求，並將其傳送至 Azure Digital Twins API。

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

如需 Visual Studio 中檔案支援的詳細資訊 .http ，請參閱在 Visual Studio 2022 中使用 .http 檔案。

必要條件

若要使用 Visual Studio 向 Azure Digital Twins API 提出要求，您必須設定 Azure Digital Twins 實例並下載 Visual Studio 2022。本節適用於這些步驟。

設定 Azure Digital Twins 執行個體

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

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

下載 Visual Studio 2022

接下來，下載Visual Studio 2022。請務必在 安裝中包含 ASP.NET 和 Web 開發 工作負載。

設定 Visual Studio 專案

在本節中，您會在 Visual Studio 中設定將用來製作 HTTP 要求的專案。

在您的電腦上開啟 Visual Studio，並建立新的專案。 使用 ASP.NET Core Empty 專案範本。

依照建立 .HTTP 檔案中的指示，在專案中建立新的.http檔案。

新增變數

接下來，在檔案頂端 .http 新增一些變數，以用來連線到您的 Azure Digital Twins 資源。

您需要的一組變數取決於您所使用的 API 集合，因此請使用下列索引標籤來選取數據平面和控制平面 API。

資料平面
控制平面

為數據平面要求新增下列變數。 Azure Digital Twins 實例的主機名有一個佔位元（其結尾為 digitaltwins.azure.net）。

@hostName=<host-name-of-your-Azure-Digital-Twins-instance>
@DPversion=2023-10-31

為控制平面要求新增下列變數。它們包含資源值的佔位元。

@instance=<name-of-your-Azure-Digital-Twins-instance>
@subscription=<ID-of-your-Azure-subscription>
@resourceGroup=<resource-group>
@CPversion=2023-01-31

新增持有人令牌

既然您已設定 Azure Digital Twins 實例和 Visual Studio 專案，您必須取得 HTTP 要求可用來授權 Azure Digital Twins API 的持有人令牌。

有多種方式可取得此令牌。本文使用 Azure CLI 來登入您的 Azure 帳戶，並以這種方式取得令牌。

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

首先，執行下列命令，確定您已使用正確的認證登入 Azure：
```
az login
```
接下來，使用 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
```
若要取得與控制平面 API 搭配使用的權杖，請針對權杖內容使用下列值：https://management.azure.com/。
```
az account get-access-token --resource https://management.azure.com/
```
注意

如果您需要使用屬於實例不同Microsoft Entra 租使用者的服務主體或使用者帳戶來存取 Azure Digital Twins 實例，您必須向 Azure Digital Twins 實例的「首頁」租使用者要求令牌。如需此程序的詳細資訊，請參閱撰寫應用程式驗證程式碼。
複製結果中的值 accessToken 。此值是您 要貼到 Visual Studio 中以授權要求的權杖值 。

提示

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

將令牌新增至 `.http` 檔案

.http在 Visual Studio 的檔案中，新增另一個保留令牌值的變數。

資料平面
控制平面

@token=<paste-data-plane-token>

您的變數現在看起來應該像這樣：

@token=<paste-control-plane-token>

您的變數現在看起來應該像這樣：

新增要求

現在已設定您的 .http 檔案，您可以將要求新增至 Azure Digital Twin API。

從開啟 Azure Digital Twins REST API 參考開始。本檔包含 API 所涵蓋之所有作業的詳細資料。流覽至您要執行之要求的參考頁面。

本文會從數據平面使用 DigitalTwins Update API 作為範例。

新增要求範本：複製參考文件中顯示的 HTTP 要求。

在 Visual Studio 中，將要求貼到檔案 .http 中變數下方的新行中。
新增參數：查看 參考檔的 URI 參數 一節，以查看要求需要哪些參數值。您可以將某些取代為您稍早建立的變數，並視需要填入其他參數值。若要參考變數，請將變數名稱放在雙大括弧中，例如 {{variable}}。如需詳細資訊，請參閱變數。

注意

對於數據平面要求， digitaltwins-hostname 也是參數。將取代為 {{hostName}} ，以使用主機名變數的值。

以下是這個步驟在範例要求中的外觀：
新增授權：在要求下方新增下列這一行（完全如撰寫的），以使用持有人令牌變數指定驗證。
```
Authorization: Bearer {{token}}
```
以下是這個步驟在範例要求中的外觀：
新增其他標頭：查看 參考檔的 [要求標頭 ] 區段，以查看哪些標頭值可以伴隨要求。您也可以包含傳統的 HTTP 標頭，例如 Content-Type。以格式 HeaderName: Value在自己的行上新增每個標頭。如需詳細資訊，請參閱要求標頭。

以下是這個步驟在範例要求中的外觀：
新增本文：查看 參考檔的 [要求本文 ] 區段，以查看要求可能需要哪些本文資訊。在空白行之後新增要求本文。如需詳細資訊，請參閱要求本文。

以下是這個步驟在範例要求中的外觀：
當要求就緒時，請選取要求上方的 [ 傳送要求 ] 以傳送要求。