在 Azure Digital Twins 中建立端點
本文說明如何使用 Azure 入口網站或 Azure CLI 建立 Azure 數位對應項事件的端點。 您也可以使用 DigitalTwinsEndpoint 控制平面 API 來管理端點。
將事件通知從 Azure Digital Twins 路由傳送至下游服務或連線的計算資源是兩個步驟的程序：建立端點，然後建立事件路由以將資料傳送至這些端點。 本文涵蓋的第一個步驟會設定可接收事件的端點。 稍後，您可以建立事件路由，以指定 Azure Digital Twins 所產生的事件會傳遞至哪些端點。
必要條件
您會需要可免費設定的 Azure 帳戶
您需要 Azure 訂用帳戶中的 Azure Digital Twins 執行個體。 如果您還沒有執行個體，您可以使用設定執行個體和驗證中的步驟來建立。 請從安裝程式取得下列值，以便稍後使用於本文中：
- 執行個體名稱
- 資源群組
您可以在設定執行個體之後，於 Azure 入口網站中找到這些詳細資料。
接下來，如果您想要在遵循本指南時使用 Azure CLI，請遵循下列指示。
備妥環境以使用 Azure CLI
在 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。
建立所需的資源
這些服務是您可為執行個體建立的支援端點類型：
若要將端點連結至 Azure Digital Twins，則您針對端點所使用的事件方格主題、事件中樞或服務匯流排主題必須先存在。
使用下圖查看建立端點前應設定的資源。
| 端點類型 | 必要資源 (連結至建立指示) |
|---|---|
| 事件方格端點 | 事件方格主題 *事件結構描述必須是事件方格架構或雲端事件架構 v1.0 |
| 事件中樞端點 | 事件中樞命名空間 事件中樞 (選用) 金鑰型驗證的授權規則 |
| 服務匯流排端點 | 服務匯流排命名空間 服務匯流排主題 (選用) 金鑰型驗證的授權規則 |
建立端點
當您建立端點資源後，即可將其用於 Azure Digital Twins 端點。
若要建立新的端點，請移至 Azure 入口網站中的執行個體頁面 (您可以在入口網站搜尋列中輸入其名稱，以尋找執行個體)。
從執行個體功能表中，選取 [端點]。 然後，從後續的 [端點] 頁面中，選取 [+ 建立端點]。 這麼做會開啟 [建立端點] 頁面，而您會在下列步驟中填入該頁面中的欄位。
輸入端點的 [名稱]，然後選擇 [端點類型]。
完成端點類型所需的其他詳細資料，包含您的訂用帳戶與稍早所述的端點資源。
- 僅針對事件中樞和服務匯流排端點，您必須選取 [驗證類型]。 您可以使用金鑰型驗證搭配預先建立的授權規則，或是系統指派或使用者指派的受控識別。 如需使用身分識別驗證選項的詳細資訊，請參閱端點選項：身分識別型驗證。
選取 [儲存]，完成建立端點。
建立端點後，您可以檢查頂端 Azure 入口網站列中的通知圖示，並確認已成功建立端點：
如果端點建立失敗，觀察錯誤訊息，並於幾分鐘後重試。
您也可以檢視在 Azure Digital Twins 執行個體的 [端點] 頁面上建立的端點。
現在，事件方格主題、事件中樞或服務匯流排主題可在您為端點選擇的名稱下，做為 Azure Digital Twins 中的端點使用。 您通常會使用該名稱做為事件路由的目標，您可在建立路由和篩選條件中加以建立。
端點選項：身分識別型驗證
本節描述如何在將事件轉送至支援的路由目的地時，針對 Azure Digital Twins 執行個體使用受控識別。 不需要設定受控識別即可進行路由，但其可協助執行個體輕鬆地存取其他受 Microsoft Entra 保護的資源，例如事件中樞、服務匯流排目的地和 Azure 儲存體容器。 受控識別可以是系統指派或使用者指派。
本節的其餘部分會逐步解說使用受控識別設定端點的三個步驟。
1.啟用執行個體的受控識別
使用下列索引標籤來取得符合您慣用體驗的指示。
首先，請確定您已為 Azure Digital Twins 執行個體啟用受控識別。
此外，確定您在執行個體上具有 Azure Digital Twins 資料擁有者角色。 您可以在設定使用者存取權限中找到指示。
2.將 Azure 角色指派給身分識別
一旦針對 Azure Digital Twins 執行個體建立了受控識別，您就必須為其指派適當的角色，以不同類型的端點進行驗證，以便將事件路由至支援的目的地。 本節描述角色選項，以及如何將其指派給受控識別。
重要
請務必完成此步驟。 若沒有此步驟，身分識別將無法存取您的端點，而且不會傳遞事件。
以下是您 Azure Digital Twins 身分識別存取端點所需的最低角色，取決於目的地類型。 具有較高權限的角色 (例如，資料擁有者角色) 也適用。
| Destination | Azure 角色 |
|---|---|
| Azure 事件中樞 | Azure 事件中樞資料傳送者 |
| Azure 服務匯流排 | Azure 服務匯流排資料傳送者 |
| Azure 儲存體容器 | 儲存體 Blob 資料參與者 |
使用下列索引標籤，以使用您慣用的體驗來指派角色。
若要將角色指派給身分識別，首先在瀏覽器中開啟 Azure 入口網站。
瀏覽至端點資源 (事件中樞、服務匯流排主題或儲存體容器)，方法是在入口網站搜尋列中搜尋其名稱。
選取 [存取控制 (IAM)]。
選取 [新增 > 角色指派 ] 以開啟 [新增角色指派] 頁面。
使用下列資訊，將所需的角色指派給 Azure Digital Twins 執行個體的受控識別。 如需詳細步驟，請參閱使用 Azure 入口網站指派 Azure 角色。
設定 值 角色 從選項中選取所需的角色。 存取權指派對象 受控識別 成員 選取要獲指派角色 Azure Digital Twins 執行個體的系統指派受控識別。 使用者指派的身分識別將會採用在您建立身分識別時所選擇的名稱，而系統指派的身分識別將會採用符合您 Azure Digital Twins 執行個體名稱的名稱。 
3.建立具有身分識別型驗證的端點
在針對 Azure Digital Twins 執行個體設定受控識別，並將適當的角色指派給該受控識別之後，您可以建立 Azure Digital Twins 端點，使用身分識別進行驗證。 此選項僅適用於事件中樞和服務匯流排類型端點 (並不支援事件方格)。
注意
您無法編輯已使用金鑰型身分識別建立的端點，以變更為身分識別型驗證。 第一次建立端點時，您必須選擇驗證類型。
使用下列索引標籤，以使用您慣用的體驗來建立端點。
開始遵循一般指示來建立 Azure Digital Twins 端點。
當您進入完成端點類型所需詳細資料的步驟時，請針對 [驗證類型] 選取 [系統指派] 或 [使用者指派 (預覽)]。
完成端點的設定，然後選取 [儲存]。
停用受控識別的考量
由於身分識別會與使用其的端點分開管理，因此請務必考慮對身分識別或其角色所做的任何變更在 Azure Digital Twins 執行個體中的端點上可能具有的效果。 如果已停用身分識別，或從中移除端點的必要角色，端點可能會變成無法存取，而且事件流程將會中斷。
若要繼續使用已停用之受控識別所設的端點，您必須刪除該端點，然後用不同的驗證類型重新建立該端點。 做完此變更之後，事件最多可能要花一小時才能重新傳遞至端點。
端點選項：無效信件處理
當端點無法在某個時間週期內或嘗試傳遞事件一定次數之後傳遞事件時，可以將未傳遞的事件傳送至儲存體帳戶。 此程序稱為無效化。
您可以使用 Azure 入口網站或 Azure Digital Twins CLI 來設定必要的儲存體資源。 不過，若要建立已啟用無效信件的端點，您必須使用 Azure Digital Twins CLI 或 控制平面 API。
若要深入了解無效信件，請參閱端點和事件路由。 如需有關如何以無效信件設定端點的指示，請繼續瀏覽本節的其他部分。
設定儲存體資源
在設定無效信件位置之前，您必須先在 Azure 帳戶中，有具備容器的儲存體帳戶。
當您建立端點時，您會提供此容器的 URL。 無效信件位置會以具有 SAS 權杖的容器 URI 形式，提供給端點。 對於儲存體帳戶內的目的地容器，該權杖需要 write 權限。 無效信件 SAS URI 的完整格式，將會採下述格式：https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>。
請遵循下列步驟，在您的 Azure 帳戶中設定這些儲存體資源，以準備在下一節中設定端點連線。
建立 SAS 權杖
接下來，為您的儲存體帳戶建立端點可使用的 SAS 權杖，以存取至該帳戶。
從瀏覽至 Azure 入口網站中的儲存體帳戶開始 (您可以使用入口網站搜尋列，並依名稱找到)。
在儲存體帳戶頁面中，選擇左側導覽列中的 [共用存取簽章] 連結，以開始設定 SAS 權杖。
在共用存取簽章頁面的 [允許的服務] 和 [允許的資源類型] 底下，選取您想要的任何設定。 您必須在每個類別中，至少選取一個方塊。 在 [允許的權限] 下，選擇 [寫入] (如果您想要，也可以選取其他權限)。
針對其餘設定，設定您想要的任何值。
當您完成時，選取 [產生 SAS 和連接字串] 按鈕，以產生 SAS 權杖。
這麼做會在相同頁面底部的設定選取範圍下，產生數個 SAS 和連接字串。 向下捲動以檢視值，並使用 [複製到剪貼簿] 圖示來複製 SAS 權杖值。 將其儲存，以供稍後使用。
建立無效信件端點
若要建立已啟用無效信的端點，您必須使用 CLI 命令或控制平面 API 來建立端點，而非 Azure 入口網站。
如需如何使用 Azure CLI 建立此端點類型的指示，請切換至本節的 CLI 索引標籤。
訊息儲存體結構描述
當您設定完無效信件的端點之後，無效信件的訊息即會以下列格式儲存在您的儲存體帳戶中：
<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json
無效訊息會相符原本要傳遞至原始端點的原始事件結構描述。
以下是對應項建立通知的無效信件訊息範例：
{
"specversion": "1.0",
"id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
"type": "Microsoft.DigitalTwins.Twin.Create",
"source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
"data": {
"$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
"$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
"TwinData": "some sample",
"$metadata": {
"$model": "dtmi:test:deadlettermodel;1",
"room": {
"lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
}
}
},
"subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
"time": "2020-10-14T01:11:49.3667224Z",
"datacontenttype": "application/json",
"traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}
下一步
若要實際將資料從 Azure Digital Twins 傳送至端點，您必須定義事件路由。 這些路由可讓開發人員在整個系統內及下游服務連接事件流程。 單一路由可選取多個通知和事件種類。 繼續在建立路由和篩選條件中建立事件路由至您的端點。