共用方式為

設定 Azure Digital Twins 執行個體和驗證 (CLI)

本文涵蓋設定新 Azure Digital Twins 執行個體的步驟，包括建立執行個體和設定驗證。 完成本文之後，您將得到一個能讓您進行程式設計的 Azure Digital Twins 執行個體。

新 Azure Digital Twins 執行個體的完整設定包含兩個部分：

  1. 建立實例。
  2. 設定使用者訪問許可權：Azure 用戶必須在 Azure Digital Twins 實例上擁有 Azure Digital Twins 數據擁有者 角色，才能管理它及其數據。 在此步驟中，身為 Azure 訂用帳戶的擁有者/系統管理員，會將此角色指派給管理 Azure Digital Twins 實例的人員。 此人可能是您自己或組織中的其他人。

重要

若要完成此完整文章並設定可使用的實例，您需要在 Azure 訂用帳戶上管理資源和使用者存取權的許可權。 任何能夠在訂用帳戶上建立資源的人都可以完成第一個步驟，但第二個步驟需要使用者存取管理許可權（或擁有這些許可權的人員合作）。 您可以在使用者存取權限步驟的 先決條件：必要許可權 一節中深入瞭解所需的權限。

必要條件

設定 CLI 工作階段

若要開始在 CLI 中使用 Azure Digital Twins，您要做的第一件事就是登入，並針對此工作階段設定訂閱的 CLI 內容。 在您的 CLI 視窗中執行下列命令：

az login
az account set --subscription "<your-Azure-subscription-ID>"

提示

您也可以在上一個命令中使用訂用帳戶名稱，而不是標識符。

如果您是第一次搭配 Azure Digital Twins 使用此訂用帳戶，請執行下列命令向 Azure Digital Twins 命名空間註冊。 （如果你不確定，沒關係，即使你過去曾經執行過它，也可以再次執行。）

az provider register --namespace 'Microsoft.DigitalTwins'

接下來，您會新增 適用於 Azure CLI 的 Azure IoT 擴充功能Microsoft，以啟用與 Azure Digital Twins 和其他 IoT 服務互動的命令。 執行此命令以確定您擁有最新版本的延伸模組：

az extension add --upgrade --name azure-iot

現在您已準備好在 Azure CLI 中使用 Azure Digital Twins。

您可以隨時執行 az dt --help 來確認此狀態，以查看可用的最上層 Azure Digital Twins 命令清單。

建立 Azure Digital Twins 執行個體

在本節中，您會使用 CLI 命令建立 Azure Digital Twins 的新實例。 您需要提供：

  • 部署實例的資源群組。 如果您還沒有現有的資源群組，您可以使用下列命令立即建立一個資源群組： 
    az group create --location <region> --name <name-for-your-resource-group>
  • 部署區域。 若要查看哪些區域支援 Azure Digital Twins，請流覽 依區域提供的 Azure 產品。
  • 執行個體的名稱。 如果您的訂用帳戶在已經使用指定名稱的區域中有另一個 Azure Digital Twins 實例，系統會要求您挑選不同的名稱。

使用下列 az dt 命令 中的這些值來建立 實體：

az dt create --dt-name <name-for-your-Azure-Digital-Twins-instance> --resource-group <your-resource-group> --location <region>

有數個選擇性參數可以新增至 命令，以在建立期間指定資源的其他事項，包括建立實例的受控識別，或啟用/停用公用網路存取。 如需支持參數的完整清單，請參閱 az dt create 參考檔。

使用受控識別來建立執行個體

當您在 Azure Digital Twins 實例上啟用 託管身分 時，會在 Microsoft Entra ID 中為其建立身分識別。 然後，該身分識別可用來向其他服務進行驗證。 您可以在建立實例時，或 稍後在現有實例上啟用 Azure Digital Twins 實例的受控識別。

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

系統指派的身分識別命令

若要建立啟用「系統指派的身分識別」的 Azure Digital Twins 執行個體，您可以在用來建立執行個體的 --mi-system-assigned 命令中加入 az dt create 參數。 （如需建立命令的詳細資訊，請參閱其 參考文件 或 設定 Azure Digital Twins 實例的一般指示。

若要建立具有系統指派的身分識別的執行個體，請加入 --mi-system-assigned 參數，如下所示：

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned

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

若要建立具有「使用者指派的身分識別」的執行個體，請使用 --mi-user-assigned 參數提供現有使用者指派之身分識別的識別碼，如下所示：

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-user-assigned <user-assigned-identity-resource-ID>

確認是否成功並收集重要的值

如果成功建立實例，CLI 的結果看起來會像這樣，並輸出您所建立資源的相關信息：

Cloud Shell 視窗的螢幕快照，其中已成功在 Azure 入口網站中建立資源群組和 Azure Digital Twins 實例。

請注意來自輸出的 Azure Digital Twins 實例的 主機名、名稱 和 資源群組。 這些值都很重要，而且您可能需要在繼續使用 Azure Digital Twins 實例時使用這些值，以設定驗證和相關 Azure 資源。 如果其他使用者正在針對 實例進行程序設計，您應該與他們共用這些值。

提示

您可以隨時執行 az dt show --dt-name <your-Azure-Digital-Twins-instance> 來查看這些屬性和執行個體的所有屬性。

您現在已備妥 Azure Digital Twins 執行個體。 接下來，您會提供適當的 Azure 使用者許可權來管理它。

設定使用者存取權限

Azure Digital Twins 會針對角色型訪問控制 （RBAC） 使用 Microsoft Entra ID 。 這表示使用者必須先具備適當權限的角色指派，才能對 Azure Digital Twins 執行個體進行資料平面呼叫。

針對 Azure Digital Twins，此角色為 Azure Digital Twins 數據擁有者。 您可以在 Azure Digital Twins 解決方案的安全性中深入瞭解角色和安全性。

注意

此角色與 Microsoft Entra ID 擁有者 角色不同，也可以在 Azure Digital Twins 實例的範圍指派。 這是兩個不同的管理角色，擁有者角色 不會提供資料平面功能的存取權，而這是由 Azure Digital Twins 資料擁有者授與的。

本節說明如何在 Azure Digital Twins 實例中為使用者建立角色指派，並在 Azure 訂用帳戶上的 Microsoft Entra 租使用者中使用該使用者的電子郵件。 視您組織中的角色而定，您可以自行設定此許可權，或代表管理 Azure Digital Twins 實例的其他人進行設定。

必要條件：權限要求

要能夠完成下列步驟，您必須在訂用帳戶中具有包含下列許可權的角色：

  • 建立和管理 Azure 資源
  • 管理使用者的 Azure 資源存取權 (包含授與和委派權限)

符合此需求的常見角色包括 擁有者、 帳戶管理員或 使用者存取管理員 和 參與者的組合。 如需關於角色和許可權（包括其他角色所包含的權限）的完整說明，請造訪 Azure RBAC 文件中的 Azure 角色、Microsoft Entra 角色，以及經典訂閱系統管理員角色。

若要在訂用帳戶中檢視您的角色，請流覽 Azure 入口網站中的 [訂用帳戶] 頁面 （您可以使用此連結，或使用入口網站搜尋列尋找 訂 用帳戶）。 尋找您使用的訂用帳戶名稱，並在 [ 我的角色 ] 資料行中檢視您的角色：

Azure 入口網站中 [訂用帳戶] 頁面的螢幕快照，其中顯示用戶為擁有者。

如果您發現此值為 參與者，或先前未具有必要許可權的另一個角色，您可以連絡訂用帳戶上具有這些許可權的使用者（例如訂用帳戶擁有者或帳戶管理員），然後以下列其中一種方式繼續進行：

  • 要求他們代表您完成角色指派的步驟。
  • 要求他們在訂用帳戶上提升您的角色，以便您有繼續自己的許可權。 此要求是否適當，取決於您的組織及其內的角色。

指派角色

若要授與使用者管理 Azure Digital Twins 實例的許可權，您必須在實例內指派 Azure Digital Twins 數據擁有者 角色。

使用下列命令來指派角色。 Azure 訂用帳戶中 具有足夠許可權 的用戶必須執行 命令。 此命令會要求在 Microsoft Entra 帳戶上傳入應獲指派角色之使用者的「使用者主體名稱」。 在大部分情況下，此值會比對 Microsoft Entra 帳戶上的用戶電子郵件。

az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<Azure-AD-user-principal-name-of-user-to-assign>" --role "Azure Digital Twins Data Owner"

此命令的結果會輸出使用者所建立角色指派的相關信息。

注意

如果此命令傳回錯誤，指出 CLI 在圖形資料庫中找不到使用者或服務主體，請改用使用者的物件識別碼來指派角色。 個人 Microsoft帳戶 （MSA） 上的使用者可能會發生這種情況。

使用 Microsoft Entra 使用者的 Azure 入口網站頁面 來選取使用者帳戶，並開啟其詳細數據。 複製使用者 的物件識別碼：

Azure 入口網站中用戶頁面的螢幕快照，其中醒目提示 [對象識別符] 欄位中的 GUID。

然後，使用上一個命令中 參數的用戶物件識別碼 assignee ，重複角色指派清單命令。

確認是否成功

檢查您是否已成功設定角色指派的其中一種方式，是在 Azure 入口網站中檢視 Azure Digital Twins 實例的角色指派。

在 Azure 入口網站中，移至 Azure 數位對應項執行個體。 若要到達該處，您可以在 Azure Digital Twins 實例 的頁面上查閱它，或在入口網站搜尋列中搜尋其名稱。

然後，在 [存取控制] (IAM) > [角色指派] 下檢視其所有指派的角色。 您的角色指派應該會出現在清單中。

Azure 入口網站中 Azure Digital Twins 實例的角色指派截圖。

您現在已備妥 Azure Digital Twins 實例，並獲指派許可權來管理它。

啟用/停用執行個體的受控識別

本節說明如何將受控識別新增至已經存在的 Azure Digital Twins 執行個體。 您也可以在已有受控識別的執行個體上停用受控識別。

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

系統指派的身分識別命令

為現有實例啟用系統指派身分識別的命令，是用來az dt create的相同命令。 您可以提供現有執行個體的名稱，而不用提供新的執行個體名稱。 接下來，請務必要新增 --mi-system-assigned 參數。

az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned

若要在目前啟用的執行個體上停用系統指派的身分識別，請使用下列命令將 --mi-system-assigned 設為 false。

az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned false

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

若要在現有執行個體上啟用「使用者指派的」身分識別，請在下列命令中提供現有使用者指派之身分識別的識別碼：

az dt identity assign --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>

若要在目前啟用的執行個體上停用使用者指派的身分識別，請在下列命令中提供身分識別的識別碼：

az dt identity remove --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>

停用受控識別的考量

請務必要考量針對身分識別或其角色的變更，對於使用該身分識別的資源會造成什麼影響。 如果您使用 受控識別搭配 Azure Digital Twins 端點 或 數據歷程記錄 ，且身分識別已停用，或從中移除必要的角色，端點或數據歷程記錄連線可能會變得無法存取，且事件流程中斷。

若要繼續使用已停用的受控識別所設定的端點，您必須刪除端點，並以不同的驗證類型 重新建立端點 。 在這項變更之後，事件可能需要一小時的時間才能繼續傳遞至端點。

下一步

使用 Azure Digital Twins CLI 命令在執行個體上測試個別 REST API 呼叫：

或者，請參閱如何利用驗證碼將用戶端應用程式連線到您的執行個體：

  • Last updated on