在 Azure Digital Twins 中建立端點
本文說明如何使用 Azure 入口網站 或 Azure CLI 建立 Azure Digital Twin 事件的 端點 。 您也可以使用 DigitalTwinsEndpoint 控制平面 API 來管理端點。
將事件通知 從 Azure Digital Twins 路由 傳送至下游服務或連線的計算資源是兩個步驟的程式：建立端點，然後建立事件路由以將資料傳送至這些端點。 本文涵蓋第一個步驟，設定可接收事件的端點。 稍後，您可以建立 事件路由 ，以指定 Azure Digital Twins 所產生的事件會傳遞至哪些端點。
必要條件
您需要 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 入口網站 或 Azure Digital Twins CLI 來設定必要的儲存體資源 。 不過，若要建立已啟用無效信件的端點，您必須使用 Azure Digital Twins CLI 或 控制平面 API 。
若要深入瞭解寄不出的信件，請參閱 端點和事件路由 。 如需有關如何使用寄不出的字母設定端點的指示，請繼續進行本節的其餘部分。
設定儲存體資源
在設定寄不出的信件位置之前，您必須具有 在 Azure 帳戶中設定容器 的儲存體帳戶 。
您稍後會在建立端點時提供此容器的 URI。 寄不出的信件位置會以具有 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 傳送至端點，您必須定義 事件路由 。 這些路由可讓開發人員在整個系統內及下游服務連接事件流程。 單一路由可選取多個通知和事件種類。 繼續在 [建立路由和篩選 ] 中 建立事件路由至您的端點。