You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/digital-twins/how-to-set-up-instance-cli.md
+17-17Lines changed: 17 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ titleSuffix: Azure Digital Twins
4
4
description: See how to set up an instance of the Azure Digital Twins service using the CLI
5
5
author: baanders
6
6
ms.author: baanders
7
-
ms.date: 11/17/2022
7
+
ms.date: 4/21/2025
8
8
ms.topic: how-to
9
9
ms.service: azure-digital-twins
10
10
ms.custom: engagement-fy23, devx-track-azurecli
@@ -29,28 +29,28 @@ This article covers the steps to set up a new Azure Digital Twins instance, incl
29
29
30
30
## Create the Azure Digital Twins instance
31
31
32
-
In this section, you will create a new instance of Azure Digital Twins using the CLI command. You will need to provide:
33
-
* A resource group where the instance will be deployed. If you do not already have an existing resource group in mind, you can create one now with this command:
32
+
In this section, you create a new instance of Azure Digital Twins using the CLI command. You need to provide:
33
+
* A resource group where the instance is deployed. If you don't already have an existing resource group in mind, you can create one now with this command:
34
34
```azurecli-interactive
35
35
az group create --location <region> --name <name-for-your-resource-group>
36
36
```
37
37
* A region for the deployment. To see what regions support Azure Digital Twins, visit [Azure products available by region](https://azure.microsoft.com/global-infrastructure/services/?products=digital-twins).
38
38
* A name for your instance. If your subscription has another Azure Digital Twins instance in the region that is
39
-
already using the specified name, you'll be asked to pick a different name.
39
+
already using the specified name, you're asked to pick a different name.
40
40
41
41
Use these values in the following [az dt command](/cli/azure/dt) to create the instance:
42
42
43
43
```azurecli-interactive
44
44
az dt create --dt-name <name-for-your-Azure-Digital-Twins-instance> --resource-group <your-resource-group> --location <region>
45
45
```
46
46
47
-
There are several optional parameters that can be added to the command to specify additional things about your resource during creation, including creating a managed identity for the instance or enabling/disabling public network access. For a full list of supported parameters, see the [az dt create](/cli/azure/dt#az-dt-create) reference documentation.
47
+
There are several optional parameters that can be added to the command to specify other things about your resource during creation, including creating a managed identity for the instance or enabling/disabling public network access. For a full list of supported parameters, see the [az dt create](/cli/azure/dt#az-dt-create) reference documentation.
48
48
49
49
### Create the instance with a managed identity
50
50
51
51
When you enable a [managed identity](concepts-security.md#managed-identity-for-accessing-other-resources) on your Azure Digital Twins instance, an identity is created for it in [Microsoft Entra ID](../active-directory/fundamentals/active-directory-whatis.md). That identity can then be used to authenticate to other services. You can enable a managed identity for an Azure Digital Twins instance while the instance is being created, or [later on an existing instance](#enabledisable-managed-identity-for-the-instance).
52
52
53
-
Use the CLI command below for your chosen type of managed identity.
53
+
Use the following CLI command for your chosen type of managed identity.
If the instance was created successfully, the result in the CLI looks something like this, outputting information about the resource you have created:
75
+
If the instance was created successfully, the result in the CLI looks something like this, outputting information about the resource you created:
76
76
77
77
:::image type="content" source="media/how-to-set-up-instance/cloud-shell/create-instance.png" alt-text="Screenshot of the Cloud Shell window with successful creation of a resource group and Azure Digital Twins instance in the Azure portal." lightbox="media/how-to-set-up-instance/cloud-shell/create-instance.png":::
78
78
79
-
Note the Azure Digital Twins instance's **hostName**, **name**, and **resourceGroup** from the output. These values are all important and you may need to use them as you continue working with your Azure Digital Twins instance, to set up authentication and related Azure resources. If other users will be programming against the instance, you should share these values with them.
79
+
Note the Azure Digital Twins instance's **hostName**, **name**, and **resourceGroup** from the output. These values are all important and you might need to use them as you continue working with your Azure Digital Twins instance, to set up authentication and related Azure resources. If other users are programming against the instance, you should share these values with them.
80
80
81
81
> [!TIP]
82
82
> You can see these properties, along with all the properties of your instance, at any time by running `az dt show --dt-name <your-Azure-Digital-Twins-instance>`.
83
83
84
-
You now have an Azure Digital Twins instance ready to go. Next, you will give the appropriate Azure user permissions to manage it.
84
+
You now have an Azure Digital Twins instance ready to go. Next, you give the appropriate Azure user permissions to manage it.
85
85
86
86
## Set up user access permissions
87
87
@@ -95,13 +95,13 @@ You now have an Azure Digital Twins instance ready to go. Next, you will give th
95
95
96
96
To give a user permission to manage an Azure Digital Twins instance, you must assign them the **Azure Digital Twins Data Owner** role within the instance.
97
97
98
-
Use the following command to assign the role (must be run by a user with [sufficient permissions](#prerequisites-permission-requirements) in the Azure subscription). The command requires you to pass in the *user principal name* on the Microsoft Entra account for the user that should be assigned the role. In most cases, this value will match the user's email on the Microsoft Entra account.
98
+
Use the following command to assign the role. A user with [sufficient permissions](#prerequisites-permission-requirements) in the Azure subscription must run the command. The command requires you to pass in the *user principal name* on the Microsoft Entra account for the user that should be assigned the role. In most cases, this value matches the user's email on the Microsoft Entra account.
99
99
100
100
```azurecli-interactive
101
101
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"
102
102
```
103
103
104
-
The result of this command is outputted information about the role assignment that has been created for the user.
104
+
The result of this command is outputted information about the role assignment that was created for the user.
105
105
106
106
> [!NOTE]
107
107
> If this command returns an error saying that the CLI **cannot find user or service principal in graph database**, assign the role using the user's Object ID instead. This may happen for users on personal [Microsoft accounts (MSAs)](https://account.microsoft.com/account).
@@ -110,19 +110,19 @@ The result of this command is outputted information about the role assignment th
110
110
>
111
111
> :::image type="content" source="media/includes/user-id.png" alt-text="Screenshot of the user page in Azure portal highlighting the GUID in the 'Object ID' field." lightbox="media/includes/user-id-large.png":::
112
112
>
113
-
> Then, repeat the role assignment list command using the user's Object ID for the `assignee` parameter above.
113
+
> Then, repeat the role assignment list command using the user's Object ID for the `assignee` parameter in the previous command.
You now have an Azure Digital Twins instance ready to go, and have assigned permissions to manage it.
119
+
You now have an Azure Digital Twins instance ready to go, and assigned permissions to manage it.
120
120
121
121
## Enable/disable managed identity for the instance
122
122
123
123
This section shows you how to add a managed identity to an Azure Digital Twins instance that already exists. You can also disable managed identity on an instance that has it already.
124
124
125
-
Use the CLI commands below for your chosen type of managed identity.
125
+
Use the following CLI commands for your chosen type of managed identity.
### Considerations for disabling managed identities
156
156
157
-
It's important to consider the effects that any changes to the identity or its roles can have on the resources that use it. If you're [using managed identities with your Azure Digital Twins endpoints](how-to-create-endpoints.md#endpoint-options-identity-based-authentication) or for [data history](concepts-data-history.md) and the identity is disabled, or a necessary role is removed from it, the endpoint or data history connection can become inaccessible and the flow of events will be disrupted.
157
+
It's important to consider the effects that any changes to the identity or its roles can have on the resources that use it. If you're [using managed identities with your Azure Digital Twins endpoints](how-to-create-endpoints.md#endpoint-options-identity-based-authentication) or for [data history](concepts-data-history.md) and the identity is disabled, or a necessary role is removed from it, the endpoint or data history connection can become inaccessible and the flow of events is disrupted.
158
158
159
-
To continue using an endpoint that was set up with a managed identity that's now been disabled, you'll need to delete the endpoint and [re-create it](how-to-create-endpoints.md) with a different authentication type. It may take up to an hour for events to resume delivery to the endpoint after this change.
159
+
To continue using an endpoint that was set up with a managed identity that's now been disabled, you need to delete the endpoint and [re-create it](how-to-create-endpoints.md) with a different authentication type. It might take up to an hour for events to resume delivery to the endpoint after this change.
160
160
161
161
## Next steps
162
162
@@ -165,4 +165,4 @@ Test out individual REST API calls on your instance using the Azure Digital Twin
165
165
*[Azure Digital Twins CLI command set](concepts-cli.md)
166
166
167
167
Or, see how to connect a client application to your instance with authentication code:
For Azure Digital Twins, this role is **Azure Digital Twins Data Owner**. You can read more about roles and security in [Security for Azure Digital Twins solutions](../concepts-security.md).
13
13
14
14
> [!NOTE]
15
-
> This role is different from the Microsoft Entra ID **Owner** role, which can also be assigned at the scope of the Azure Digital Twins instance. These are two distinct management roles, and Owner does not grant access to data plane features that are granted with **Azure Digital Twins Data Owner**.
15
+
> This role is different from the Microsoft Entra ID **Owner** role, which can also be assigned at the scope of the Azure Digital Twins instance. These are two distinct management roles, and **Owner** doesn't grant access to data plane features that are granted with **Azure Digital Twins Data Owner**.
16
16
17
-
This section will show you how to create a role assignment for a user in your Azure Digital Twins instance, using that user's email in the Microsoft Entra tenant on your Azure subscription. Depending on your role in your organization, you might set up this permission for yourself, or set it up on behalf of someone else who will be managing the Azure Digital Twins instance.
17
+
This section shows you how to create a role assignment for a user in your Azure Digital Twins instance, using that user's email in the Microsoft Entra tenant on your Azure subscription. Depending on your role in your organization, you might set up this permission for yourself, or set it up on behalf of someone else who manages the Azure Digital Twins instance.
description: include file for steps overview in Azure Digital Twins setup
3
+
description: Include file for steps overview in Azure Digital Twins setup
4
4
ms.service: azure-digital-twins
5
5
ms.topic: include
6
-
ms.date: 10/14/2020
6
+
ms.date: 4/21/2025
7
7
ms.author: baanders
8
8
---
9
9
10
10
Full setup for a new Azure Digital Twins instance consists of two parts:
11
-
1. Creating the instance
12
-
2. Setting up user access permissions: Azure users need to have the **Azure Digital Twins Data Owner** role on the Azure Digital Twins instance to be able to manage it and its data. In this step, you as an Owner/administrator of the Azure subscription will assign this role to the person who will be managing your Azure Digital Twins instance. This may be yourself or someone else in your organization.
11
+
1. Creating the instance.
12
+
2. Setting up user access permissions: Azure users need to have the **Azure Digital Twins Data Owner** role on the Azure Digital Twins instance to be able to manage it and its data. In this step, you as an Owner/administrator of the Azure subscription assigns this role to the person who manages your Azure Digital Twins instance. This person might be yourself or someone else in your organization.
13
13
14
14
>[!IMPORTANT]
15
-
>To complete this full article and completely set up a usable instance, you need permissions to manage both resources and user access on the Azure subscription. The first step can be completed by anyone who's able to create resources on the subscription, but the second step requires user access management permissions (or the cooperation of someone with these permissions). You can read more about this in the [Prerequisites: Required permissions](#prerequisites-permission-requirements) section for the user access permission step.
15
+
>To complete this full article and set up a usable instance, you need permissions to manage both resources and user access on the Azure subscription. Anyone who's able to create resources on the subscription can complete the first step, but the second step requires user access management permissions (or the cooperation of someone with these permissions). You can read more about the required permissions in the [Prerequisites: Required permissions](#prerequisites-permission-requirements) section for the user access permission step.
0 commit comments