設定 Azure Digital Twins 執行個體和驗證 (CLI)
本文涵蓋設定新 Azure Digital Twins 執行個體的步驟，包括建立執行個體和設定驗證。 完成本文之後，您將得到一個能讓您進行程式設計的 Azure Digital Twins 執行個體。
新 Azure Digital Twins 執行個體的完整設定包含兩個部分：
- 建立執行個體
- 設定使用者存取權限：Azure 使用者必須具備 Azure Digital Twins 執行個體的 Azure Digital Twins 資料擁有者角色，才能該執行個體及其資料。 在此步驟中，您作為 Azure 訂閱的擁有者/系統管理員，會將此角色指派給要管理 Azure Digital Twins 執行個體的人員。 這可能是您自己或您組織中的其他人員。
重要
若要完成此文章並完整安裝可用的執行個體，您需要管理 Azure 訂閱上的資源和使用者存取權的權限。 第一個步驟可由任何能在訂閱上建立資源的人員完成，但第二個步驟需要使用者存取權的管理權限 (或與擁有這些權限的人員合作)。 如需詳細資訊，請參閱使用者存取權限步驟的「必要條件：必要權限」一節。
必要條件
在 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。
設定 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 的 Microsoft Azure IoT 擴充功能以啟用可與 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 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 執行個體，您可以在用來建立執行個體的 az dt create 命令中加入 --mi-system-assigned 參數。 (如需建立命令的詳細資訊，請參閱其參考文件或用於設定 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 會輸出您所建立之資源的相關資訊，如下：
記下輸出中的 Azure Digital Twins 執行個體的主機名稱、名稱和 resourceGroup。 這些值非常重要，而且您接下來繼續使用 Azure Digital Twins 執行個體時，也可能需要用這些值來設定驗證和相關 Azure 資源。 如果其他使用者要對此執行個體進行程式設計，您應該與他們分享這些值。
提示
您可以隨時執行 az dt show --dt-name <your-Azure-Digital-Twins-instance> 來查看這些屬性和執行個體的所有屬性。
您現在已備妥 Azure Digital Twins 執行個體。 接下來，您會將管理權限授予適當的 Azure 使用者。
設定使用者存取權限
Azure Digital Twins 使用 Microsoft Entra ID 作為角色型存取控制 (RBAC)。 這表示使用者必須先具備適當權限的角色指派，才能對 Azure Digital Twins 執行個體進行資料平面呼叫。
對 Azure Digital Twins 而言，這個角色為 Azure Digital Twins 資料擁有者。 如需角色和安全性的詳細資訊，請參閱 Azure Digital Twins 解決方案的安全性。
注意
此角色不同於 Microsoft Entra ID 的「擁有者」角色 (也可在 Azure Digital Twins 執行個體範圍內指派)。 這兩個管理角色有所不同，因為擁有者沒有資料平面功能的存取權，而 Azure Digital Twins 資料擁有者則具備該存取權。
本節將說明如何在 Azure 訂用帳戶的 Microsoft Entra 租用戶中使用某個使用者的電子郵件，在您的 Azure Digital Twins 執行個體中為該使用者建立角色指派。 根據您在您組織中的角色，您可以為自己設定此權限，或代表其他將要管理 Azure Digital Twins 執行個體的人員來進行設定。
必要條件：權限要求
若要完成下列步驟，您的訂閱中必須有具備以下權限的角色：
- 建立和管理 Azure 資源
- 管理使用者的 Azure 資源存取權 (包含授與和委派權限)
符合此需求的常見角色包括：擁有者、帳戶管理員，或使用者存取管理員與參與者的組合。 如需角色和權限的完整說明，包括其他角色所擁有的權限，請見 Azure RBAC 文件中的Azure 角色、Microsoft Entra 角色和傳統訂用帳戶管理員角色。
若要在訂閱中檢視您的角色，請至 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 入口網站頁面來選取使用者帳戶並開啟其詳細資料。 複製使用者的物件識別碼：
然後，使用上述參數 assignee 的使用者物件識別碼再重複一次角色指派清單命令。
確認是否成功
檢查您是否已成功設定角色指派的其中一種方式，就是在 Azure 入口網站中檢視 Azure Digital Twins 執行個體的角色指派。 在 Azure 入口網站中，移至 Azure 數位對應項執行個體。 若要前往該處，您可以在 Azure Digital Twins 執行個體的頁面上查閱，或在入口網站搜尋列中搜尋其名稱。
然後，在 [存取控制] (IAM) > [角色指派] 下檢視其所有指派的角色。 您的角色指派應該會出現在清單中。
您現在已經備妥 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 呼叫：
或者，請參閱如何利用驗證碼將用戶端應用程式連線到您的執行個體：