在 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。
若要在本地執行 CLI 參考命令，請安裝 Azure CLI。若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。如需詳細資訊，請參閱〈如何在 Docker 容器中執行 Azure CLI〉。
- 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。請遵循您終端機上顯示的步驟，完成驗證程序。如需其他登入選項，請參閱使用 Azure CLI 向 Azure 進行驗證。
- 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。如需擴充功能的詳細資訊，請參閱使用和管理 Azure CLI 的擴充功能。
- 執行 az version 以尋找已安裝的版本和相依程式庫。若要升級至最新版本，請執行 az upgrade。

建立所需的資源

這些服務是您可為執行個體建立的支援端點類型：

事件方格主題
- 針對事件方格端點，僅支援事件方格主題。不支援事件方格網域作為端點。
事件中樞中樞
服務匯流排主題

將端點連結至 Azure Digital Twins 之前，您必須建立您用於端點的事件方格主題、事件中樞或服務總線主題。

使用下列圖表來查看您應該設定哪些資源，再建立端點。

端點類型	必要資源 (連結至建立指示)
事件方格端點	事件方格主題（事件架構必須是事件方格架構或雲端事件架構 v1.0）
事件中樞端點	事件中樞命名空間事件中樞（選擇性）金鑰型驗證的授權規則
服務匯流排端點	服務匯流排命名空間服務匯流排主題（選擇性）金鑰型驗證的授權規則

建立端點

建立端點資源之後，您可以建立 Azure Digital Twins 端點。使用下列索引標籤來選取您慣用的體驗。

入口網站
命令列介面

若要建立新的端點，請移至 Azure 入口網站中的實例頁面。您可以在入口網站搜尋欄中輸入實例的名稱來尋找實例。

從實例功能表中，選擇 連接輸出 > 端點。然後從 [ 端點] 頁面，選取 [+ 建立端點]。此動作會開啟 [ 建立端點] 頁面。
輸入端點的 [名稱]，然後選擇 [端點類型]。
完成端點類型所需的其他詳細資料，包含您的訂用帳戶與稍早所述的端點資源。
1. 僅針對事件中樞和服務總線端點，選取 [驗證類型]。您可以使用金鑰型驗證搭配預先建立的授權規則，或系統指派或使用者指派的受控識別。只有在您已啟用執行個體的系統指派身分識別時，系統指派的身分識別才可供使用。如需使用身分識別驗證選項的詳細資訊，請參閱本文稍後的端點選項：身分識別型驗證。
選取 [儲存]，完成建立端點。

建立端點之後，您可以檢查頂端 Azure 入口網站列中的通知圖示，確認已成功建立端點：

通知的螢幕擷取畫面，以確認在 Azure 入口網站中建立端點。

如果端點建立失敗，觀察錯誤訊息，並於幾分鐘後重試。

您也可以檢視您在 Azure Digital Twins 實例的 [ 端點 ] 頁面上建立的端點。

現在，事件方格主題、事件中樞或服務匯流排主題可在您為端點選擇的名稱下，做為 Azure Digital Twins 中的端點使用。一般而言，您可以使用該名稱作為事件路由的目標，您可以在建立路由和篩選中建立該名稱。

下列範例會示範如何使用 Azure Digital Twins CLI 的az dt 端點建立命令，建立端點。以您自己的資源詳細資料取代命令中的預留位置。

若要建立事件方格端點：

az dt endpoint create eventgrid --endpoint-name <Event-Grid-endpoint-name> --eventgrid-resource-group <Event-Grid-resource-group-name> --eventgrid-topic <your-Event-Grid-topic-name> --dt-name <your-Azure-Digital-Twins-instance-name>

若要建立事件中樞端點 (金鑰型驗證)：

az dt endpoint create eventhub --endpoint-name <Event-Hub-endpoint-name> --eventhub-resource-group <Event-Hub-resource-group> --eventhub-namespace <Event-Hub-namespace> --eventhub <Event-Hub-name> --eventhub-policy <Event-Hub-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

若要建立服務匯流排主題端點 (金鑰型驗證)：

az dt endpoint create servicebus --endpoint-name <Service-Bus-endpoint-name> --servicebus-resource-group <Service-Bus-resource-group-name> --servicebus-namespace <Service-Bus-namespace> --servicebus-topic <Service-Bus-topic-name> --servicebus-policy <Service-Bus-topic-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

執行這些命令之後，事件方格主題、事件中樞或服務總線主題會以 Azure Digital Twins 中的端點的形式提供。端點具有您以--endpoint-name參數提供的名稱。一般而言，您可以使用該名稱作為事件路由的目標，您可以在建立路由和篩選中建立該名稱。

端點選項：身分識別型驗證

本節描述如何在將事件轉送至支援的路由目的地時，針對 Azure Digital Twins 執行個體使用受控識別。不需要設定受控識別即可進行路由，但其可協助執行個體輕鬆地存取其他受 Microsoft Entra 保護的資源，例如事件中樞、服務匯流排目的地和 Azure 儲存體容器。受控識別可以是系統指派或使用者指派。

本節的其餘部分會逐步介紹設定具受管理的身份的端點的三個步驟。

1.啟用執行個體的受控識別

使用下列索引標籤來取得符合您慣用體驗的指示。

入口網站
命令列介面

首先，請確定您為 Azure Digital Twins 實例啟用受控識別。

此外，確定您在執行個體上具有 Azure Digital Twins 資料擁有者角色。您可以在設定使用者存取權限中找到指示。

2.將 Azure 角色指派給身分識別

為 Azure Digital Twins 實例建立受控識別之後，請指派適當的角色，以使用不同類型的端點進行驗證，以將事件路由傳送至支援的目的地。本節描述角色選項，以及如何將其指派給受控識別。

重要

請務必完成此步驟。如果沒有它，身分識別就無法存取您的端點，也不會傳遞事件。

以下是您 Azure Digital Twins 身分識別存取端點所需的最低角色，取決於目的地類型。具有較高許可權的角色（例如數據擁有者角色）也能夠運作。

目的地	Azure 角色
Azure 事件中樞	Azure 事件中樞資料發送器
Azure 服務匯流排	Azure 服務匯流排資料傳送者
Azure 存儲容器	儲存體 Blob 資料參與者

使用下列索引標籤，以使用您慣用的體驗來指派角色。

入口網站
命令列介面

若要指派角色給身份識別，請使用瀏覽器開啟 Azure 入口網站。

瀏覽至端點資源 (事件中樞、服務匯流排主題或儲存體容器)，方法是在入口網站搜尋列中搜尋其名稱。
選取 [存取控制 (IAM)]。
選取 [新增 > 角色指派 ] 以開啟 [新增角色指派] 頁面。

將所需的角色指派給 Azure Digital Twins 執行個體的受控識別。如需詳細步驟，請參閱使用 Azure 入口網站指派 Azure 角色。

設定	價值
角色	從選項中選取所需的角色。
存取權指派對象	受控識別
成員	選取要獲指派角色 Azure Digital Twins 執行個體的系統指派受控識別。使用者指派的身分識別具有您在建立身分識別時選擇的名稱，而系統指派的身分識別具有符合 Azure Digital Twins 實例名稱的名稱。

您可以將 --scopes 參數新增至 az dt create 命令，以將身分識別指派給一或多個具有所指定角色的範圍。在首次建立實例時或之後提供現有實例名稱時，請使用此命令。

以下範例示範如何建立具有系統指派受控身份的實例，並將事件中樞中的自訂角色 MyCustomRole 指派給該身份。

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned --scopes "/subscriptions/<subscription ID>/resourceGroups/<resource-group>/providers/Microsoft.EventHub/namespaces/<Event-Hubs-namespace>/eventhubs/<event-hub-name>" --role MyCustomRole

如需使用此命令指派角色的其他範例，請參閱 az dt create 參考文件。

您也可以使用 az role assignment 命令群組來建立和管理角色。使用此命令來支援您不想使用 create 命令將角色指派分組的其他案例。

3.建立具有身分識別型驗證的端點

為 Azure Digital Twins 實例設定受控識別併為其指派適當的角色之後，請建立使用身分識別進行驗證的端點。此選項僅適用於事件中樞和服務匯流排類型端點 (並不支援事件方格)。

附註

您無法編輯以金鑰為基礎的身分識別所建立的端點，以變更為以身分識別為基礎的驗證。當您第一次建立端點時，必須選擇驗證類型。

使用下列區段，以使用您慣用的體驗來建立端點。

入口網站
命令列介面

開始遵循一般指示來建立 Azure Digital Twins 端點。

當您進入完成端點類型所需詳細資料的步驟時，請針對 [驗證類型] 選取 [系統指派] 或 [使用者指派 (預覽)]。

完成端點的設定，然後選取 [儲存]。

透過將參數新增至 az dt endpoint create 命令，以將受控識別新增至端點。如需此命令的詳細資訊，請參閱其參考檔或建立 Azure Digital Twins 端點的一般說明。

針對您選擇的受控識別類型，使用下列 CLI 命令。

系統指派的身分識別命令

若要建立使用系統指派驗證的端點，請使用 IdentityBased 參數指定 --auth-type 驗證類型。下列範例說明事件中樞端點的這項功能。

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --auth-type IdentityBased

使用者指派的身分識別命令

若要建立使用使用者指派身分識別驗證的端點，請使用 --user 參數指定使用者指派的身分識別資源識別碼。下列範例說明事件中樞端點的這項功能。

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --user <user-assigned-identity-resource-ID>

停用受控識別的考量

身分識別會與使用該身分識別的端點分開管理，因此請務必考慮身分識別或其角色的任何變更如何影響 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 帳戶中設定這些記憶體資源，請遵循下一節中的步驟。設定記憶體資源之後，您可以設定端點連線。

若要在 Azure 訂用帳戶中建立記憶體帳戶，請遵循建立記憶體帳戶中的步驟。記下記憶體帳戶名稱，以便稍後使用。
若要在新記憶體帳戶內建立容器，請遵循建立容器中的步驟。記下容器名稱，以便稍後使用。

建立 SAS 權杖

接下來，為您的儲存帳戶建立一個 SAS 權杖，以便端點可以使用來存取該帳戶。

入口網站
命令列介面

在 Azure 入口網站中瀏覽至您的記憶體帳戶（您可以使用入口網站搜尋列依名稱找到它）。
在記憶體帳戶頁面中，選擇左側導覽列中的 [安全性 + 網络 > 共用存取簽章 ] 連結，以開始設定 SAS 令牌。
在 [ 共用存取簽章] 頁面上，於 [ 允許的服務 ] 和 [ 允許的資源類型] 底下，選取您想要的設定。您必須在每個類別中至少選取一個方塊。在 [允許的許可權] 下，選擇 [ 寫入]。您也可以選取其他許可權。
設定其餘設定所需的值。
當您完成時，請選取 [產生 SAS 和連接字串 ] 以產生 SAS 令牌。
完成此程序會在相同頁面底部的設定選取範圍下，產生數個 SAS 和連接字串值。向下捲動以檢視值，並使用 [複製到剪貼簿] 圖示來複製 SAS 權杖值。將其儲存，以供稍後使用。

使用下列命令擷取儲存體帳戶金鑰，並複製其中一個金鑰的值：
```
az storage account keys list --account-name <storage-account-name>
```
選取到期日，並使用下列命令為您的儲存體帳戶產生 SAS 權杖：
```
az storage account generate-sas --account-name <storage-account-name> --account-key <storage-account-key> --expiry <expiration-date> --services bfqt --resource-types o --permissions w
```
此命令的輸出是 SAS 權杖。複製 SAS 權杖值，以供稍後使用。

附註

上一個命令中的參數範例集合包括 "blob"、"file"、"queue" 和 "table" 服務 (--services bfqt)、"object" 資源類型 (--resource-types o) 和 "write" 許可權 (--permissions w)。

如需有關 az storage account generate-sas 命令及其參數的詳細資訊，請參閱 Azure CLI 參考。

若要建立已啟用無效信件的端點，請使用 CLI 命令或控制平面 API 來建立您的端點。您無法在 Azure 入口網站中建立這種類型的端點。

如需如何使用 Azure CLI 建立此端點類型的指示，請切換至本節的 CLI 索引標籤。

若要建立已啟用無效信件的端點，請將 --deadletter-sas-uri 參數新增至 az dt 端點建立命令，以建立端點。

參數的值是您在上一節中收集的儲存體帳戶名稱、容器名稱和 SAS 權杖所組成的無效信件 SAS URI。此參數會建立具有金鑰型驗證的端點。以下是參數的外觀：

--deadletter-sas-uri https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>

秘訣

若要建立具有身分識別型驗證的無效信件端點，請將本節中的無效信件處理參數和適當的受控識別參數新增至相同的命令。

您也可以使用 Azure Digital Twins 控制平面 API 來建立死無效信件端點，而非 CLI。若要這樣做，請檢視 DigitalTwinsEndpoint 文件，以了解如何建構要求並新增無效信件參數。

訊息儲存體結構描述

當您設定無效信件的端點後，無效信件的訊息會以下列格式儲存在您的儲存體帳戶中：

<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"
}

下一步

建立端點之後，請定義事件路由以將數據傳送至端點。事件路由可讓您設定整個系統和下游服務的事件流程。單一路由可以允許多個通知和事件類型。請依照「建立路由」和「篩選」中的指示，建立一條事件路由到你的端點。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-06-20