+The following example configures a **PhoneNumber** claim with the `Simple` mask. For more samples, check out the [Claim simple mask live demo](https://github.com/azure-ad-b2c/unit-tests/tree/main/claims#simple-mask).

+The following example configures a **AlternateEmail** claim with the `Regex` mask. For more samples, check out the [Regex mask live demo](https://github.com/azure-ad-b2c/unit-tests/tree/main/claims#regex-mask).

+The following example configures a **city** dropdown list claim with a default value set to `New York`. For more samples, check out the [Claim restriction enumeration live demo](https://github.com/azure-ad-b2c/unit-tests/tree/main/claims#restriction-enumeration).

+The following example shows the use of the **LocalizedCollections** element. It contains two **LocalizedCollection** elements, one for English and another one for Spanish. Both set the **Restriction** collection of the claim `Gender` with a list of items for English and Spanish. For more samples, check out the [Claim restriction enumeration live demo](https://github.com/azure-ad-b2c/unit-tests/tree/main/claims#restriction-enumeration).

+ <LocalizedCollections>

+ <LocalizedCollection ElementType="ClaimType" ElementId="Gender" TargetCollection="Restriction">

+ </LocalizedCollections>

+</LocalizedResources>

+ </LocalizedCollections>

+</LocalizedResources>

+> [!WARNING]

+> Data of users included in multi-stage access reviews are a part of the audit record at the start of the review. Administrators may delete the data at any time by deleting the multi-stage access review series.

+| 1.23 | Dec 2021 | Jan 2022 | Apr 2022 | 1.26 GA |

+> [!NOTE]

+> The free certificate is issued by DigiCert. For some domains, you must explicitly allow DigiCert as a certificate issuer by creating a [CAA domain record](https://wikipedia.org/wiki/DNS_Certification_Authority_Authorization) with the value: `0 issue digicert.com`.

+- The user-assigned managed identity and the target Azure resources that your runbook manages using that identity can be in different Azure subscriptions.

+// For Pay-As-You-Go (per-GB) and commitment tier pricing details, see https://azure.microsoft.com/pricing/details/monitor/.

+let PerNodePrice = 15.; // Montly price per monitored node

+let PerNodeOveragePrice = 2.30; // Price per GB for data overage in the Per Node pricing tier

+let PerGBPrice = 2.30; // Enter the Pay-as-you-go price for your workspace's region (from https://azure.microsoft.com/pricing/details/monitor/)

+GET https://management.azure.com/subscriptions/00000000-0000-0000-0000-00000000000/resourcegroups/testRG/providers/Microsoft.OperationalInsights/workspaces/testWS/tables/Syslog_SRCH?api-version=2021-12-01-preview

+Use the drop-down list to select from the list of available languages. This setting controls the language you see for text throughout the Azure portal. Azure portal supports the following 18 languages in addition to English: Chinese (Simplified), Chinese (Traditional), Czech, Dutch, French, German, Hungarian, Indonesian, Italian, Japanese, Korean, Polish, Portuguese (Brazil), Portuguese (Portugal), Russian, Spanish, Swedish, and Turkish.

+This article helps you configure your Bastion deployment, and then connect to a VM in the VNet using a native client (SSH or RDP) on your local computer. The native client feature lets you connect to your target VMs via Bastion using Azure CLI, and expands your sign-in options to include local SSH key pair and Azure Active Directory (Azure AD). Additionally with this feature, you can now also upload or download files, depending on the connection type and client.

+This section helps you connect to your virtual machine from the native client on a local Windows computer. If you want to upload and download files after connecting, you must use an RDP connection. For more information about file transfers, see [Upload or download files](vm-upload-download-native.md).

+[Upload or download files](vm-upload-download-native.md)

+ Title: 'Upload or download files - native client'

+description: Learn how to upload or download files using Azure Bastion and a native client.

+# Upload or download files using the native client (Preview)

+# Number types

+## Available options

+- **To send or receive an SMS**, choose a Toll-Free Number or a Short Code

+- **To make or receive phone calls**, choose a Toll-Free Number or a Local Number

+| Type | Example | Send SMS | Receive SMS | Make Calls | Receive Calls | Typical Use Case | Restrictions |

+| :-- | :- | :: | :: | :--: | :--: | :- | :- |

+| [Toll-Free](../../quickstarts/telephony/get-phone-number.md) | +1 (8AB) XYZ PQRS | Yes | Yes | Yes | Yes | Receive calls on IVR bots, SMS Notifications | SMS in US only |

+| [Local (Geographic)](../../quickstarts/telephony/get-phone-number.md) | +1 (ABC) XYZ PQRS | No | No | Yes | Yes | Geography Specific Number | Calling Only |

+| [Short-Codes](../../quickstarts/sms/apply-for-short-code.md) | ABC-XYZ | Yes | Yes | No | No | High-velocity SMS | SMS only |

+## Next steps

+For additional information about getting or managing phone numbers please see the following pages:

+# Subscription eligibility and number capabilities

+## Subscription eligibility

+| Number Type | Eligible Azure Agreement Type |

+| :- | :- |

+| Toll-Free and Local (Geographic) | Modern Customer Agreement (Field and Customer Led), Modern Partner Agreement (CSP), Enterprise Agreement |

+| Short-Codes | Modern Customer Agreement (Field Led) and Enterprise Agreement Only |

+## Number capabilities

+## Customers with US Azure billing addresses

+| Number | Type | Send SMS | Receive SMS | Make Calls | Receive Calls |

+| :- | :- | :- | :- | :- | : |

+| USA & Puerto Rico | Toll-Free | General Availability | General Availability | General Availability | General Availability\* |

+| USA & Puerto Rico | Local | Not Available | Not Available | General Availability | General Availability\* |

+| USA | Short-Codes | Public Preview | Public Preview\* | Not Available | Not Available |

+\* Available through Azure Bot Framework and Dynamics only

+## Customers with UK Azure billing addresses

+| Number | Type | Send SMS | Receive SMS | Make Calls | Receive Calls |

+| :- | :-- | :- | :- | :- | : |

+| UK | Toll-Free | Not Available | Not Available | Public Preview | Public Preview\* |

+| UK | Local | Not Available | Not Available | Public Preview | Public Preview\* |

+| USA & Puerto Rico | Toll-Free | General Availability | General Availability | Public Preview | Public Preview\* |

+| USA & Puerto Rico | Local | Not Available | Not Available | Public Preview | Public Preview\* |

+\* Available through Azure Bot Framework and Dynamics only

+## Customers with Ireland Azure billing addresses

+| Number | Type | Send SMS | Receive SMS | Make Calls | Receive Calls |

+| :- | :-- | :- | :- | :- | : |

+| USA & Puerto Rico | Toll-Free | General Availability | General Availability | General Availability | General Availability\* |

+| USA & Puerto Rico | Local | Not Available | Not Available | General Availability | General Availability\* |

+\* Available through Azure Bot Framework and Dynamics only

+| Number | Type | Send SMS | Receive SMS | Make Calls | Receive Calls |

+| : | :-- | : | : | :- | : |

+| Denmark | Toll-Free | Not Available | Not Available | Public Preview | Public Preview\* |

+| Denmark | Local | Not Available | Not Available | Public Preview | Public Preview\* |

+## Next steps

+For additional information about ACS' telephony options please see the following pages:

+| [columnNames](data-flow-expressions-usage.md#columnNames) | Gets the names of all output columns for a stream. You can pass an optional stream name as the first argument and optional second argument to only return schema drift columns. |

+- [Learn how to use Expression Builder](concepts-data-flow-expression-builder.md).

+<code><b>columnNames(<i>&lt;value1&gt;</i> : string, i>&lt;value1&gt;</i> : boolean) => array</b></code><br/><br/>

+Gets the names of all output columns for a stream. You can pass an optional stream name as the first argument. The second argument is also optional, with false as the default. If you set the second argument to ``true()``, ADF will return only columns that are drifted via schema drift.

+* ``columnNames('DeriveStream', true())``

+* ``columnNames('', true())``

+- [Learn how to use Expression Builder](concepts-data-flow-expression-builder.md).

+| [Multiple changes to identity recommendations](#multiple-changes-to-identity-recommendations) | May 2022 |

+### Multiple changes to identity recommendations

+**Estimated date for change:** May 2022

+Defender for Cloud includes multiple recommendations for improving the management of users and accounts. In December, we'll be making the changes outlined below.

+- **Improved freshness interval** - Currently, the identity recommendations have a freshness interval of 24 hours. This update will reduce that interval to 12 hours.

+- **Account exemption capability** - Defender for Cloud has many features for customizing the experience and making sure your secure score reflects your organization's security priorities. The exempt option on security recommendations is one such feature. For a full overview and instructions, see [Exempting resources and recommendations from your secure score](exempt-resource.md). With this update, you'll be able to exempt specific accounts from evaluation by the eight recommendations listed in the following table.

+ Typically, you'd exempt emergency ΓÇ£break glassΓÇ¥ accounts from MFA recommendations, because such accounts are often deliberately excluded from an organization's MFA requirements. Alternatively, you might have external accounts that you'd like to permit access to but which don't have MFA enabled.

+ > [!TIP]

+ > When you exempt an account, it won't be shown as unhealthy and also won't cause a subscription to appear unhealthy.

+ |Recommendation| Assessment key|

+ |-|-|

+ |[MFA should be enabled on accounts with owner permissions on your subscription](https://portal.azure.com/#blade/Microsoft_Azure_Security/RecommendationsBlade/assessmentKey/94290b00-4d0c-d7b4-7cea-064a9554e681)|94290b00-4d0c-d7b4-7cea-064a9554e681|

+ |[MFA should be enabled on accounts with read permissions on your subscription](https://portal.azure.com/#blade/Microsoft_Azure_Security/RecommendationsBlade/assessmentKey/151e82c5-5341-a74b-1eb0-bc38d2c84bb5)|151e82c5-5341-a74b-1eb0-bc38d2c84bb5|

+ |[MFA should be enabled on accounts with write permissions on your subscription](https://portal.azure.com/#blade/Microsoft_Azure_Security/RecommendationsBlade/assessmentKey/57e98606-6b1e-6193-0e3d-fe621387c16b)|57e98606-6b1e-6193-0e3d-fe621387c16b|

+ |[External accounts with owner permissions should be removed from your subscription](https://portal.azure.com/#blade/Microsoft_Azure_Security/RecommendationsBlade/assessmentKey/c3b6ae71-f1f0-31b4-e6c1-d5951285d03d)|c3b6ae71-f1f0-31b4-e6c1-d5951285d03d|

+ |[External accounts with read permissions should be removed from your subscription](https://portal.azure.com/#blade/Microsoft_Azure_Security/RecommendationsBlade/assessmentKey/a8c6a4ad-d51e-88fe-2979-d3ee3c864f8b)|a8c6a4ad-d51e-88fe-2979-d3ee3c864f8b|

+ |[External accounts with write permissions should be removed from your subscription](https://portal.azure.com/#blade/Microsoft_Azure_Security/RecommendationsBlade/assessmentKey/04e7147b-0deb-9796-2e5c-0336343ceb3d)|04e7147b-0deb-9796-2e5c-0336343ceb3d|

+ |[Deprecated accounts with owner permissions should be removed from your subscription](https://portal.azure.com/#blade/Microsoft_Azure_Security/RecommendationsBlade/assessmentKey/e52064aa-6853-e252-a11e-dffc675689c2)|e52064aa-6853-e252-a11e-dffc675689c2|

+ |[Deprecated accounts should be removed from your subscription](https://portal.azure.com/#blade/Microsoft_Azure_Security/RecommendationsBlade/assessmentKey/00c6d40b-e990-6acf-d4f3-471e747a27c4)|00c6d40b-e990-6acf-d4f3-471e747a27c4|

+ |||

+

+- **Recommendations rename** - From this update, we're renaming two recommendations. We're also revising their descriptions. The assessment keys will remain unchanged.

+ |Property |Current value | From the update|

+ ||||

+ |Assessment key | e52064aa-6853-e252-a11e-dffc675689c2 | Unchanged|

+ |Name |[Deprecated accounts with owner permissions should be removed from your subscription](https://portal.azure.com/#blade/Microsoft_Azure_Security/RecommendationsBlade/assessmentKey/e52064aa-6853-e252-a11e-dffc675689c2) |Subscriptions should be purged of accounts that are blocked in Active Directory and have owner permissions |

+ |Description |User accounts that have been blocked from signing in, should be removed from your subscriptions.<br>These accounts can be targets for attackers looking to find ways to access your data without being noticed.|User accounts that have been blocked from signing into Active Directory, should be removed from your subscriptions. These accounts can be targets for attackers looking to find ways to access your data without being noticed.<br>Learn more about securing the identity perimeter in [Azure Identity Management and access control security best practices](../security/fundamentals/identity-management-best-practices.md).|

+ |Related policy |[Deprecated accounts with owner permissions should be removed from your subscription](https://portal.azure.com/#blade/Microsoft_Azure_Policy/PolicyDetailBlade/definitionId/%2fproviders%2fMicrosoft.Authorization%2fpolicyDefinitions%2febb62a0c-3560-49e1-89ed-27e074e9f8ad) |Subscriptions should be purged of accounts that are blocked in Active Directory and have owner permissions |

+ |||

+ |Property |Current value | From the update|

+ ||||

+ |Assessment key | 00c6d40b-e990-6acf-d4f3-471e747a27c4 | Unchanged|

+ |Name |[Deprecated accounts should be removed from your subscription](https://portal.azure.com/#blade/Microsoft_Azure_Security/RecommendationsBlade/assessmentKey/00c6d40b-e990-6acf-d4f3-471e747a27c4)|Subscriptions should be purged of accounts that are blocked in Active Directory and have read and write permissions|

+ |Description |User accounts that have been blocked from signing in, should be removed from your subscriptions.<br>These accounts can be targets for attackers looking to find ways to access your data without being noticed.|User accounts that have been blocked from signing into Active Directory, should be removed from your subscriptions. These accounts can be targets for attackers looking to find ways to access your data without being noticed.<br>Learn more about securing the identity perimeter in [Azure Identity Management and access control security best practices](../security/fundamentals/identity-management-best-practices.md).|

+ |Related policy |[Deprecated accounts should be removed from your subscription](https://portal.azure.com/#blade/Microsoft_Azure_Policy/PolicyDetailBlade/definitionId/%2fproviders%2fMicrosoft.Authorization%2fpolicyDefinitions%2f6b1cbf55-e8b6-442f-ba4c-7246b6381474)|Subscriptions should be purged of accounts that are blocked in Active Directory and have read and write permissions|

+ |||

+1. In Defender for IoT select **System Settings**.

+Azure Digital Twins comes equipped with control plane APIs, data plane APIs, and SDKs for managing your instance and its elements.

+The most current control plane API version is 2020-12-01.

+* DigitalTwinModels - The DigitalTwinModels category contains APIs to manage the [models](concepts-models.md) in an Azure Digital Twins instance. Management activities include upload, validation, retrieval, and deletion of models authored in DTDL.

+* DigitalTwins - The DigitalTwins category contains the APIs that let developers create, modify, and delete [digital twins](concepts-twins-graph.md) and their relationships in an Azure Digital Twins instance.

+* Query - The Query category lets developers [find sets of digital twins in the twin graph](how-to-query-graph.md) across relationships.

+* Event Routes - The Event Routes category contains APIs to [route data](concepts-route-events.md), through the system and to downstream services.

+The most current data plane API version is 2020-10-31.

+* You can use the .NET (C#) SDK. To use the .NET SDK...

+* You can use the Java SDK. To use the Java SDK...

+* You can use the JavaScript SDK. To use the JavaScript SDK...

+* You can use the Python SDK. To use the Python SDK...

+To use the SDK, include the NuGet package `Azure.DigitalTwins.Core` with your project. You'll also need the latest version of the `Azure.Identity` package. In Visual Studio, you can add these packages using the NuGet Package Manager (accessed through **Tools > NuGet Package Manager > Manage NuGet Packages for Solution**). You can also use the .NET command-line tool with the commands found in the NuGet package links below to add these packages to your project:

+> Please note that Azure Digital Twins doesn't currently support Cross-Origin Resource Sharing (CORS). For more info about the impact and resolution strategies, see the [Cross-Origin Resource Sharing (CORS)](concepts-security.md#cross-origin-resource-sharing-cors) section of *Concepts: Security for Azure Digital Twins solutions*.

+* Requests to the Azure Digital Twins APIs require a user or service principal that is a part of the same [Azure Active Directory](../active-directory/fundamentals/active-directory-whatis.md) (Azure AD) tenant where the Azure Digital Twins instance exists. To prevent malicious scanning of Azure Digital Twins endpoints, requests with access tokens from outside the originating tenant will be returned a "404 Sub-Domain not found" error message. This error will be returned even if the user or service principal was given an Azure Digital Twins Data Owner or Azure Digital Twins Data Reader role through [Azure AD B2B](../active-directory/external-identities/what-is-b2b.md) collaboration. For information on how to achieve access across multiple tenants, see [Write app authentication code](how-to-authenticate-client.md#authenticate-across-tenants).

+From the portal homepage, search for your Azure Digital Twins instance to pull up its details. Select the **Metrics** option from the Azure Digital Twins instance's menu to bring up the **Metrics** page.

+This article contains information about the Azure Digital Twins Explorer, including its use cases and an overview of its features. For detailed steps on using each feature, see [Use Azure Digital Twins Explorer](how-to-use-azure-digital-twins-explorer.md).

+*Azure Digital Twins Explorer* is a developer tool for visualizing and interacting with the data in your Azure Digital Twins instance, including your [models](concepts-models.md) and [twin graph](concepts-twins-graph.md).

+>This tool is currently in public preview.

+* Exploration: Use the explorer to learn about Azure Digital Twins and the way it represents your real-world environment. Import sample models and graphs that you can view and edit to familiarize yourself with the service. For guided steps to get started using Azure Digital Twins Explorer, see [Get started with Azure Digital Twins Explorer](quickstart-azure-digital-twins-explorer.md).

+* Development: Use the explorer to view and validate your twin graph. You can also use it to investigate specific properties of models, twins, and relationships. Make on the spot modifications to your graph and its data. For detailed instructions on how to use each feature, see [Use Azure Digital Twins Explorer](how-to-use-azure-digital-twins-explorer.md).

+Azure Digital Twins Explorer is an open-source tool that welcomes contributions to the code and documentation. The hosted application is deployed regularly from a source code repository in GitHub.

+The command set is called `az dt`, and is part of the [Azure IoT extension for Azure CLI](https://github.com/Azure/azure-iot-cli-extension). You can view the full list of commands and their usage as part of the reference documentation for the `az iot` command set: [az dt command reference](/cli/azure/dt).

+The Azure Digital Twins commands are part of the [Azure IoT extension for Azure CLI (azure-iot)](https://github.com/Azure/azure-iot-cli-extension), so follow these steps to make sure you have the latest `azure-iot` extension with the `az dt` commands.

+If you're using the Azure CLI with PowerShell, your Azure CLI version should be 2.3.1 or above as a requirement of the extension package.

+You can use an update policy to enrich your raw time series data with the corresponding twin ID from Azure Digital Twins, and persist it to a target table. Using the twin ID, the target table can then be joined against the digital twins selected by the Azure Digital Twins plugin.

+Azure Digital Twins can send data to connected endpoints. Supported endpoints can be:

+Azure Digital Twins implements *at least once* delivery for data emitted to egress services.

+Different events in Azure Digital Twins produce *notifications*, which allow the solution backend to be aware when different actions are happening. These notifications are then [routed](concepts-route-events.md) to different locations inside and outside of Azure Digital Twins that can use this information to take action.

+*Digital twin change notifications* are triggered when a digital twin is being updated, like:

+Whether [digital twins](concepts-twins-graph.md) represent [IoT Hub devices in Azure Digital Twins](how-to-ingest-iot-hub-data.md) or not, they will all emit notifications. They do so because of *lifecycle notifications*, which are about the digital twin itself.

+*Relationship change notifications* are triggered when any relationship of a digital twin is created, updated, or deleted.

+*Telemetry messages* are received in Azure Digital Twins from connected devices that collect and send measurements.

+This article discusses the High Availability (HA) and Disaster Recovery (DR) features offered specifically by the Azure Digital Twins service. The article covers intra-region HA, cross region DR, monitoring service health, and best practices on HA/DR.

+Azure Digital Twins provides *intra-region HA* by implementing redundancies within the service. This functionality is reflected in the [service SLA](https://azure.microsoft.com/support/legal/sla/digital-twins) for uptime. No additional work is required by the developers of an Azure Digital Twins solution to take advantage of these HA features. Although Azure Digital Twins offers a reasonably high uptime guarantee, transient failures can still be expected, as with any distributed computing platform. Appropriate retry policies should be built in to the components interacting with a cloud application to deal with transient failures.

+*Microsoft-initiated failover* is exercised in rare situations to failover all the Azure Digital Twins instances from an affected region to the corresponding [geo-paired region](../availability-zones/cross-region-replication-azure.md). This process is a default option (with no way for users to opt out), and requires no intervention from the user. Microsoft reserves the right to make a determination of when this option will be exercised. This mechanism doesn't involve user consent before the user's instance is failed over.

+> Some Azure services provide an additional option called *customer-initiated failover*, which enables customers to initiate a failover just for their instance, such as to run a DR drill. This mechanism is currently not supported by Azure Digital Twins.

+> Some Azure services provide an option for users to configure a different region for failover, as a way to meet data residency requirements. This capability is currently not supported by Azure Digital Twins.

+1. Use the left menu to switch to the **Health history** page.

+1. Look for an **Issue Name** beginning with **Azure Digital Twins**, and select it.

+1. For general information about the outage, view the **Summary** tab.

+1. For more information and updates on the issue over time, view the **Issue updates** tab.

+A key characteristic of Azure Digital Twins is the ability to define your own vocabulary and build your twin graph in the self-defined terms of your business. This capability is provided through user-provided *models*. You can think of models as the nouns in a description of your world. Azure Digital Twins models are represented in the JSON-LD-based *Digital Twin Definition Language (DTDL)*.

+A model is similar to a *class* in an object-oriented programming language, defining a data shape for one particular concept in your real work environment. Models have names (such as Room or TemperatureSensor), and contain elements such as properties, telemetry/events, and commands that describe what this type of entity in your environment can do. Later, you'll use these models to create [digital twins](concepts-twins-graph.md) that represent specific entities that meet this type description.

+DTDL is based on JSON-LD and is programming-language independent. DTDL isn't exclusive to Azure Digital Twins, but is also used to represent device data in other IoT services such as [IoT Plug and Play](../iot-develop/overview-iot-plug-and-play.md). Azure Digital Twins uses DTDL version 2 (use of DTDL version 1 with Azure Digital Twins has now been deprecated).

+* All top-level DTDL elements in a model must be of type `Interface`. The reason for this requirement is that Azure Digital Twins model APIs can receive JSON objects that represent either an interface or an array of interfaces. As a result, no other DTDL element types are allowed at the top level.

+* DTDL for Azure Digital Twins must not define any commands.

+Within a model definition, the top-level code item is an *interface*. This type encapsulates the entire model, and the rest of the model is defined within the interface.

+* *Property* - Properties are data fields that represent the state of an entity (like the properties in many object-oriented programming languages). Properties have backing storage and can be read at any time. For more information, see [Properties and telemetry](#properties-and-telemetry) below.

+* *Telemetry* - Telemetry fields represent measurements or events, and are often used to describe device sensor readings. Unlike properties, telemetry isn't stored on a digital twin; it's a series of time-bound data events that need to be handled as they occur. For more information, see [Properties and telemetry](#properties-and-telemetry) below.

+* *Relationship* - Relationships let you represent how a digital twin can be involved with other digital twins. Relationships can represent different semantic meanings, such as `contains` ("floor contains room"), `cools` ("hvac cools room"), `isBilledTo` ("compressor is billed to user"), and so on. Relationships allow the solution to provide a graph of interrelated entities. Relationships can also have properties of their own. For more information, see [Relationships](#relationships) below.

+* *Component* - Components allow you to build your model interface as an assembly of other interfaces, if you want. An example of a component is a frontCamera interface (and another component interface backCamera) that are used in defining a model for a phone. First define an interface for frontCamera as though it were its own model, and then reference it when defining Phone.

+ Use a component to describe something that is an integral part of your solution but doesn't need a separate identity, and doesn't need to be created, deleted, or rearranged in the twin graph independently. If you want entities to have independent existences in the twin graph, represent them as separate digital twins of different models, connected by relationships.

+> The [spec for DTDL](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/dtdlv2.md) also defines *Commands*, which are methods that can be executed on a digital twin (like a reset command, or a command to switch a fan on or off). However, commands are not currently supported in Azure Digital Twins.

+| `@type` | Identifies the kind of information being described. For an interface, the type is `Interface`. |

+| `contents` | All remaining interface data is placed here, as an array of attribute definitions. Each attribute must provide a `@type` (`Property`, `Telemetry`, `Command`, `Relationship`, or `Component`) to identify the sort of interface information it describes, and then a set of properties that define the actual attribute (for example, `name` and `schema` to define a `Property`). |

+This model describes a Home, with one property for an ID. The Home model also defines a relationship to a Floor model, which can be used to indicate that a Home twin is connected to certain Floor twins.

+This section goes into more detail about *properties* and *telemetry* in DTDL models.

+Here's some guidance on conceptually distinguishing between DTDL properties and telemetry in Azure Digital Twins.

+* *Properties* are expected to have backing storage, which means that you can read a property at any time and retrieve its value. If the property is writable, you can also store a value in the property.

+* *Telemetry* is more like a stream of events; it's a set of data messages that have short lifespans. If you don't set up listening for the event and actions to take when it happens, there's no trace of the event at a later time. You can't come back to it and read it later.

+Telemetry is often used with IoT devices, because many devices either can't, or aren't interested in, storing the measurement values they generate. Instead, they send them out as a stream of "telemetry" events. In this case, you can't query the device at any time for the latest value of the telemetry field. You'll need to listen to the messages from the device and take actions as the messages arrive.

+As a result, when designing a model in Azure Digital Twins, you'll probably use properties in most cases to model your twins. Doing so allows you to have the backing storage and the ability to read and query the data fields.

+As per DTDL, the schema for property and telemetry attributes can be of standard primitive typesΓÇö`integer`, `double`, `string`, and `boolean`ΓÇöand other types such as `dateTime` and `duration`.

+* (telemetry only) `Array`

+Here's a basic example of a property on a DTDL model. This example shows the ID property of a Home.

+Here's a basic example of a telemetry field on a DTDL model. This example shows Temperature telemetry on a Sensor.

+This section goes into more detail about *relationships* in DTDL models.

+Relationships can be defined with or without a *target*. A target specifies which types of twin the relationship can reach. For example, you might include a target to specify that a Home model can only have a `rel_has_floors` relationship with twins that are Floor twins.

+DTDL also allows for relationships to have properties of their own. When defining a relationship within a DTDL model, the relationship can have its own `properties` field where you can define custom properties to describe relationship-specific state.

+This section goes into more detail about *components* in DTDL models.

+Sometimes, you may want to specialize a model further. For example, it might be useful to have a generic model Room, and specialized variants ConferenceRoom and Gym. To express specialization, DTDL supports *inheritance*. Interfaces can inherit from one or more other interfaces. You can do so by adding an `extends` field to the model.

+The extending interface can't change any of the definitions of the parent interfaces; it can only add to them. It also can't redefine a capability already defined in any of its parent interfaces (even if the capabilities are defined to be the same). For example, if a parent interface defines a `double` property `mass`, the extending interface can't contain a declaration of `mass`, even if it's also a `double`.

+Get the ontology from the following repository: [Digital Twins Definition Language-based RealEstateCore ontology for smart buildings](https://github.com/Azure/opendigitaltwins-building).

+Get the ontology from the following repository: [Digital Twins Definition Language (DTDL) ontology for Smart Cities](https://github.com/Azure/opendigitaltwins-smartcities).

+Get the ontology from the following repository: [Digital Twins Definition Language (DTDL) ontology for Energy Grid](https://github.com/Azure/opendigitaltwins-energygrid/).

+To use a model with Azure Digital Twins, it must be in DTDL format. This article describes general design guidance in the form of a conversion pattern for converting RDF-based models to DTDL so that they can be used with Azure Digital Twins.

+| Adopt | You can start your solution with an open-source DTDL ontology that has been built on widely adopted industry standards. You can either use these model-sets out-of-the-box, or extend them with your own additions for a customized solution. | [Adopting&nbsp;industry&nbsp;standard ontologies](concepts-ontologies-adopt.md)<br><br>[Extending&nbsp;ontologies](concepts-ontologies-extend.md) |

+| Convert | If you already have existing models represented in another standard format, you can convert them to DTDL to use them with Azure Digital Twins. | [Converting&nbsp;ontologies](concepts-ontologies-convert.md)<br><br>[Extending&nbsp;ontologies](concepts-ontologies-extend.md) |

+| Author | You can always develop your own custom DTDL models from scratch, using any applicable industry standards as inspiration. | [DTDL models](concepts-models.md) |

+This article describes the basics of the query language and its capabilities. Recall that the center of Azure Digital Twins is the [twin graph](concepts-twins-graph.md), constructed from digital twins and relationships. This graph can be queried to get information about the digital twins and relationships it contains. These queries are written in a custom SQL-like query language, referred to as the *Azure Digital Twins query language*. This language is similar to the [IoT Hub query language](../iot-hub/iot-hub-devguide-query-language.md) with many comparable features.

+* Remember case sensitivity: All Azure Digital Twins query operations are case-sensitive, so take care to use the exact names defined in the models. If property names are misspelled or incorrectly cased, the result set is empty with no errors returned.

+* Escape single quotes: If your query text includes a single quote character in the data, the quote will need to be escaped with the `\` character. Here's an example that deals with a property value of *D'Souza*:

+An Azure Digital Twins *Query Unit (QU)* is a unit of on-demand computation that's used to execute your [Azure Digital Twins queries](how-to-query-graph.md) using the [Query API](/rest/api/digital-twins/dataplane/query).

+This article covers *event routes* and how Azure Digital Twins uses them to send data internally and to consumers outside the service.

+Azure Digital Twins implements *at least once* delivery for data emitted to egress services.

+To define an event route, developers first must define endpoints. An *endpoint* is a destination outside of Azure Digital Twins that supports a route connection. Supported destinations include:

+* The topic path of the endpoint, such as `your-topic.westus2.eventgrid.azure.net`

+When an endpoint can't deliver an event within a certain time period or after trying to deliver the event several times, it can send the undelivered event to a storage account. This process is known as *dead-lettering*. Azure Digital Twins will dead-letter an event when one of the following conditions is met:

+If either of the conditions is met, the event is dropped or dead-lettered. By default, each endpoint doesn't turn on dead-lettering. To enable it, you must specify a storage account to hold undelivered events when creating the endpoint. You can then pull events from this storage account to resolve deliveries.

+1. First, the security principal's identity is authenticated, and an OAuth 2.0 token is returned.

+2. Next, the token is passed as part of a request to the Azure Digital Twins service, to authorize access to the specified resource.

+The authentication step requires any application request to contain an OAuth 2.0 access token at runtime. If an application is running within an Azure entity such as an [Azure Functions](../azure-functions/functions-overview.md) app, it can use a *managed identity* to access the resources. Read more about managed identities in the next section.

+Azure provides two Azure built-in roles for authorizing access to the Azure Digital Twins [data plane APIs](concepts-apis-sdks.md#overview-data-plane-apis). You can refer to the roles either by name or by ID:

+When referring to roles in automated scenarios, it's recommended to refer to them by their IDs rather than their names. The names may change between releases, but the IDs won't, making them a more stable reference in automation.

+Setting up an [Azure Active Directory (Azure AD)](../active-directory/fundamentals/active-directory-whatis.md) *managed identity* for an Azure Digital Twins instance can allow the instance to easily access other Azure AD-protected resources, such as [Azure Key Vault](../key-vault/general/overview.md). The identity is managed by the Azure platform, and doesn't require you to provision or rotate any secrets. For more about managed identities in Azure AD, see [Managed identities for Azure resources](../active-directory/managed-identities-azure-resources/overview.md).

+Azure supports two types of managed identities: system-assigned and user-assigned. Currently, Azure Digital Twins supports only *system-assigned identities*.

+* Pricing: For pricing details, see [Azure Private Link pricing](https://azure.microsoft.com/pricing/details/private-link).

+* Regional availability: For Azure Digital Twins, this feature is available in all the Azure regions where Azure Digital Twins is available.

+* Maximum number of private endpoints per Azure Digital Twins instance: 10

+A *service tag* represents a group of IP address prefixes from a given Azure service. Microsoft manages the address prefixes encompassed by the service tag and automatically updates the service tag as addresses change, minimizing the complexity of frequent updates to network security rules. For more information about service tags, see [Virtual network tags](../virtual-network/service-tags-overview.md).

+You can use service tags to define network access controls on [network security groups](../virtual-network/network-security-groups-overview.md#security-rules) or [Azure Firewall](../firewall/service-tags.md), by using service tags in place of specific IP addresses when you create security rules. By specifying the service tag name (in this case, AzureDigitalTwins) in the appropriate **source** or **destination** field of a rule, you can allow or deny the traffic for the corresponding service.

+Below are the details of the AzureDigitalTwins service tag.

+4. Set IP filters on the external resource(s) using the IP ranges from Step 2.

+Azure Digital Twins doesn't currently support Cross-Origin Resource Sharing (CORS). As a result, if you're calling a REST API from a browser app, an [API Management (APIM)](../api-management/api-management-key-concepts.md) interface, or a [Power Apps](/powerapps/powerapps-overview) connector, you may see a policy error.

+This article describes what digital twins are in the context of Azure Digital Twins, and how relationships between them can form a twin graph. In an Azure Digital Twins solution, the entities in your environment are represented by *digital twins*. A digital twin is an instance of one of your custom-defined [models](concepts-models.md). It can be connected to other digital twins via *relationships* to form a *twin graph*: this twin graph is the representation of your entire environment.

+For example, the model Floor might define a `contains` relationship that targets twins of type Room. With this definition, Azure Digital Twins will allow you to create `contains` relationships from any Floor twin to any Room twin (including twins that are of Room subtypes).

+You can also use a helper class called `BasicDigitalTwin` to store property fields in a "twin" object more directly, as an alternative to using a dictionary. For more information about the helper class and examples of its use, see [Create a digital twin](how-to-manage-twin.md#create-a-digital-twin).

+>While twin properties are treated as optional and thus don't have to be initialized, any [components](concepts-models.md#elements-of-a-model) on the twin need to be set when the twin is created. They can be empty objects, but the components themselves must exist.

+> You may prefer to set up a new app registration every time you need one, or to do this only once, establishing a single app registration that will be shared among all scenarios that require it.

+Create a new .json file on your computer called *manifest.json*. Copy this text into the file:

+Navigate to the *manifest.json* file on your machine and select **Open**. Doing so will upload the file to the root of your Cloud Shell storage.

+* resource name

+* client ID

+* tenant ID

+* client secret

+To work with Azure Digital Twins, the resource name is `http://digitaltwins.azure.net`.

+To create a client secret for your app registration, you'll need your app registration's client ID value from the previous section. Use the value in the following CLI command to create a new secret:

+> You may prefer to set up a new app registration every time you need one, or to do this only once, establishing a single app registration that will be shared among all scenarios that require it.

+Start by navigating to [Azure Active Directory](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview) in the Azure portal (you can use this link or find it with the portal search bar). Select **App registrations** from the service menu, and then **+ New registration**.

+In the **Register an application** page that follows, fill in the requested values:

+* **Supported account types**: Select **Accounts in this organizational directory only (Default Directory only - Single tenant)**

+* **Redirect URI**: An **Azure AD application reply URL** for the Azure AD application. Add a **Public client/native (mobile & desktop)** URI for `http://localhost`.

+When you're finished, select the **Register** button.

+* resource name

+* client ID

+* tenant ID

+* client secret

+To work with Azure Digital Twins, the resource name is `http://digitaltwins.azure.net`.

+The client ID and tenant ID values can be collected from the app registration's details page in the Azure portal:

+Take note of the **Application (client) ID** and **Directory (tenant) ID** shown on your page.

+To set up a client secret for your app registration, start on your app registration page in the Azure portal.

+1. Select **Certificates & secrets** from the registration's menu, and then select **+ New client secret**.

+Next, configure the app registration you've created with permissions to access Azure Digital Twins. First, you'll create a role assignment for the app registration within the Azure Digital Twins instance. Then, you'll provide API permissions for the app to read and write to the Azure Digital Twins APIs.

+You can view the role assignment you've set up under **Access control (IAM) > Role assignments**.

+From the portal page for your app registration, select **API permissions** from the menu. On the following permissions page, select the **+ Add a permission** button.

+In the **Request API permissions** page that follows, switch to the **APIs my organization uses** tab and search for *Azure digital twins*. Select **Azure Digital Twins** from the search results to continue with assigning permissions for the Azure Digital Twins APIs.

+> If your subscription still has an existing Azure Digital Twins instance from the previous public preview of the service (before July 2020), you'll need to search for and select **Azure Smart Spaces Service** instead. This is an older name for the same set of APIs (notice that the **Application (client) ID** is the same as in the screenshot above), and your experience won't be changed beyond this step.

+Next, you'll select which permissions to grant for these APIs. Expand the **Read (1)** permission and check the box that says **Read.Write** to grant this app registration reader and writer permissions.

+Select **Add permissions** when finished.

+On the **API permissions** page, verify that there's now an entry for Azure Digital Twins reflecting **Read.Write** permissions:

+* Grant admin consent for the app registration. Your organization may have **Admin Consent Required** globally turned on in Azure AD for all app registrations within your subscription. If so, the Owner/administrator will need to select this button for your company on the app registration's **API permissions** page for the app registration to be valid:

+ - If consent was granted successfully, the entry for Azure Digital Twins should then show a **Status** value of **Granted for (your company)**

+Once a private endpoint has been created for your Azure Digital Twins instance, you can use the [az dt network private-endpoint connection](/cli/azure/dt/network/private-endpoint/connection) commands to continue managing private endpoint connections with respect to the instance. Operations include:

+You can configure your Azure Digital Twins instance to deny all public connections and allow only connections through private endpoints to enhance the network security. This action is done with a *public network access flag*.

+This policy allows you to restrict API access to Private Link connections only. When the public network access flag is set to `disabled`, all REST API calls to the Azure Digital Twins instance data plane from the public cloud will return `403, Unauthorized`. Otherwise, when the policy is set to `disabled` and a request is made through a private endpoint, the API call will succeed.

+To disable public network access for an Azure Digital Twins instance, use the `--public-network-access` parameter like this:

+To enable public network access on an instance where it's currently disabled, use the following similar command:

+To disable public network access:

+To enable public network access:

+* An IoT hub. For instructions, see the [Create an IoT Hub section of this IoT Hub quickstart](../iot-hub/quickstart-send-telemetry-cli.md).

+* An Azure Digital Twins instance that will receive your device telemetry. For instructions, see [Set up an Azure Digital Twins instance and authentication](./how-to-set-up-instance-portal.md).

+This article also uses Visual Studio. You can download the latest version from [Visual Studio Downloads](https://visualstudio.microsoft.com/downloads/).

+Whenever a temperature telemetry event is sent by the thermostat device, a function processes the telemetry and the `Temperature` property of the digital twin should update. This scenario is outlined in a diagram below:

+You'll then need to create one twin using this model. Use the following command to create a thermostat twin named thermostat67, and set 0.0 as an initial temperature value.

+Next, assign an access role for the function and configure the application settings so that it can access your Azure Digital Twins instance.

+ 2. For **Event Schema**, choose **Event Grid Schema**.

+ 1. For **Filter to Event Types**, choose the **Device Telemetry** checkbox and uncheck other event types.

+ 1. For **Endpoint Type**, Select **Azure Function**.

+ 1. For **Endpoint**, use the **Select an endpoint** link to choose what Azure Function to use for the endpoint.

+In the **Select Azure Function** page that opens up, verify or fill in the below details.

+ 4. **Slot**: **Production**.

+Save your details with the **Confirm Selection** button.

+Select the **Create** button to create the event subscription.

+To test your new ingress function, use the device simulator from [Connect an end-to-end solution](./tutorial-end-to-end.md). That tutorial is driven by this [Azure Digital Twins end-to-end sample project written in C#](/samples/azure-samples/digital-twins-samples/digital-twins-samples). You'll be using the *DeviceSimulator* project in that repository.

+* Download sample repo: This article uses a [DTDL model](concepts-models.md) file and an Azure function body from the [OPC UA to Azure Digital Twins GitHub Repo](https://github.com/Azure-Samples/opcua-to-azure-digital-twins). Start by downloading the sample repo onto your machine. You can select the **Code** button for the repo to either clone the repository or download it as a .zip file to your machine.

+* Download Visual Studio: This article uses Visual Studio to publish an Azure function. You can download the latest version of Visual Studio from [Visual Studio Downloads](https://visualstudio.microsoft.com/downloads/).

+You can use [Azure Digital Twins Explorer](concepts-azure-digital-twins-explorer.md) to upload the Simulation model, and create a new twin called simulation-1.

+1. Navigate to the downloaded [OPC UA to Azure Digital Twins](https://github.com/Azure-Samples/opcua-to-azure-digital-twins) project on your local machine, and into the *Azure Functions/OPCUAFunctions* folder. Open the *OPCUAFunctions.sln* solution in Visual Studio.

+Next, assign an access role for the function and configure the application settings so that it can access your Azure Digital Twins instance.

+Lastly, create an event subscription to connect your function app and ProcessOPCPublisherEventsToADT function to your IoT Hub. The event subscription is needed so that data can flow from the gateway device into IoT Hub through the function, which then updates Azure Digital Twins.

+The event subscription will have an **Endpoint type** of **Azure function**, and an **Endpoint** of **ProcessOPCPublisherEventsToADT**.

+> * Published the sample function ProcessOPCPublisherEventsToADT to a function app in Azure.

+* [OPCUA2DTDL](https://github.com/khilscher/OPCUA2DTDL)

+ - If you haven't already downloaded the sample as part of the tutorial in [Prerequisites](#prerequisites), [navigate to the sample](/samples/azure-samples/digital-twins-samples/digital-twins-samples/) and select the **Browse code** button underneath the title. Doing so will take you to the GitHub repo for the samples, which you can download as a .zip by selecting the **Code** button and **Download ZIP**.

+ This button will download a copy of the sample repo in your machine, as *digital-twins-samples-master.zip*. Unzip the folder.

+ - Navigate to the sample link and use the same download process to download a copy of the sample to your machine, as *digitaltwins-signalr-webapp-sample-main.zip*. Unzip the folder.

+* *negotiate* - A HTTP trigger function. It uses the *SignalRConnectionInfo* input binding to generate and return valid connection information.

+* *broadcast* - An [Event Grid](../event-grid/overview.md) trigger function. It receives Azure Digital Twins telemetry data through the event grid, and uses the output binding of the SignalR instance you created in the previous step to broadcast the message to all connected client applications.

+1. In the *SampleFunctionsApp* project, create a new C# class called *SignalRFunctions.cs*. For instructions on how to create a new class, see [Develop Azure Functions using Visual Studio](../azure-functions/functions-develop-vs.md#add-a-function-to-your-project).

+1. In Visual Studio's **Package Manager Console** window, or any command window on your machine, navigate to the folder *digital-twins-samples-master\AdtSampleApp\SampleFunctionsApp*, and run the following command to install the `SignalRService` NuGet package to the project:

+Next, configure the function to communicate with your Azure SignalR instance. You'll start by gathering the SignalR instance's connection string, and then add it to the functions app's settings.

+1. Select the **Copy** icon to copy the **Primary CONNECTION STRING**.

+1. Finally, add your Azure SignalR connection string to the function's app settings, using the following Azure CLI command. Also, replace the placeholders with your resource group and app service/function app name from the [tutorial prerequisite](how-to-integrate-azure-signalr.md#prerequisites). The command can be run in [Azure Cloud Shell](https://shell.azure.com), or locally if you have the [Azure CLI installed on your machine](/cli/azure/install-azure-cli):

+Next, subscribe the *broadcast* Azure function to the Event Grid topic you created during the [tutorial prerequisite](how-to-integrate-azure-signalr.md#prerequisites). This action will allow telemetry data to flow from the thermostat67 twin through the Event Grid topic and to the function. From here, the function can broadcast the data to all the clients.

+To broadcast the data, you'll create an Event subscription from your Event Grid topic to your *broadcast* Azure function as an endpoint.

+In the [Azure portal](https://portal.azure.com/), navigate to your Event Grid topic by searching for its name in the top search bar. Select **+ Event Subscription**.

+On the **Create Event Subscription** page, fill in the fields as follows (fields filled by default aren't mentioned):

+* **EVENT SUBSCRIPTION DETAILS** > **Name**: Give a name to your event subscription.

+* **ENDPOINT DETAILS** > **Endpoint Type**: Select **Azure Function** from the menu options.

+* **ENDPOINT DETAILS** > **Endpoint**: Select the **Select an endpoint** link, which will open a **Select Azure Function** window:

+ - Fill in your **Subscription**, **Resource group**, **Function app**, and **Function** (**broadcast**). Some of these fields may autopopulate after selecting the subscription.

+Back on the **Create Event Subscription** page, select **Create**.

+At this point, you should see two event subscriptions in the **Event Grid Topic** page.

+In this section, you'll see the result in action. First, configure the sample client web app to connect to the Azure SignalR flow you've set up. Next, you'll start up the simulated device sample app that sends telemetry data through your Azure Digital Twins instance. After that, you'll view the sample web app to see the simulated device data updating the sample web app in real time.

+Next, you'll configure the sample client web app. Start by gathering the HTTP endpoint URL of the *negotiate* function, and then use it to configure the app code on your machine.

+1. Go to the Azure portal's [Function apps](https://portal.azure.com/#blade/HubsExtension/BrowseResource/resourceType/Microsoft.Web%2Fsites/kind/functionapp) page and select your function app from the list. In the app menu, select **Functions** and choose the **negotiate** function.

+1. Select **Get function URL** and copy the value up through **/api** (don't include the last **/negotiate?**). You'll use this value in the next step.

+1. In Visual Studio's **Developer command prompt** or any command window on your machine, navigate to the *digitaltwins-signalr-webapp-sample-main\src* folder. Run the following command to install the dependent node packages:

+1. Scroll down in the instance menu and select **CORS**. On the CORS page, add `http://localhost:3000` as an allowed origin by entering it into the empty box. Check the box for **Enable Access-Control-Allow-Credentials** and select **Save**.

+To see the results in action, start the SignalR integration web app sample. You can do so from any console window at the *digitaltwins-signalr-webapp-sample-main\src* location, by running this command:

+In this article, you'll use the [Azure portal](https://portal.azure.com) to create a *custom connector* that can be used to connect Logic Apps to an Azure Digital Twins instance. You'll then create a *logic app* that uses this connection for an example scenario, in which events triggered by a timer will automatically update a twin in your Azure Digital Twins instance.

+You'll need the Twin ID of a twin in your instance that you've created.

+Navigate to the [Logic Apps Custom Connector](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Web%2FcustomApis) page in the Azure portal (you can use this link or search for it in the portal search bar). Select **+ Create**.

+The custom Swagger for this tutorial is located in the *digital-twins-custom-swaggers-main\LogicApps* folder. This folder contains subfolders called *stable* and *preview*, both of which hold different versions of the Swagger organized by date. The folder with the most recent date will contain the latest copy of the Swagger definition file. Whichever version you select, the Swagger file is named *digitaltwins.json*.

+> Unless you're working with a preview feature, it's generally recommended to use the most recent stable version of the Swagger file. However, earlier versions and preview versions of the Swagger file are also still supported.

+ - **API Endpoint**: **REST** (leave default)

+ - **Import mode**: **OpenAPI file** (leave default)

+ - **File**: This configuration will be the custom Swagger file you downloaded earlier. Select **Import**, locate the file on your machine (*Azure_Digital_Twins_custom_Swaggers__Logic_Apps_connector_\LogicApps\...\digitaltwins.json*), and select **Open**.

+ - **Icon**: Upload an icon that you like.

+ - **Icon background color**: Enter hexadecimal code in the format '#xxxxxx' for your color.

+ - **Description**: Fill whatever values you want.

+ - **Connect via on-premises data gateway**: **Toggled off** (leave default)

+ - **Scheme**: **HTTPS** (leave default)

+ - **Host**: The host name of your Azure Digital Twins instance.

+ - **Base URL**: */* (leave default)

+* **Authentication type**: **OAuth 2.0**

+ - **Identity provider**: **Azure Active Directory**

+ - **Client ID**: The Application (client) ID for the Azure AD app registration you created in [Prerequisites](#prerequisites)

+ - **Client secret**: The Client secret from the app registration

+ - **Login URL**: `https://login.windows.net` (leave default)

+ - **Tenant ID**: The Directory (tenant) ID for your Azure AD app registration

+ - **Resource URL**: *0b07f429-9f4b-4714-9392-cc5e8e80c8b0*

+ - **Scope**: *Directory.AccessAsUser.All*

+ - **Redirect URL**: (leave default for now)

+The Redirect URL field says **Save the custom connector to generate the redirect URL**. Generate it now by selecting **Update connector** across the top of the pane to confirm your connector settings.

+Enter the custom connector's redirect URL into the new field, and select the **Save** icon.

+In the [Azure portal](https://portal.azure.com), search for *Logic apps* in the portal search bar. Selecting it should take you to the **Logic apps** page. Select **+ Add** to create a new logic app.

+Select the **Review + create** button.

+* **id**: Fill the *Twin ID* of the digital twin in your instance that you want the Logic App to update.

+* **twin**: This field is where you'll enter the body that the chosen API request requires. For **DigitalTwinsUpdate**, this body is in the form of JSON Patch code. For more about structuring a JSON Patch to update your twin, see the [Update a digital twin](how-to-manage-twin.md#update-a-digital-twin) section of *How-to: Manage digital twins*.

+* **api-version**: The latest API version. Currently, this value is *2020-10-31*.

+You can choose other operations by selecting **+ New step** on the same window.

+ * You'll need your feature **stateset ID** and Azure Maps **subscription key**.

+ >There is currently a known issue in Cloud Shell affecting these command groups: `az dt route`, `az dt model`, `az dt twin`.

+You're going to create an Event Grid-triggered function inside your function app from the end-to-end tutorial ([Connect an end-to-end solution](./tutorial-end-to-end.md)). This function will unpack those notifications and send updates to an Azure Maps feature stateset to update the temperature of one room.

+1. Begin sending simulated IoT data by running the *DeviceSimulator* project from the Azure Digital Twins [Connect an end-to-end solution](tutorial-end-to-end.md). The instructions for this process are in the [Configure and run the simulation](././tutorial-end-to-end.md#configure-and-run-the-simulation) section.

+ 1. Replace the **subscription key**, **tilesetId**, and **statesetID** in the local HTML file with your values.

+* An Azure Digital Twins instance. For instructions, see [Set up an Azure Digital Twins instance and authentication](./how-to-set-up-instance-portal.md).

+* A model and a twin in the Azure Digital Twins instance. You'll need to update twin's information a few times to see that data tracked in Time Series Insights. For instructions, see [Add a model and twin](how-to-ingest-iot-hub-data.md#add-a-model-and-twin).

+ 1. *Twins hub* - Event hub to receive twin change events

+ 2. *Time series hub* - Event hub to stream events to Time Series Insights

+The first event hub you'll create in this article is the *twins hub*. This event hub will receive twin change events from Azure Digital Twins. To set up the twins hub, you'll complete the following steps in this section:

+Create the twins hub with the following CLI command. Specify a name for your twins hub.

+Azure Digital Twins instances can emit [twin update events](./concepts-event-notifications.md) whenever a twin's state is updated. In this section, you'll create an Azure Digital Twins event route that will direct these update events to the twins hub for further processing.

+The second event hub you'll create in this article is the *time series hub*. This event hub is the one that will stream the Azure Digital Twins events to Time Series Insights. To set up the time series hub, you'll complete these steps:

+Create the time series hub using the following command. Specify a name for the time series hub.

+Next, assign an access role for the function and configure the application settings so that it can access your resources.

+Next, add environment variables in the function app's settings that allow it to access the twins hub and time series hub.

+Use the twins hub primaryConnectionString value that you saved earlier to create an app setting in your function app that contains the twins hub connection string:

+Use the time series hub primaryConnectionString value that you saved earlier to create an app setting in your function app that contains the time series hub connection string:

+ * **Enable warm store** - Leave this field set to **Yes**.

+2. In the **Event Source** tab, choose the following fields:

+ * **Create an event source?** - Choose **Yes**.

+ * **Source type** - Choose **Event Hub**.

+ * **Event Hub name** - Choose the time series hub name that you created earlier in this article.

+ * **Event Hub access policy name** - Choose the time series hub auth rule that you created earlier in this article.

+ * **Event Hub consumer group** - Select **New** and specify a name for your event hub consumer group. Then, select **Add**.

+Use the [az dt twin update](/cli/azure/dt/twin#az_dt_twin_update) CLI command to update a property on the twin you added in the [Prerequisites](#prerequisites) section. If you used the twin creation instructions from [Ingest telemetry from IoT Hub](how-to-ingest-iot-hub-data.md)), you can use the following command in the local CLI or the Cloud Shell bash terminal to update the temperature property on the thermostat67 twin.

+Repeat the command at least 4 more times with different property values to create several data points that can be observed later in the Time Series Insights environment.

+1. In the [Azure portal](https://portal.azure.com), search for your time series environment name that you created earlier. In the menu options on the left, select **Overview** to see the **Time Series Insights Explorer URL**. Select the URL to view the temperature changes reflected in the Time Series Insights environment.

+This model defines a name and a unique ID for the patient room, and properties to represent visitor count and hand-wash status. These counters will be updated from motion sensors and smart soap dispensers, and will be used together to calculate a `handwash percentage` property. The model also defines a relationship `hasDevices`, which will be used to connect any [digital twins](concepts-twins-graph.md) based on this Room model to the actual devices.

+ - Use this strategy when you want to update only some of your twins that use the model, or when you want to make sure twins stay conformant with their models and writable through the model transition.

+ - Use this strategy when you want to update all twins that use this model at once, in addition to all code reacting to the models. If your model update contains a breaking change with the model update, twins will be nonconformant with their models for a short time while you're transitioning them from the old model to the new one, meaning that they won't be able to take any updates until the new model is uploaded and the twins conform to it.

+This operation doesn't overwrite earlier versions of the model, so multiple versions of the model will coexist in your instance until you [remove them](#remove-models). Since the new model version and the old model version coexist, twins can use either the new version of the model or the older version, meaning that uploading a new version of a model doesn't automatically affect existing twins. The existing twins will remain as instances of the old model version, and you can update these twins to the new model version by patching them.

+This version of the model will then be available in your instance to use for digital twins. It doesn't overwrite earlier versions of the model, so multiple versions of the model now coexist in your instance.

+Next, update the twins and relationships in your instance to use the new model version instead of the old.

+>When updating twins, use the same patch to update both the model ID (to the new model version) and any fields that must be altered on the twin to make it conform to the new model.

+You may also need to update relationships and other models in your instance that reference this model, to make them refer to the new model version. You'll need to do another model update operation to achieve this purpose, so return to the beginning of this section and repeat the process for any more models that need updating.

+Now that your new model has been uploaded in place of the old one, the twins in your graph will automatically begin to use the new model definition once the caching in your instance expires and resets. This process may take 10-15 minutes or longer, depending on the size of your graph. After that, new and changed properties on your model should be accessible, and removed properties won't be accessible anymore.

+Next, update the twins and relationships in your instance so their properties match the properties defined by the new model. Before this step is completed, the twins that don't match their model can still be read, but cannot be written to. For more information on the state of twins without a valid model, see [Twins without models](#after-deletion-twins-without-models).

+ - If you've added properties: Updating twins and relationships to have the new values isn't required, since twins missing the new values will still be valid twins. You can patch them however you want to add values for the new properties.

+ - If you've removed properties: It's required to patch twins to remove the properties that are now invalid with the new model.

+ - If you've updated properties: It's required to patch twins to update the values of changed properties to be valid with the new model.

+* Decommissioning: Once a model is decommissioned, you can no longer use it to create new digital twins. Existing digital twins that already use this model aren't affected, so you can still update them with things like property changes and adding or deleting relationships.

+* Deletion: This operation will completely remove the model from the solution. Any twins that were using this model are no longer associated with any valid model, so they're treated as though they don't have a model at all. You can still read these twins, but you can't make any updates on them until they're reassigned to a different model.

+Once a model is deleted, any digital twins that were using the model are now considered to be without a model. There's no query that can give you a list of all the twins in this stateΓÇöalthough you can still query the twins by the deleted model to know what twins are affected.

+Things you can do:

+* Add and delete incoming relationships (as in, other twins can still form relationships to this twin)

+Things you can't do:

+* Edit outgoing relationships (as in, relationships from this twin to other twins)

+In Azure Digital Twins, you can route [event notifications](concepts-event-notifications.md) to downstream services or connected compute resources. This process is done by first setting up *endpoints* that can receive the events. You can then create [event routes](concepts-route-events.md) that specify which events generated by Azure Digital Twins are delivered to which endpoints.

+* You'll need an Azure account, which [can be set up for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F)

+* You'll need an Azure Digital Twins instance in your Azure subscription. If you don't have an instance already, you can create one using the steps in [Set up an instance and authentication](how-to-set-up-instance-portal.md). Have the following values from setup handy to use later in this article:

+> For Event Grid endpoints, only event grid topics are supported. Event grid domains are not supported as endpoints.

+1. From the instance menu, select **Endpoints**. Then from the **Endpoints** page that follows, select **+ Create an endpoint**. Doing so will open the **Create an endpoint** page, where you'll fill in the fields in the following steps.

+1. Finish creating your endpoint by selecting **Save**.

+You can also view the endpoint that was created back on the **Endpoints** page for your Azure Digital Twins instance.

+Now the event grid, event hub, or Service Bus topic is available as an endpoint in Azure Digital Twins, under the name you chose for the endpoint. You'll typically use that name as the target of an event route, which you'll create [later in this article](#create-an-event-route).

+After successfully running these commands, the event grid, event hub, or Service Bus topic will be available as an endpoint in Azure Digital Twins, under the name you supplied with the `--endpoint-name` argument. You'll typically use that name as the target of an event route, which you'll create [later in this article](#create-an-event-route).

+When an endpoint can't deliver an event within a certain time period or after trying to deliver the event a certain number of times, it can send the undelivered event to a storage account. This process is known as *dead-lettering*.

+You'll provide the URI for this container when creating the endpoint later. The dead-letter location will be provided to the endpoint as a container URI with a [SAS token](../storage/common/storage-sas-overview.md). That token needs `write` permission for the destination container within the storage account. The fully formed dead letter SAS URI will be in the format of: `https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>`.

+1. Follow the steps in [Create a storage account](../storage/common/storage-account-create.md?tabs=azure-portal) to create a storage account in your Azure subscription. Make a note of the storage account name to use it later.

+1. Follow the steps in [Create a container](../storage/blobs/storage-quickstart-blobs-portal.md#create-a-container) to create a container within the new storage account. Make a note of the container name to use it later.

+Next, create a SAS token for your storage account that the endpoint can use to access it.

+1. In the storage account page, choose the **Shared access signature** link in the left navigation bar to start setting up the SAS token.

+1. On the **Shared access signature page**, under **Allowed services** and **Allowed resource types**, select whatever settings you want. You'll need to select at least one box in each category. Under **Allowed permissions**, choose **Write** (you can also select other permissions if you want).

+1. When you're finished, select the **Generate SAS and connection string** button to generate the SAS token.

+1. Doing so will generate several SAS and connection string values at the bottom of the same page, underneath the setting selections. Scroll down to view the values, and use the **Copy to clipboard** icon to copy the **SAS token** value. Save it to use later.

+The value for the parameter is the dead letter SAS URI made up of the storage account name, container name, and SAS token that you gathered in the [previous section](#set-up-storage-resources). This parameter creates the endpoint with key-based authentication.

+* Dead letter SAS URI details: storage account name, container name

+To actually send data from Azure Digital Twins to an endpoint, you'll need to define an event route. These routes let developers wire up event flow, throughout the system and to downstream services. A single route can allow multiple notifications and event types to be selected. Read more about event routes in [Endpoints and event routes](concepts-route-events.md).

+Prerequisite: Create endpoints as described earlier in this article before you move on to creating a route. You can continue to create an event route once your endpoints are finished setting up.

+>If you have recently deployed your endpoints, validate that they're finished deploying before attempting to use them for a new event route. If route deployment fails because the endpoints aren't ready, wait a few minutes and try again.

+From the instance menu, select **Event routes**. Then from the **Event routes** page that follows, select **+ Create an event route**.

+On the **Create an event route** page that opens up, choose at minimum:

+* A name for your route in the **Name** field

+* The **Endpoint** you want to use to create the route

+For the route to be enabled, you must also **Add an event route filter** of at least `true`. (Leaving the default value of `false` will create the route, but no events will be sent to it.) To do so, toggle the switch for the **Advanced editor** to enable it, and write `true` in the **Filter** box.

+When finished, select the **Save** button to create your event route.

+As described above, routes have a filter field. If the filter value on your route is `false`, no events will be sent to your endpoint.

+> Filters are case-sensitive and need to match the payload case.

+To add an event filter while you're creating an event route, use the **Add an event route filter** section of the **Create an event route** page.

+To use the basic filters, expand the **Event types** option and select the checkboxes corresponding to the events you want to send to your endpoint.

+To create an event route with advanced filter options, toggle the switch for the **Advanced editor** to enable it. You can then write your own event filters in the **Filter** box:

+| Source | Name of Azure Digital Twins instance | `source = '<host-name>'`| Here are the possible host name values: <br><br> For notifications: `<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net` <br><br> For telemetry: `<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>`|

+| Subject | A description of the event in the context of the event source above | `subject = '<subject>'` | Here are the possible subject values: <br><br>For notifications: The subject is `<twin-ID>` <br> or a URI format for subjects, which are uniquely identified by multiple parts or IDs:<br>`<twin-ID>/relationships/<relationship-ID>`<br><br> For telemetry: The subject is the component path (if the telemetry is emitted from a twin component), such as `comp1.comp2`. If the telemetry isn't emitted from a component, then its subject field is empty. |

+| Data schema | DTDL model ID | `dataschema = '<model-dtmi-ID>'` | For telemetry: The data schema is the model ID of the twin or the component that emits the telemetry. For example, `dtmi:example:com:floor4;2` <br><br>For notifications (create/delete): Data schema can be accessed in the notification body at `$body.$metadata.$model`. <br><br>For notifications (update): Data schema can be accessed in the notification body at `$body.modelId`|

+|String| `STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')` <br> `CONTAINS(subject, '<twin-ID>')`|

+|Integer|`$body.errorCode > 200`|

+|Double|`$body.temperature <= 5.5`|

+|Bool|`$body.poweredOn = true`|

+|Null|`$body.prop != null`|

+From the portal homepage, search for your Azure Digital Twins instance to pull up its details. Select the **Metrics** option from the Azure Digital Twins instance's navigation menu on the left to bring up the **Metrics** page.

+* What are the models uploaded to my instance? How many are there?

+* What are the twins in my instance? How many are there?

+* What's the general shape of the graph in my instance? How many relationships are there?

+* What endpoints do I have in my instance?

+* What routes do I have in my instance? Do they have filters?

+* Where does my instance connect to other Azure services? Some common integration points include:

+* What other personal or company apps do I have that connect to my instance?

+* You can keep the same name for the new instance if it's in a different resource group. If you need to use the same resource group that contains your original instance, your new instance will need its own distinct name.

+* You don't need to recreate the Event Grid, Event Hubs, or Service Bus resource that you're using for the endpoint. For more information, see the [Prerequisites section](how-to-manage-routes.md#prerequisite-create-endpoint-resources) in the endpoint instructions. You just need to recreate the endpoint on the Azure Digital Twins instance.

+* Azure AD app registrations don't need to be recreated. If you're using an [app registration](./how-to-create-app-registration-portal.md) to connect to the Azure Digital Twins APIs, you can reuse the same app registration with your new instance.

+[Models](concepts-models.md) in Azure Digital Twins are defined using the JSON-LD-based Digital Twins Definition language (DTDL). It is recommended to validate your models offline before uploading them to your Azure Digital Twins instance.

+In the folder for the DTDL Validator sample, see the *readme.md* file for instructions on how to package the sample into a self-contained executable.

+The solution described in this article will allow you to automate the process to provision and retire IoT Hub devices in Azure Digital Twins, using Device Provisioning Service.

+For more information about the provision and retire stages, and to better understand the set of general device management stages that are common to all enterprise IoT projects, see the [Device lifecycle section](../iot-hub/iot-hub-device-management-overview.md#device-lifecycle) of IoT Hub's device management documentation.

+* An Azure Digital Twins instance. Follow the instructions in [Set up an instance and authentication](how-to-set-up-instance-portal.md) to create an Azure digital twins instance. Gather the instance's **host name** in the Azure portal ([instructions](how-to-set-up-instance-portal.md#verify-success-and-collect-important-values)).

+* An IoT hub. For instructions, see the "Create an IoT Hub" section of [the IoT Hub quickstart](../iot-hub/quickstart-send-telemetry-cli.md).

+* An [Azure function](../azure-functions/functions-overview.md) that updates digital twin information based on IoT Hub data. Follow the instructions in [Ingest IoT hub data](how-to-ingest-iot-hub-data.md) to create this Azure function. Gather the function **name** to use it in this article.

+This sample also uses a *device simulator* that includes provisioning using the Device Provisioning Service. The device simulator is located here: [Azure Digital Twins and IoT Hub Integration Sample](/samples/azure-samples/digital-twins-iothub-integration/adt-iothub-provision-sample/). Get the sample project on your machine by navigating to the sample link and selecting the **Browse code** button underneath the title. This button will take you to the GitHub repo for the sample, which you can download as a .zip file by selecting the **Code** button and **Download ZIP**.

+You'll need [Node.js](https://nodejs.org/download) installed on your machine. The device simulator is based on Node.js, version 10.0.x or later.

+1. First, create a new function of type **HTTP-trigger** in the function app project in Visual Studio. For instructions on how to create this function, see [Develop Azure Functions using Visual Studio](../azure-functions/functions-develop-vs.md#add-a-function-to-your-project).

+Next, you'll need to create an enrollment in Device Provisioning Service using a *custom allocation function*. To create an enrollment, follow the instructions in the [Create the enrollment](../iot-dps/how-to-use-custom-allocation-policies.md#create-the-enrollment) section of the custom allocation policies article in the Device Provisioning Service documentation.

+* **Select the IoT hubs this group can be assigned to:** Choose your IoT hub name or select the **Link a new IoT hub** button, and choose your IoT hub from the dropdown.

+Next, choose the **Select a new function** button to link your function app to the enrollment group. Then, fill in the following values:

+Next, in your device simulator directory, copy the *.env.template* file to a new file called *.env*, and gather the following values to fill in the settings:

+* PROVISIONING_IDSCOPE: To get this value, navigate to your device provisioning service in the [Azure portal](https://portal.azure.com/), then select **Overview** in the menu options and look for the field **ID Scope**.

+* PROVISIONING_SYMMETRIC_KEY: This environment variable is the primary key for the enrollment you set up earlier. To get this value again, navigate to your device provisioning service in the Azure portal, select **Manage enrollments**, then select the enrollment group that you created earlier and copy the **Primary Key**.

+Now, use the values above to update the *.env* file settings.

+2. Select **Add**. In the **Add SAS Policy** window that opens, enter a policy name of your choice and select the **Listen** checkbox.

+1. First, create a new function of type **Event Hub Trigger** in the function app project in Visual Studio. For instructions on how to create this function, see [Develop Azure Functions using Visual Studio](../azure-functions/functions-develop-vs.md#add-a-function-to-your-project).

+4. In the window **Add an event hub endpoint** that opens, choose the following values:

+1. Navigate to the **Routes** tab and select **Add** to add a route.

+2. In the **Add a route** page that opens, choose the following values:

+ * **Data source**: Choose **Device Lifecycle Events**.

+This article offers query examples and instructions for using the *Azure Digital Twins query language* to query your [twin graph](concepts-twins-graph.md) for information. (For an introduction to the query language, see [Query language](concepts-query-language.md).)

+Get digital twins by properties (including ID and metadata):

+You can also get twins based on whether a certain property is defined. Here's a query that gets twins that have a defined `Location` property:

+This query can help you get twins by their `tag` properties, as described in [Add tags to digital twins](how-to-use-tags.md). Here's a query that gets all twins tagged with `red`:

+You can also get twins based on the type of a property. Here's a query that gets twins whose `Temperature` property is a number:

+It considers [inheritance](concepts-models.md#model-inheritance) and model [versioning](how-to-manage-model.md#update-models), and evaluates to `true` for a given twin if the twin meets either of these conditions:

+* The twin directly implements the model provided to `IS_OF_MODEL()`, and the version number of the model on the twin is greater than or equal to the version number of the provided model

+* The twin implements a model that extends the model provided to `IS_OF_MODEL()`, and the twin's extended model version number is greater than or equal to the version number of the provided model

+So for example, if you query for twins of the model `dtmi:example:widget;4`, the query will return all twins based on version 4 or greater of the widget model, and also twins based on version 4 or greater of any models that inherit from widget.

+When querying based on digital twins' relationships, the Azure Digital Twins query language has a special syntax.

+Here's a sample relationship-based query. This code snippet selects all digital twins with an `ID` property of `ABC`, and all digital twins related to these digital twins via a `contains` relationship.

+The type of the relationship (`contains` in the example above) is indicated using the relationship's `name` field from its [DTDL definition](concepts-models.md#basic-relationship-example).

+For instance, you can start with a source twin and follow its relationships to find the target twins of the relationships. Here's an example of a query that finds the target twins of the `feeds` relationships coming from the twin source-twin.

+You can also start with the target of the relationship and trace the relationship back to find the source twin. Here's an example of a query that finds the source twin of a `feeds` relationship to the twin target-twin.

+Similarly to the way digital twins have properties described via DTDL, relationships can also have properties. You can query twins based on the properties of their relationships.

+As an example, consider a `servicedBy` relationship that has a `reportedCondition` property. In the below query, this relationship is given an alias of `R` to reference its property.

+In the example above, note how `reportedCondition` is a property of the `servicedBy` relationship itself (NOT of some digital twin that has a `servicedBy` relationship).

+Here's an example of a query that uses projection to return twins and relationships. The following query projects the Consumer, Factory, and Edge from a scenario where a Factory with an ID of `ABC` is related to the Consumer through a relationship of `Factory.customer`, and that relationship is presented as the `Edge`.

+You can also use projection to return a property of a twin. The following query projects the `Name` property of the Consumers that are related to the Factory with an ID of `ABC` through a relationship of `Factory.customer`.

+You can also use projection to return a property of a relationship. Like in the previous example, the following query projects the `Name` property of the Consumers related to the Factory with an ID of `ABC` through a relationship of `Factory.customer`; but now it also returns two properties of that relationship, `prop1` and `prop2`. It does this by naming the relationship `Edge` and gathering its properties.

+Here's a similar query that queries the same set as above, but projects only the `Consumer.name` property as `consumerName`, and projects the complete Factory as a twin.

+You can combine any of the above types of query using combination operators to include more detail in a single query. Here are some other examples of compound queries that query for more than one type of twin descriptor at once.

+* Get twins that have a relationship named `Contains` with another twin that has an ID of `id1`

+You can enable system-managed identities for an Azure Digital Twins instance in two different ways:

+- Enable it as part of the instance's initial setup.

+- Enable it later on an instance that already exists.

+The command to enable managed identity is the same as the command to create an instance with a system managed identity. All that changes is the value of the instance name parameter:

+To disable managed identity on an instance where it's currently enabled, use the following similar command to set `--assign-identity` to `false`.

+This article shows how to send events from twin to twin, so that when one digital twin in the graph is updated, related twins in the graph that are affected by this information can also update. This event handling will help you create a fully connected Azure Digital Twins graph, where data that arrives into Azure Digital Twins from external sources like IoT Hub is propagated through the entire graph.

+This article uses Visual Studio. You can download the latest version from [Visual Studio Downloads](https://visualstudio.microsoft.com/downloads/).

+To set up twin-to-twin handling, you'll need an Azure Digital Twins instance to work with. For instructions on how to create an instance, see [Set up an Azure Digital Twins instance and authentication](./how-to-set-up-instance-portal.md). The instance should contain at least two twins that you want to send data between.

+To set up twin-to-twin event handling, start by creating an *endpoint* in Azure Digital Twins and a *route* to that endpoint. Twins undergoing an update will use the route to send information about their update events to the endpoint (where Event Grid can pick them up later and pass them to an Azure function for processing).

+Before your function can access Azure Digital Twins, it needs some information about the instance and permission to access it. In this section, you'll assign an access role for the function and configure the application settings so that it can find and access the instance.

+To subscribe your Azure function, you'll create an *Event Grid subscription* that sends data from the Event Grid topic that you created earlier to your Azure function.

+This article covers the steps to set up a new Azure Digital Twins instance, including creating the instance and setting up authentication. After completing this article, you'll have an Azure Digital Twins instance ready to start programming against.

+In this section, you will create a new instance of Azure Digital Twins using the CLI command. You will need to provide:

+> 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).

+> Use the [Azure portal page of Azure Active Directory users](https://portal.azure.com/#blade/Microsoft_AAD_IAM/UsersManagementMenuBlade/AllUsers) to select the user account and open its details. Copy the user's **Object ID**:

+> Then, repeat the role assignment list command using the user's Object ID for the `assignee` parameter above.

+This article covers the steps to set up a new Azure Digital Twins instance, including creating the instance and setting up authentication. After completing this article, you'll have an Azure Digital Twins instance ready to start programming against.

+ - **Resource group**: A resource group in which to deploy the instance. If you don't already have an existing resource group in mind, you can create one here by selecting the **Create new** link and entering a name for a new resource group

+After finishing your instance setup by selecting **Create**, you can view the status of your instance's deployment in your Azure notifications along the portal icon bar. The notification will indicate when deployment has succeeded, at which point you can select the **Go to resource** button to view your created instance.

+From the instance's **Overview** page, note its **Name**, **Resource group**, and **Host name**. These values are all important and you may need to use them as you continue working with your Azure Digital Twins instance. If other users will be programming against the instance, you should share these values with them.

+You can view the role assignment you've set up under **Access control (IAM) > Role assignments**. The user should show up in the list with a role of **Azure Digital Twins Data Owner**.

+This article covers the steps to set up a new Azure Digital Twins instance, including creating the instance and setting up authentication. After completing this article, you'll have an Azure Digital Twins instance ready to start programming against.

+1. If you have multiple Azure subscriptions, choose the appropriate subscription in which the resources should be billed. Select a specific subscription using the [Set-AzContext](/powershell/module/az.accounts/set-azcontext) cmdlet.

+1. If this is your first time using Azure Digital Twins with this subscription, you must register the `Microsoft.DigitalTwins` resource provider. (If you're not sure, it's ok to run it again even if you've done it sometime in the past.)

+1. Use the following command to install the `Az.DigitalTwins` PowerShell module.

+In this section, you'll create a new instance of Azure Digital Twins using Azure PowerShell. You'll need to provide:

+* An [Azure resource group](../azure-resource-manager/management/overview.md) where the instance will be deployed. If you don't already have an existing resource group, you can create one using the [New-AzResourceGroup](/powershell/module/az.resources/new-azresourcegroup) cmdlet:

+* 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).

+* A name for your instance. The name of the new instance must be unique within the region for your subscription. If your subscription has another Azure Digital Twins instance in the region that's already using the specified name, you'll be asked to pick a different name.

+If the instance was created successfully, the result looks similar to the following output containing information about the resource you've created:

+Note the Azure Digital Twins instance's **host name**, **name**, and **resource group**. These are important values that you may need 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.

+You now have an Azure Digital Twins instance ready to go. Next, you'll give the appropriate Azure user permissions to manage it.

+To give a user permissions to manage an Azure Digital Twins instance, you must assign them the **Azure Digital Twins Data Owner** role within the instance.

+First, determine the Object Id for the Azure AD account of the user that should be assigned the role. You can find this value using the [Get-AzAdUser](/powershell/module/az.resources/get-azaduser) cmdlet, by passing in the user principal name on the Azure AD account to retrieve their Object Id (and other user information). In most cases, the user principal name will match the user's email on the Azure AD account.

+Next, use the Object Id in the following command to assign the role. The command also requires you to enter the same subscription ID, resource group name, and Azure Digital Twins instance name that you chose earlier when creating the instance. The command must be run by a user with [sufficient permissions](#prerequisites-permission-requirements) in the Azure subscription.

+>This tool is currently in public preview.

+Doing so will bring up the **Azure Digital Twins URL modal**, where you can enter the host name of another Azure Digital Twins instance after the `https://` prefix to connect to that instance.

+>At this time, the ability to switch contexts within the app isn't available for personal Microsoft Accounts (MSA). MSA users will need to access the explorer from the chosen instance in the Azure portal, or may connect to a certain instance through a [direct link to the environment](#link-to-your-environment).

+To indicate which types of relationships to follow when expanding, use the **Expansion Direction** button. Doing so allows you to select from incoming, outgoing, or both incoming and outgoing relationships.

+* The *custom Excel-based format* described in the rest of this section. This format allows you to upload twins and relationships.

+* The *JSON-based format* generated on [graph export](#export-graph-and-models). This format can contain twins, relationships, and/or models.

+| (Optional)<br>The DTMI model ID for a twin that should be created.<br><br>You can leave this column blank for a row if you want that row to create only a relationship (no twins). | (Required)<br>The unique ID for a twin.<br><br>If a new twin is being created in this row, this value will be the ID of the new twin.<br>If there's relationship information in the row, this ID will be used as the target of the relationship. | (Optional)<br>The ID of a twin that should be the source twin for a new relationship.<br><br>You can leave this column blank for a row if you want that row to create only a twin (no relationships). | (Optional)<br>The name for the new relationship to create. The relationship direction will be from the twin in column C to the twin in column B. | (Optional)<br>A JSON string containing property settings for the twin to be created. The properties must match the ones defined in the model from column A. |

+To share your environment, you can send a link to the recipient that will open an Azure Digital Twins Explorer window connected to your instance. Use the link below and replace the placeholders for your *tenant ID* and the *host name* of your Azure Digital Twins instance.

+> The value for the host name placeholder is not preceded by the `https://` prefix here.

+* **Eager Loading**: When a query returns twins that have relationships to other twins that aren't included in the query results, this feature will load the "missing" twins before rendering the graph.

+You can customize the panel layout by editing the positions of the panels that make up Azure Digital Twins Explorer (Query Explorer, Twins, Models, Twin Graph, Model Graph). To move a panel to a different location, click and hold the panel name, and drag it to its new desired position.

+Azure Digital Twins has two sets of APIs that you can work with: data plane and control plane. For more about the difference between these API sets, see [Azure Digital Twins APIs and SDKs](concepts-apis-sdks.md). This article contains information for both API sets.

+ To get a token to use with the data plane APIs, use the following static value for the token context: `0b07f429-9f4b-4714-9392-cc5e8e80c8b0`. This is the resource ID for the Azure Digital Twins service endpoint.

+ To get a token to use with the control plane APIs, use the following value for the token context: `https://management.azure.com/`.

+ > If you need to access your Azure Digital Twins instance using a service principal or user account that belongs to a different Azure Active Directory tenant from the instance, you'll need to request a token from the Azure Digital Twins instance's "home" tenant. For more information on this process, see [Write app authentication code](how-to-authenticate-client.md#authenticate-across-tenants).

+Requests in Postman are saved in *collections* (groups of requests). When you create a collection to group your requests, you can apply common settings to many requests at once. This can greatly simplify authorization if you plan to create more than one request against the Azure Digital Twins APIs, as you only have to configure these details once for the entire collection.

+1. In the **Import** window that follows, select **Upload Files** and navigate to the collection file on your machine that you created earlier. Select Open.

+Follow these steps to add a bearer token to the collection for authorization. This is where you'll use the token value you gathered in the [Get bearer token](#get-bearer-token) section in order to use it for all API requests in your collection.

+If you're making a [data plane](concepts-apis-sdks.md#overview-data-plane-apis) collection, help the collection connect easily to your Azure Digital Twins resources by setting some variables provided with the collections. When many requests in a collection require the same value (like the host name of your Azure Digital Twins instance), you can store the value in a variable that applies to every request in the collection. Both of the downloadable collections for Azure Digital Twins come with pre-created variables that you can set at the collection level.

+Follow these steps to add a bearer token to the collection for authorization. This is where you'll use the token value you gathered in the [Get bearer token](#get-bearer-token) section in order to use it for all API requests in your collection.

+1. In Postman, set the type for the request and enter the request URL, filling in placeholders in the URL as required. This is where you will use your instance's host name from the [Prerequisites section](#prerequisites).

+A *marker tag* is a simple string that is used to mark or categorize a digital twin, such as "blue" or "red". This string is the tag's name, and marker tags have no meaningful valueΓÇöthe tag is significant just by its presence (or absence).

+A *value tag* is a key-value pair that is used to give each tag a value, such as `"color": "blue"` or `"color": "red"`. Once a value tag is created, it can also be used as a marker tag by ignoring the tag's value.

+*Azure Digital Twins* is a platform as a service (PaaS) offering that enables the creation of twin graphs based on digital models of entire environments, which could be buildings, factories, farms, energy networks, railways, stadiums, and moreΓÇöeven entire cities. These digital models can be used to gain insights that drive better products, optimized operations, reduced costs, and breakthrough customer experiences.

+> IoT Hub device twins differ from digital twins in the Azure Digital Twins service. While *IoT Hub device twins* are maintained by your IoT hub for each IoT device that you connect to it, *digital twins* can be representations of anything defined by digital models and instantiated within Azure Digital Twins.

+You can think of these model definitions as a specialized vocabulary to describe your business. For a building management solution, for example, you might define models such as Building, Floor, and Elevator. You can then create digital twins based on these models to represent your specific environment.

+*Models* are defined in a JSON-like language called [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/dtdlv2.md), and they describe twins by their state properties, telemetry events, commands, components, and relationships.

+* Models define semantic *relationships* between your entities so that you can connect your twins into a graph that reflects their interactions. You can think of the models as nouns in a description of your world, and the relationships as verbs.

+* You can also specialize twins using model *inheritance*. One model can inherit from another.

+Digital models in Azure Digital Twins are live, up-to-date representations of the real world. Using the relationships in your custom DTDL models, you'll connect twins into a live graph representing your environment.

+Azure Digital Twins provides a rich event system to keep that graph current with data processing and business logic. You can connect external compute resources, such as [Azure Functions](../azure-functions/functions-overview.md), to drive this data processing in flexible, customized ways.

+You can also extract insights from the live execution environment, using Azure Digital Twins' powerful *query APIΓÇï*. The API lets you query with extensive search conditions, including property values, relationships, relationship properties, model information, and more. You can also combine queries, gathering a broad range of insights about your environment and answering custom questions that are important to you.

+The data in your Azure Digital Twins model can be routed to downstream Azure services for more analytics or storage. This functionality is provided through *event routes*, which use [Event Hubs](../event-hubs/event-hubs-about.md), [Event Grid](../event-grid/overview.md), or [Service Bus](../service-bus-messaging/service-bus-messaging-overview.md) to drive your data flows.

+You can read about the service limits of Azure Digital Twins in the [Azure Digital Twins service limits article](reference-service-limits.md). This resource can be useful while working with the service to understand the service's functional and rate limitations, as well as which limits can be adjusted if necessary.

+You can view a list of common IoT terms and their uses across the Azure IoT services, including Azure Digital Twins, in the [Azure IoT Glossary](../iot-fundamentals/iot-glossary.md?toc=/azure/digital-twins/toc.json&bc=/azure/digital-twins/breadcrumb/toc.json). This resource may be a useful reference while you get started with Azure Digital Twins and building an IoT solution.

+With Azure Digital Twins, you can create and interact with live models of your real-world environments, which can be part of wider IoT solutions. First, you model individual elements as digital twins. Then you connect them into a knowledge graph that can respond to live events and be queried for information.

+* [Room.json](https://raw.githubusercontent.com/Azure-Samples/digital-twins-explorer/main/client/examples/Room.json): This is a model file representing a room in a building. Navigate to the link, right-click anywhere on the screen, and select **Save as** in your browser's right-click menu. Use the following Save As window to save the file somewhere on your machine with the name *Room.json*.

+* [Floor.json](https://raw.githubusercontent.com/Azure-Samples/digital-twins-explorer/main/client/examples/Floor.json): This is a model file representing a floor in a building. Navigate to the link, right-click anywhere on the screen, and select **Save as** in your browser's right-click menu. Use the following Save As window to save the file to the same location as Room.json, under the name *Floor.json*.

+* [buildingScenario.xlsx](https://github.com/Azure-Samples/digital-twins-explorer/raw/main/client/examples/buildingScenario.xlsx): This file contains a graph of room and floor twins, and relationships between them. Depending on your browser settings, selecting this link may download the *buildingScenario.xlsx* file automatically to your default download location, or it may open the file in your browser with an option to download. Here is what that download option looks like in Microsoft Edge:

+Each model is written in a language like JSON-LD called Digital Twin Definition Language (DTDL). Each model describes a single type of entity in terms of its properties, telemetry, relationships, and components. Later, you'll use these models as the basis for digital twins that represent specific instances of these types.

+1. In the Open window that appears, navigate to the folder containing the *Room.json* and *Floor.json* files that you downloaded earlier.

+1. Select *Room.json* and *Floor.json*, and select **Open** to upload them both.

+Digital twins represent the actual entities within your business environment. They can be things like sensors on a farm, lights in a car, orΓÇöin this quickstartΓÇörooms on a building floor. You can create many twins of any given model type, such as multiple rooms that all use the Room model. You connect them with relationships into a *twin graph* that represents the full environment.

+2. In the Open window, navigate to the *buildingScenario.xlsx* file you downloaded earlier. This file contains a description of the sample graph. Select **Open**.

+One way to query the twins in your graph is by their properties. Querying based on properties can help answer a variety of questions. For example, you can find outliers in your environment that might need attention.

+The properties in this list are editable. Select the temperature value of **70** to enable entering a new value. Enter *76*, and select the **Save** icon to update the temperature to 76.

+* If you plan to continue to the Azure Digital Twins tutorials, you can reuse the instance in this quickstart for those articles, and you don't need to remove it.

+This document contains reference information on the *FROM clause* for the [Azure Digital Twins query language](concepts-query-language.md).

+The following query shows an example of what can't be done as per this limitation.

+This document contains reference information on the *JOIN clause* for the [Azure Digital Twins query language](concepts-query-language.md).

+Because relationships in Azure Digital Twins are part of digital twins, not independent entities, the `RELATED` keyword is used in `JOIN` queries to reference the set of relationships of a certain type from the twin collection (the type is specified using the relationship's `name` field from its [DTDL definition](concepts-models.md#basic-relationship-example)). The set of relationships can be assigned a collection name within the query.

+The following query selects all digital twins that are related to the twin with an ID of `ABC` through a `contains` relationship.

+This document contains reference information on the *MATCH clause* for the [Azure Digital Twins query language](concepts-query-language.md). This clause is currently in preview.

+The relationship condition can include one or more of the following details:

+The query specifies a [relationship direction](#specify-relationship-direction), and searches for Building and Sensor twins where...

+* the Sensor is targeted by any relationship from a Building twin with a `$dtId` of Building21, and

+* the Sensor has a temperature above 50.

+The Building and Sensor are both included in the query result.

+For a *left-to-right* relationship, use the following syntax.

+For a *right-to-left* relationship, use the following syntax.

+For a *non-directional* relationship, use the following syntax. This will not specify a direction for the relationship, so relationships of any direction will be included in the result.

+The first example shows a left-to-right directional traversal. This query finds twins Room and Factory where...

+* Room targets Factory (with any name of relationship)

+* Room has a temperature value that's greater than 50

+* Factory has a `$dtId` of 'ABC'

+The following example shows a right-to-left directional traversal. This query looks similar to the one above, but the direction of the relationship between Room and Factory is reversed. This query finds twins Room and Factory where...

+* Factory targets Room (with any name of relationship)

+* Factory has a `$dtId` of 'ABC'

+* Room has a temperature value that's greater than 50

+The following example shows a non-directional traversal. This query finds twins Room and Factory where...

+* Room and Factory share any name of relationship, going in either direction

+* Factory has a `$dtId` of 'ABC'

+* Room has a humidity value that's greater than 70

+For a single name, use the following syntax. The placeholder values that should be replaced with your values are `twin_1`, `relationship_name`, and `twin_2`.

+For multiple possible names use the following syntax. The placeholder values that should be replaced with your values are `twin_1`, `relationship_name_option_1`, `relationship_name_option_2`, `twin_2`, and the note to continue the pattern as needed for the number of relationship names you want to enter.

+(Default) To leave name unspecified, leave the brackets empty of name information, like this:

+The following example shows a single relationship name. This query finds twins Building and Sensor where...

+* Building has a 'contains' relationship to Sensor (going in either direction)

+* Building has a `$dtId` of 'Seattle21'

+The following example shows multiple possible relationship names. This query looks similar to the one above, but there are multiple possible relationship names that are included in the result. This query finds twins Building and Sensor where...

+* Building has either a 'contains' or 'isAssociatedWith' relationship to Sensor (going in either direction)

+* Building has a `$dtId` of 'Seattle21'

+The following example has no specified relationship name. As a result, relationships with any name will be included in the query result. This query finds twins Building and Sensor where...

+* Building has a relationship to Sensor with any name (and going in either direction)

+* Building has a `$dtId` of 'Seattle21'

+To specify an exact number of hops, use the following syntax. The placeholder values that should be replaced with your values are `twin_1`, `number_of_hops`, and `twin_2`.

+To specify a range of hops, use the following syntax. The placeholder values that should be replaced with your values are `twin_1`, `starting_limit`, `ending_limit` and `twin_2`. The starting limit isn't included in the range, while the ending limit is included.

+(Default) To default to one hop, leave the brackets empty of hop information, like this:

+The following example specifies an exact number of hops. The query will only return relationships between twins Floor and Room that are exactly 3 hops.

+The following example specifies a range of hops. The query will return relationships between twins Floor and Room that are between 1 and 3 hops (meaning the number of hops is either 2 or 3).

+You can also show a range by providing only one boundary. In the following example, the query will return relationships between twins Floor and Room that are at most 2 hops (meaning the number of hops is either 1 or 2).

+The following example has no specified number of hops, so will default to one hop between twins Floor and Room.

+The following example assigns a query variable 'r' to the relationship. Later, in the `WHERE` clause, it uses the variable to specify that the relationship Rel should have a name property with a value of 'child'.

+In a single query, you can combine [relationship direction](#specify-relationship-direction), [relationship name](#specify-number-of-hops), and one of either [number of hops](#specify-number-of-hops) or [a query variable assignment](#assign-query-variable-to-relationship-and-specify-relationship-properties).

+To specify relationship direction, relationship name, and number of hops within a single query, use the following syntax within the relationship condition. The placeholder values that should be replaced with your values are `twin_1` and `twin_2`, `optional_left_angle_bracket` and `optional_right_angle_bracket`, `relationship_name(s)`, and `number_of_hops`.

+To specify relationship direction, relationship name, and a query variable for the relationship within a single query, use the following syntax within the relationship condition. The placeholder values that should be replaced with your values are `twin_1` and `twin_2`, `optional_left_angle_bracket` and `optional_right_angle_bracket`, `relationship_variable`, and `relationship_name(s)`.

+You can chain multiple relationship conditions together, like this. The placeholder values that should be replaced with your values are `twin_1`, all instances of `relationship_condition`, and `twin_2`.

+Here's an example that combines relationship direction, relationship name, and number of hops The following query finds twins Floor and Room where the relationship between Floor and Room meets these conditions:

+* the relationship is left-to-right, with Floor as the source and Room as the target

+The query also specifies that twin Floor has a `$dtId` of 'thermostat-15'.

+Here's an example that combines relationship direction, relationship name, and a named query variable for the relationship. The following query finds twins Floor and Room where the relationship between Floor and Room is assigned to a query variable `r` and meets these conditions:

+* the relationship is left-to-right, with Floor as the source and Room as the target

+* the relationship, which is given a query variable `r`, has a length property equal to 10

+The query also specifies that twin Floor has a `$dtId` of 'thermostat-15'.

+The following example illustrates *chained* relationship conditions. The query finds twins Floor, Cafe, and Room, where...

+* the relationship between Floor and Room meets these conditions:

+ - the relationship is left-to-right, with Floor as the source and Cafe as the target

+ - the relationship, which is given query variable `r`, has a length property equal to 10

+* the relationship between Cafe and Room meets these conditions:

+ - the relationship is right-to-left, with Room as the source and Cafe as the target

+The query also specifies that twin Floor has a `$dtId` of 'thermostat-15' and twin Cafe has a temperature of 55.

+You can also use chained relationship conditions to express bi-directional relationships. The following query finds twins Floor, Room, and Building, where...

+* the relationship between Building and Floor meets these conditions:

+ - the relationship is left-to-right, with Building as the source and Floor as the target

+ - the relationship is given a query variable `r1`

+* the relationship between Floor and Room meets these conditions:

+ - the relationship is right-to-left, with Room as the source and Floor as the target

+ - the relationship is given a query variable `r2`

+The query also specifies that twin Building has a `$dtId` of 'building-3' and Room has a temperature greater than 50.

+This document contains reference information on the *SELECT clause* for the [Azure Digital Twins query language](concepts-query-language.md).

+This document contains reference information on the *WHERE clause* for the [Azure Digital Twins query language](concepts-query-language.md).

+This document contains reference information on *functions* for the [Azure Digital Twins query language](concepts-query-language.md).

+The following query returns all digital twins who have a defined `Location` property.

+This document contains reference information on *operators* for the [Azure Digital Twins query language](concepts-query-language.md).

+This document contains the list of *reserved keywords* in the [Azure Digital Twins query language](concepts-query-language.md). These words cannot be used as identifiers in queries unless they are [escaped in double square brackets](#escaping-reserved-keywords-in-queries).

+> Some areas of this service have adjustable limits. This is represented in the tables below with the **Adjustable?** column. When the limit can be adjusted, the **Adjustable?** value is **Yes**.

+* Use retry logic. The [Azure Digital Twins SDKs](concepts-apis-sdks.md) implement retry logic for failed requests, so if you're working with a provided SDK, this functionality is already built-in. Otherwise, consider implementing retry logic in your own application. The service sends back a `Retry-After` header in the failure response, which you can use to determine how long to wait before retrying.

+* Use thresholds and notifications to warn about approaching limits. Some of the service limits for Azure Digital Twins have corresponding [metrics](troubleshoot-metrics.md) that can be used to track usage in these areas. To configure thresholds and set up an alert on any metric when a threshold is approached, see the instructions in [Troubleshooting: Alerts](troubleshoot-alerts.md). To set up notifications for other limits where metrics aren't provided, consider implementing this logic in your own application code.

+* Deploy at scale across multiple instances. Avoid having a single point of failure. Instead of one large graph for your entire deployment, consider sectioning out subsets of twins logically (like by region or tenant) across multiple instances.

+In this article, you'll learn how to set up *alerts* in the [Azure portal](https://portal.azure.com). These alerts will notify you when configurable conditions you've defined based on the metrics of your Azure Digital Twins instance are met, allowing you to take important actions.

+Alerts proactively notify you when important conditions are found in your metrics data. They allow you to identify and address issues before the users of your system notice them. You can read more about alerts in [Overview of alerts in Microsoft Azure](../azure-monitor/alerts/alerts-overview.md).

+3. On the **Create alert rule** page that follows, you can follow the prompts to define conditions, actions to be triggered, and alert details.

+ - You can select the **Enable alert rule upon creation** checkbox if you want the alert to become active as soon as it's created.

+ - You can select the **Automatically resolve alerts** checkbox if you want to resolve the alert when the condition isn't met anymore.

+ - This section is also where you select a **subscription**, **resource group**, and **Severity** level.

+4. Select the **Create alert rule** button to create your alert rule.

+Here's an excerpt from the **Select condition** process illustrating what types of alert signals are available for Azure Digital Twins. On this page you can filter the type of signal, and select the signal that you want from a list.

+After setting up alerts, they'll show up back on the **Alerts** page for your instance.

+Azure Digital Twins can collect *logs* for your service instance to monitor its performance, access, and other data. You can use these logs to get an idea of what is happening in your Azure Digital Twins instance, and analyze root causes on issues without needing to contact Azure support.

+This article also contains information about all the log categories that Azure Digital Twins can collect, and their schemas.

+After configuring storage details of your Azure Digital Twins logs, you can write *custom queries* for them to generate insights and troubleshoot issues. The service also provides a few example queries that can help you get started, by addressing common questions that customers may have about their instances.

+2. Select **Logs** from the menu to open the log query page. The page opens to a window called **Queries**.

+ You can also close the **Queries** window without running anything to go straight to the query editor page, where you can write or edit custom query code.

+3. After exiting the **Queries** window, you'll see the main query editor page. Here you can view and edit the text of the example queries, or write your own queries from scratch.

+ - The **Tables** tab shows the different Azure Digital Twins [log categories](#log-categories) that are available to use in your queries.

+ - The **Queries** tab contains the example queries that you can load into the editor.

+ - The **Filter** tab lets you customize a filtered view of the data that the query returns.

+This log schema is consistent for `ADTDigitalTwinsOperation`, `ADTModelsOperation`, `ADTQueryOperation`. The same schema is also used for `ADTEventRoutesOperation`, except the `Microsoft.DigitalTwins/eventroutes/action` operation name (for more information about that schema, see the next section, [Egress log schemas](#egress-log-schemas)).

+Here's an example JSON body for an `ADTEventRoutesOperation` that isn't of `Microsoft.DigitalTwins/eventroutes/action` type (for more information about that schema, see the next section, [Egress log schemas](#egress-log-schemas)).

+Most often, this error indicates that your Azure role-based access control (Azure RBAC) permissions for the service aren't set up correctly. Many actions for an Azure Digital Twins instance require you to have the Azure Digital Twins Data Owner role on the instance you are trying to manage.

+If you don't have this role assignment, someone with an Owner role in your Azure subscription should run the following command to give your Azure user the Azure Digital Twins Data Owner role on the Azure Digital Twins instance.

+For more information about this role requirement and the assignment process, see [Set up your user's access permissions](how-to-set-up-instance-CLI.md#set-up-user-access-permissions).

+If you have this role assignment already and you're using an Azure AD app registration to authenticate a client app, you can continue to the next solution if this solution didn't resolve the 403 issue.

+To check whether the permissions have been configured correctly, navigate to the [Azure AD app registration overview page](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps) in the Azure portal. You can get to this page yourself by searching for *app registrations* in the portal search bar.

+You can resolve this issue by having each federated identity from another tenant request a token from the Azure Digital Twins instance's "home" tenant.

+This error might occur if your Azure account does not have the required Azure role-based access control (Azure RBAC) permissions set on your Azure Digital Twins instance. In order to access data in your instance, you must have the *Azure Digital Twins Data Reader* or *Azure Digital Twins Data Owner* role on the instance you are trying to read or manage, respectively.

+Verify that your Azure user has the *Azure Digital Twins Data Reader* role on the Azure Digital Twins instance if you're just trying to read its data, or the *Azure Digital Twins Data Owner* role on the instance if you're trying to manage its data.

+If you do not have this role assignment, someone with an Owner role in your Azure subscription should run the following command to give your Azure user the appropriate role on the Azure Digital Twins instance.

+If you're an Owner on the subscription, you can run this command yourself. If you're not, contact an Owner to run this command on your behalf. The role name is either *Azure Digital Twins Data Owner* for edit access or *Azure Digital Twins Data Reader* for read access.

+For more details about this role requirement and the assignment process, see [Set up your user's access permissions](how-to-set-up-instance-CLI.md#set-up-user-access-permissions).

+**Issue description:** Commands in Cloud Shell running at *https://shell.azure.com* may intermittently fail with the error "400 Client Error: Bad Request for url: `http://localhost:50342/oauth2/token`", followed by full stack trace.

+**Issue description:** When writing authentication code in your Azure Digital Twins applications using version 1.2.0 of the [Azure.Identity](/dotnet/api/azure.identity?view=azure-dotnet&preserve-view=true) library, you may experience issues with the [InteractiveBrowserCredential](/dotnet/api/azure.identity.interactivebrowsercredential?view=azure-dotnet&preserve-view=true) method. This issue presents as an error response of "Azure.Identity.AuthenticationFailedException" when trying to authenticate in a browser window. The browser window may fail to start up completely, or appear to authenticate the user successfully, while the client application still fails with the error.

+| The&nbsp;affected&nbsp;method&nbsp;is&nbsp;used&nbsp;in&nbsp;the&nbsp;following articles:<br><br>[Code a client app](tutorial-code.md)<br><br>[Write app authentication code](how-to-authenticate-client.md)<br><br>[Azure Digital Twins APIs and SDKs](concepts-apis-sdks.md) | Some users have had this issue with version 1.2.0 of the `Azure.Identity` library. | To resolve, update your applications to use a [later version](https://www.nuget.org/packages/Azure.Identity) of `Azure.Identity`. After updating the library version, the browser should load and authenticate as expected. |

+**Issue description:** When writing authentication code using version 1.3.0 of the [Azure.Identity](/dotnet/api/azure.identity?view=azure-dotnet&preserve-view=true) library, some users have experienced issues with the [DefaultAzureCredential](/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet&preserve-view=true) method used in many samples throughout these Azure Digital Twins docs. This issue presents as an error response of "Azure.Identity.AuthenticationFailedException: SharedTokenCacheCredential authentication failed" when the code tries to authenticate.

+| `DefaultAzureCredential` is used in most of the documentation examples for this service that include authentication. If you're writing authentication code using `DefaultAzureCredential` with version 1.3.0 of the `Azure.Identity` library and seeing this error message, this issue affects you. | It's likely a result of some configuration issue with the `Azure.Identity` library and `DefaultAzureCredential`, its authentication class. This class is a wrapper containing several credential types that are tried in order. The issue may occur when the authentication flow reaches the `SharedTokenCacheCredential` type. | One strategy to resolve this is to exclude `SharedTokenCacheCredential` from your credential, as described in this [DefaultAzureCredential issue](https://github.com/Azure/azure-sdk/issues/1970) that is currently open against `Azure.Identity`. You can exclude `SharedTokenCacheCredential` from your credential by instantiating the `DefaultAzureCredential` class using the following optional parameter: `new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });`<br>Another option is to change your application to use an earlier version of `Azure.Identity`, such as [version 1.2.3](https://www.nuget.org/packages/Azure.Identity/1.2.3). Using an earlier version has no functional impact to Azure Digital Twins, which makes it an accepted solution. |

+[Azure Service Health](../service-health/index.yml) is a suite of experiences that can help you diagnose and get support for service problems that affect your Azure resources. It contains resource health, service health, and status information, and reports on both current and past health information.

+* .NET Core 3.1 on your development machine. You can download this version of the .NET Core SDK for multiple platforms from [Download .NET Core 3.1](https://dotnet.microsoft.com/download/dotnet-core/3.1).

+Once in the project directory, create an empty .NET console app project. In the command window, you can run the following command to create a minimal C# project for the console:

+Next, add two dependencies to your project that will be needed to work with Azure Digital Twins. The first is the package for the [Azure Digital Twins SDK for .NET](/dotnet/api/overview/azure/digitaltwins/client?view=azure-dotnet&preserve-view=true), the second provides tools to help with authentication against Azure.

+To authenticate, you need the host name of your Azure Digital Twins instance.

+Set the value of `adtInstanceUrl` to your Azure Digital Twins instance host name.

+* If no error occurs, the program will print: "Service client created - ready to go".

+Azure Digital Twins has no intrinsic domain vocabulary. The types of elements in your environment that you can represent in Azure Digital Twins are defined by you, using *models*. [Models](concepts-models.md) are similar to classes in object-oriented programming languages; they provide user-defined templates for [digital twins](concepts-twins-graph.md) to follow and instantiate later. They're written in a JSON-like language called *Digital Twins Definition Language (DTDL)*.

+> If you're using Visual Studio for this tutorial, you may want to select the newly-created JSON file and set the **Copy to Output Directory** property in the Property inspector to **Copy if Newer** or **Copy Always**. This will enable Visual Studio to find the JSON file with the default path when you run the program with F5 during the rest of the tutorial.

+Before you run the program again to test this new code, recall that the last time you ran the program, you uploaded your model already. Azure Digital Twins won't let you upload the same model twice, so if you attempt to upload the same model again, the program should throw an exception.

+Now that you've uploaded a model to Azure Digital Twins, you can use this model definition to create *digital twins*. [Digital twins](concepts-twins-graph.md) are instances of a model, and represent the entities within your business environmentΓÇöthings like sensors on a farm, rooms in a building, or lights in a car. This section creates a few digital twins based on the model you uploaded earlier.

+Next, you can create *relationships* between the twins you've created, to connect them into a *twin graph*. [Twin graphs](concepts-twins-graph.md) are used to represent your entire environment.

+Add a new static method to the `Program` class, underneath the `Main` method (the code now has two methods):

+Add the following new method to the `Program` class:

+* If you plan to continue to the next tutorial, the instance used in this tutorial can be reused in the next one. You can keep the Azure Digital Twins resources you set up here and skip the rest of this section.

+In this tutorial, you'll build a graph in Azure Digital Twins using models, twins, and relationships. The tool for this tutorial is the sample command-line client application for interacting with an Azure Digital Twins instance. The client app is similar to the one written in [Code a client app](tutorial-code.md).

+Models are similar to classes in object-oriented programming languages; they provide user-defined templates for [digital twins](concepts-twins-graph.md) to follow and instantiate later. They're written in a JSON-like language called *Digital Twins Definition Language (DTDL)*, and can define a twin's properties, telemetry, relationships, and components.

+> DTDL also allows for the definition of commands on digital twins. However, commands are not currently supported in the Azure Digital Twins service.

+In your Visual Studio window where the *AdtE2ESample.sln* project is open, use the **Solution Explorer** pane to navigate to the *AdtSampleApp\SampleClientApp\Models folder*. This folder contains sample models.

+1. You can verify the update succeeded by running this command to see room0's information:

+Next, you can create some relationships between these twins, to connect them into a [twin graph](concepts-twins-graph.md). Twin graphs are used to represent an entire environment.

+The types of relationships that you can create from one twin to another are defined within the [models](#model-a-physical-environment-with-dtdl) that you uploaded earlier. The [model definition for Floor](https://github.com/azure-Samples/digital-twins-samples/blob/master/AdtSampleApp/SampleClientApp/Models/Floor.json) specifies that floors can have a type of relationship called `contains`, which makes it possible to create a `contains`-type relationship from each Floor twin to the corresponding room that it contains.

+1. Run the following code to add a `contains` relationship from each of the Floor twins you created earlier to a corresponding Room twin. The relationships are named relationship0 and relationship1.

+ >The `contains` relationship in the [Floor model](https://github.com/azure-Samples/digital-twins-samples/blob/master/AdtSampleApp/SampleClientApp/Models/Floor.json) was also defined with two string properties, `ownershipUser` and `ownershipDepartment`, so you can also provide arguments with the initial values for these when you create the relationships.

+1. What are all the entities from my environment represented in Azure Digital Twins? (query all)

+1. What are all the rooms in my environment? (query by model)

+ You can restrict your query to twins of a certain type, to get more specific information about what's represented. The result of this shows room0 and room1, but doesn't show floor0 or floor1 (since they're floors, not rooms).

+1. What are all the rooms on floor0? (query by relationship)

+1. What are all the twins in my environment with a temperature above 75? (query by property)

+1. What are all the rooms on floor0 with a temperature above 75? (compound query)

+* If you plan to continue to the next tutorial, you can keep the resources you set up here to continue using this Azure Digital Twins instance and configured sample app for the next tutorial

+* If you want to continue using the Azure Digital Twins instance, but clear out all of its models, twins, and relationships, you can use the sample app's `DeleteAllTwins` and `DeleteAllModels` commands to clear the twins and models in your instance, respectively.

+To work with Azure Digital Twins in this article, you first need to set up an Azure Digital Twins instance and the required permissions for using it. If you already have an Azure Digital Twins instance set up from previous work, you can use that instance.

+* The instance's **host name**

+Models are similar to classes in object-oriented programming languages; they provide user-defined templates for [digital twins](concepts-twins-graph.md) to follow and instantiate later. They're written in a JSON-like language called *Digital Twins Definition Language (DTDL)*, and can define a twin's properties, telemetry, relationships, and components.

+> DTDL also allows for the definition of commands on digital twins. However, commands are not currently supported in the Azure Digital Twins service.

+1. Run this [az dt twin update](/cli/azure/dt/twin#az_dt_twin_update) command to change room0's RoomName from Room0 to PresidentialSuite:

+Next, you can create some relationships between these twins, to connect them into a [twin graph](concepts-twins-graph.md). Twin graphs are used to represent an entire environment.

+The types of relationships that you can create from one twin to another are defined within the [models](#model-a-physical-environment-with-dtdl) that you uploaded earlier. The [model definition for Floor](https://github.com/azure-Samples/digital-twins-samples/blob/master/AdtSampleApp/SampleClientApp/Models/Floor.json) specifies that floors can have a type of relationship called `contains`. Since the model definition specifies this relationship, it's possible to create a `contains`-type relationship from each Floor twin to the corresponding room that it contains.

+1. Run the following code to add a `contains`-type relationship from each of the Floor twins you created earlier to the corresponding Room twin. The relationships are named relationship0 and relationship1.

+ >The `contains` relationship in the [Floor model](https://github.com/azure-Samples/digital-twins-samples/blob/master/AdtSampleApp/SampleClientApp/Models/Floor.json) was also defined with two properties, `ownershipUser` and `ownershipDepartment`, so you can also provide arguments with the initial values for these when you create the relationships.

+1. What are all the entities from my environment represented in Azure Digital Twins? (query all)

+1. What are all the rooms in my environment? (query by model)

+ You can restrict your query to twins of a certain type, to get more specific information about what's represented. The result of this shows room0 and room1, but doesn't show floor0 or floor1 (since they're floors, not rooms).

+1. What are all the rooms on floor0? (query by relationship)

+1. What are all the twins in my environment with a temperature above 75? (query by property)

+1. What are all the rooms on floor0 with a temperature above 75? (compound query)

+* If you plan to continue to the next tutorial, you can keep the resources you set up here and reuse the Azure Digital Twins instance without clearing anything in between.

+* If you want to continue using the Azure Digital Twins instance, but clear out all of its models, twins, and relationships, you can use the [az dt twin relationship delete](/cli/azure/dt/twin/relationship#az_dt_twin_relationship_delete), [az dt twin delete](/cli/azure/dt/twin#az_dt_twin_delete), and [az dt model delete](/cli/azure/dt/model#az_dt_model_delete) commands to clear the relationships, twins, and models in your instance, respectively.

+> * Propagate changes through the twin graph by processing digital twin notifications with Azure Functions, endpoints, and routes

+The sample project used in this tutorial represents a real-world building scenario, containing a floor, a room, and a thermostat device. These components will be digitally represented in an Azure Digital Twins instance, which will then be connected to [IoT Hub](../iot-hub/about-iot-hub.md), [Event Grid](../event-grid/overview.md), and two [Azure functions](../azure-functions/functions-overview.md) to enable movement of data.

+Here are the components implemented by the building scenario AdtSampleApp sample app:

+* SampleClientApp - A sample Azure Digital Twins solution

+* SampleFunctionsApp - An Azure Functions app that updates your Azure Digital Twins graph based on telemetry from IoT Hub and Azure Digital Twins events

+First, you'll use the AdtSampleApp solution from the sample project to build the Azure Digital Twins piece of the end-to-end scenario (**section A**):

+In your Visual Studio window where the *AdtE2ESample.sln* solution is open, run the SampleClientApp project with this button in the toolbar:

+The next step is setting up an [Azure Functions app](../azure-functions/functions-overview.md) that will be used throughout this tutorial to process data. The function app, SampleFunctionsApp, contains two functions:

+Back in your Visual Studio window where the *AdtE2ESample.sln* solution is open, the function app is located in the SampleFunctionsApp project. You can view it in the **Solution Explorer** pane.

+In the **Solution Explorer** pane, expand **SampleFunctionsApp > Dependencies**. Right-select **Packages** and choose **Manage NuGet Packages...**.

+Doing so will open the NuGet Package Manager. Select the **Updates** tab and if there are any packages to be updated, check the box to **Select all packages**. Then select **Update**.

+1. Create an Azure storage account by running the following command:

+1. Create an Azure function app by running the following command:

+1. Next, you'll zip up the functions and publish them to your new Azure function app.

+ The cmdlet will create a *publish.zip* file in the directory location of your terminal that includes a *host.json* file, as well as *bin*, *ProcessDTRoutedData*, and *ProcessHubToDTEvents* directories.

+The second setting creates an environment variable for the function with the URL of your Azure Digital Twins instance. The function code will use the value of this variable to refer to your instance. For more information about environment variables, see [Manage your function app](../azure-functions/functions-how-to-use-azure-function-app-settings.md?tabs=portal).

+The output is the list of settings for the Azure Function, which should now contain an entry called `ADT_SERVICE_URL`.

+To do so, you'll create an *Event Subscription* on your IoT Hub, with the Azure function as an endpoint. This "subscribes" the function to events happening in IoT Hub.

+In the [Azure portal](https://portal.azure.com/), navigate to your newly created IoT hub by searching for its name in the top search bar. Select **Events** from the hub menu, and select **+ Event Subscription**.

+Selecting this option will bring up the **Create Event Subscription** page.

+* **EVENT SUBSCRIPTION DETAILS** > **Name**: Give a name to your event subscription.

+* **TOPIC DETAILS** > **System Topic Name**: Give a name to use for the system topic.

+* **EVENT TYPES** > **Filter to Event Types**: Select **Device Telemetry** from the menu options.

+* **ENDPOINT DETAILS** > **Endpoint Type**: Select **Azure Function** from the menu options.

+* **ENDPOINT DETAILS** > **Endpoint**: Select the **Select an endpoint** link, which will open a **Select Azure Function** window:

+ - Fill in your **Subscription**, **Resource group**, **Function app**, and **Function** (**ProcessHubToDTEvents**). Some of these values may auto-populate after selecting the subscription.

+Back on the **Create Event Subscription** page, select **Create**.

+Begin by getting the IoT hub connection string with this command:

+Then, get the device connection string with this command:

+In a new Visual Studio window, open (from the downloaded solution folder) *DeviceSimulator* > **DeviceSimulator.sln**.

+> You should now have two Visual Studio windows, one with *DeviceSimulator.sln* and one from earlier with *AdtE2ESample.sln*.

+From the **Solution Explorer** pane in this new Visual Studio window, select **DeviceSimulator > AzureIoTHub.cs** to open it in the editing window. Change the following connection string values to the values you gathered above:

+The *ProcessHubToDTEvents* function you published earlier listens to the IoT Hub data, and calls an Azure Digital Twins API to update the `Temperature` property on the thermostat67 twin.

+To see the data from the Azure Digital Twins side, go to your Visual Studio window where the *AdtE2ESample.sln* solution is open and run the SampleClientApp project.

+You should see the live updated temperatures from your Azure Digital Twins instance being logged to the console every two seconds.

+To do so, you'll create an Event Grid subscription that sends data from the event grid topic that you created earlier to your *ProcessDTRoutedData* Azure function.

+In the [Azure portal](https://portal.azure.com/), navigate to your event grid topic by searching for its name in the top search bar. Select **+ Event Subscription**.

+The steps to create this event subscription are similar to when you subscribed the first Azure function to IoT Hub earlier in this tutorial. This time, you don't need to specify **Device Telemetry** as the event type to listen for, and you'll connect to a different Azure function.

+On the **Create Event Subscription** page, fill in the fields as follows (fields filled by default aren't mentioned):

+* **EVENT SUBSCRIPTION DETAILS** > **Name**: Give a name to your event subscription.

+* **ENDPOINT DETAILS** > **Endpoint Type**: Select **Azure Function** from the menu options.

+* **ENDPOINT DETAILS** > **Endpoint**: Select the **Select an endpoint** link, which will open a **Select Azure Function** window:

+ - Fill in your **Subscription**, **Resource group**, **Function app**, and **Function** (**ProcessDTRoutedData**). Some of these values may auto-populate after selecting the subscription.

+Back on the **Create Event Subscription** page, select **Create**.

+Go to your Visual Studio window where the *DeviceSimulator.sln* solution is open, and run the DeviceSimulator project.

+To see the data from the Azure Digital Twins side, go to your Visual Studio window where the *AdtE2ESample.sln* solution is open, and run the SampleClientApp project.

+In the project console window that opens, run the following command to get the temperatures being reported by both the digital twin thermostat67 and the digital twin room21.

+You should see the live updated temperatures from your Azure Digital Twins instance being logged to the console every two seconds. Notice that the temperature for room21 is being updated to match the updates to thermostat67.

+2. Simulated device telemetry is sent to IoT Hub, where the *ProcessHubToDTEvents* Azure function is listening for telemetry events. The *ProcessHubToDTEvents* Azure function uses the information in these events to set the `Temperature` property on thermostat67 (**arrow B** in the diagram).

+3. Property change events in Azure Digital Twins are routed to an event grid topic, where the *ProcessDTRoutedData* Azure function is listening for events. The *ProcessDTRoutedData* Azure function uses the information in these events to set the `Temperature` property on room21 (**arrow C** in the diagram).

+* If you want to continue using the Azure Digital Twins instance you set up in this article, but clear out some or all of its models, twins, and relationships, you can use the [az dt](/cli/azure/dt) CLI commands to delete the elements you want to remove.

+ $keyVault = New-AzKeyVault -Name "your_key_vault_name" -ResourceGroupName "your_resource_group" -Location "resource_location" -SoftDeleteRetentionInDays 90

+ | Rule_5 | * | https:443 | azure.archive.ubuntu.com | Allows access to updates for security packages. |

+ | Rule_6 | TCP | * | SQL | 1433 , 11000-11999 | If you are using the default sql servers provided by HDInsight, configure a network rule in the Service Tags section for SQL that will allow you to log and audit SQL traffic. Unless you configured Service Endpoints for SQL Server on the HDInsight subnet, which will bypass the firewall. If you are using custom SQL server for Ambari, Oozie, Ranger and Hive metastores then you only need to allow the traffic to your own custom SQL Servers. Refer to [Azure SQL Database and Azure Synapse Analytics connectivity architecture](../azure-sql/database/connectivity-architecture.md) to see why 11000-11999 port range is also needed in addition to 1433. |

+ | Rule_7 | TCP | * | Azure Monitor | * | (optional) Customers who plan to use auto scale feature should add this rule. |

+- [OBS Studio](https://obsproject.com/download)

+- [Restream.io](https://restream.io/)

+- [Streamlabs](https://streamlabs.com/)

+## Self-hosted integration runtime network and proxy recommendations

+For scanning data sources across your on-premises and Azure networks, you may need to deploy and use one or multiple [self-hosted integration runtime virtual machines](manage-integration-runtimes.md) inside an Azure VNet or an on-premises network, for any of the scenarios mentioned earlier in this document.

+- To simplify management, when possible, use Azure runtime and [Azure Purview Managed runtime](catalog-managed-vnet.md) to scan Azure data sources.

+

+- The Self-hosted integration runtime service can communicate with Azure Purview through public or private network over port 443. For more information see, [self-hosted integration runtime networking requirements](manage-integration-runtimes.md#networking-requirements).

+- One self-hosted integration runtime VM can be used to scan one or multiple data sources in Azure Purview, however, self-hosted integration runtime must be only registered for Azure Purview and cannot be used for Azure Data Factory or Azure Synapse at the same time.

+- You can register and use one or multiple self-hosted integration runtime in one Azure Purview account. It is recommended to place at least one self-hosted integration runtime VM in each region or on-premises network where your data sources reside.

+- It is recommended to define a baseline for required capacity for each self-hosted integration runtime VM and scale the VM capacity based on demand.

+- It is recommended to setup network connection between self-hosted integration runtime VMs and Azure Purview and its managed resources through private network, when possible.

+- Allow outbound connectivity to download.microsoft.com, if auto-update is enabled.

+- The self-hosted integration runtime service does not require outbound internet connectivity, if self-hosted integration runtime VMs are deployed in an Azure VNet or in the on-premises network that is connected to Azure through an ExpressRoute or Site to Site VPN connection. In this case, the scan and metadata ingestion process can be done through private network.

+- Self-hosted integration runtime can communicate Azure Purview and its managed resources directly or through [a proxy server](manage-integration-runtimes.md#proxy-server-considerations). Avoid using proxy settings if self-hosted integration runtime VM is inside an Azure VNet or connected through ExpressRoute or Site to Site VPN connection.

+- Review supported scenarios, if you need to use self-hosted integration runtime with [proxy setting](manage-integration-runtimes.md#proxy-server-considerations).

+- If delegated auth is used, make sure proper [Power BI license](/power-bi/admin/service-admin-licensing-organization#subscription-license-types) is assigned to Power BI admin user that is used for the scan.

+

+3. Assign proper Power BI license to the user.

+6. Create an App Registration in your Azure Active Directory tenant. Provide a web URL in the **Redirect URI**. Take note of Client ID(App ID).

+7. From Azure Active Directory dashboard, select newly created application and then select **App registration**. From **API Permissions**, assign the application the following delegated permissions and grant admin consent for the tenant:

+ - Microsoft Graph User.Read

+2. Assign proper Power BI license to the user.

+7. Create an App Registration in your Azure Active Directory tenant where Power BI is located. Provide a web URL in the **Redirect URI**. Take note of Client ID(App ID).

+ - Microsoft Graph User.Read

+11. Under **Advanced settings**, enable **Allow Public client flows**.

+12. In the Azure Purview Studio, navigate to the **Data map** in the left menu. Navigate to **Sources**.

+13. Select the registered Power BI source from cross tenant.

+14. Select **+ New scan**.

+15. Give your scan a name. Then select the option to include or exclude the personal workspaces.

+16. Select **Azure AutoResolveIntegrationRuntime** from the drop-down list.

+17. For the **Credential**, select **Delegated authentication** and click **+ New** to create a new credential.

+

+18. Create a new credential and provide required parameters:

+19. Select **Test Connection** before continuing to next steps.

+ If **Test Connection** failed, select **View Report** to see the detailed status and troubleshoot the problem:

+ 1. Access - Failed status means the user authentication failed: Validate if username and password is correct. review if the Credential contains correct Client (App) ID from the App Registration.

+ 2. Assets (+ lineage) - Failed status means the Azure Purview - Power BI authorization has failed. Make sure the user is added to Power BI Administrator role and has proper Power BI license assigned to.

+ 3. Detailed metadata (Enhanced) - Failed status means the Power BI admin portal is disabled for the following setting - **Enhance admin APIs responses with detailed metadata**

+20. Set up a scan trigger. Your options are **Recurring**, and **Once**.

+## Troubleshooting tips

+If delegated auth is used:

+- Check your key vault. Make sure there are no typos in the password.

+- Assign proper [Power BI license](/power-bi/admin/service-admin-licensing-organization#subscription-license-types) to Power BI administrator user.

+- Validate if user is assigned to Power BI Administrator role.

+- If user is recently created, make sure password is reset successfully and user can successfully initiate the session.

+ Title: Improve your security defenses for ransomware attacks with Azure Firewall Premium

+description: In this article, you learn how Azure Firewall Premium can help you protect against ransomware.

+documentationcenter: na

+ms.assetid: 9dcb190e-e534-4787-bf82-8ce73bf47dba

+ na

+# Improve your security defenses for ransomware attacks with Azure Firewall Premium

+In this article, you learn how Azure Firewall Premium can help you protect against ransomware.

+## What is ransomware?

+Ransomware is a type of malicious software designed to block access to your computer system until a sum of money is paid. The attacker usually exploits an existing vulnerability in your system to penetrate your network and execute the malicious software on the target host.

+Ransomware is often spread through phishing emails that contain malicious attachments or through drive-by downloading. Drive-by downloading occurs when a user unknowingly visits an infected website and then malware is downloaded and installed without the userΓÇÖs knowledge.

+## Protect from network malicious activity

+A network intrusion detection and prevention system (IDPS) allows you to monitor your network for malicious activity, log information about this activity, report it, and optionally attempt to block it.

+[Azure Firewall Premium](../../firewall/premium-features.md#idps) provides signature-based IDPS where every packet is inspected thoroughly, including all its headers and payload, to identify a malicious activity and to prevent it from penetrating into your network.

+The IDPS signatures are applicable for both application and network level traffic (Layers 4-7), fully managed, and contain more than 65,000 signatures in over 50 different categories. To keep them (the IDPS signatures?) up to date with the dynamic ever-changing attack landscape:

+- Azure Firewall has early access to vulnerability information from [Microsoft Active Protections Program](https://www.microsoft.com/msrc/mapp) (MAPP) and [Microsoft Security Response Center](https://www.microsoft.com/msrc/) (MSRC).

+- Azure Firewall releases 30 to 50 new signatures each day.

+Today, modern encryption (SSL/TLS) is used globally to secure Internet traffic. Attackers use encryption to carry their malicious software into the victimΓÇÖs network. Therefore, customers must inspect their encrypted traffic just like any other traffic.

+Azure Firewall Premium IDPS allows you to detect attacks in all ports and protocols for non-encrypted traffic. However, when HTTPS traffic needs to be inspected, Azure Firewall can use its TLS inspection capability to decrypt the traffic and accurately detect malicious activities.

+After the ransomware is installed on the target machine, it may try to encrypt the machineΓÇÖs data. The ransomware requires an encryption key and may use the Command and Control (C&C) to get the encryption key from the C&C server hosted by the attacker. CryptoLocker, WannaCry, TeslaCrypt, Cerber, and Locky are some of the ransomwares using C&C to fetch the required encryption keys.

+Azure Firewall Premium has hundreds of signatures that are designed to detect C&C connectivity and block it to prevent the attacker from encrypting your data. The following diagram shows Azure Firewall protection against a ransomware attack using the C&C channel.

+

+## Fend off ransomware attacks

+A holistic approach to fend off ransomware attacks is recommended. Azure Firewall operates in a default deny mode and blocks access unless explicitly allowed by the administrator. Enabling the Threat Intelligence (TI) feature in alert/deny mode blocks access to known malicious IPs and domains. Microsoft Threat Intel feed is updated continuously based on new and emerging threats.

+Firewall Policy can be used for centralized configuration of firewalls. This helps with responding to threats rapidly. Customers can enable Threat Intel and IDPS across multiple firewalls with just a few clicks. Web categories lets administrators allow or deny user access to web categories such as gambling websites, social media websites, and others. URL filtering provides scoped access to external sites and can cut down risk even further. In other words, Azure Firewall has everything necessary for companies to defend comprehensively against malware and ransomware.

+Detection is equally important as prevention. Azure Firewall solution for Azure Sentinel gets you both detection and prevention in the form of an easy-to-deploy solution. Combining prevention and detection allows you to ensure that you both prevent sophisticated threats when you can, while also maintaining an ΓÇ£assume breach mentalityΓÇ¥ to detect and quickly respond to cyberattacks.

+## Next steps

+See [Ransomware protection in Azure](ransomware-protection.md) to learn more about defenses for ransomware attacks in Azure and for guidance on how to proactively protect your assets.

+To learn more about Azure Firewall Premium, see:

+- [Azure Firewall Premium features](../../firewall/premium-features.md)

+- [Optimize security with Azure Firewall solution for Azure Sentinel](https://www.microsoft.com/security/blog/2021/06/08/optimize-security-with-azure-firewall-solution-for-azure-sentinel/)

+|<a name="devicetype"></a>**DeviceType** | Enumerated | The type of the device stored in DeviceType fields. Possible values include:<br>- `Computer`<br>- `Mobile Device`<br>- `IOT Device`<br>- `Other`. For more information, see [The Device entity](#the-device-entity). |

+| **EventStartTime** | Mandatory | Date/time | The time in which the event started. If the source supports aggregation and the record represents multiple events, the time that the first event was generated. If not provided by the source record, this field aliases the [TimeGenerated](#timegenerated) field. |

+| **EventEndTime** | Mandatory | Date/time | The time in which the event ended. If the source supports aggregation and the record represents multiple events, the time that the last event was generated. If not provided by the source record, this field aliases the [TimeGenerated](#timegenerated) field. |

+The Site Recovery team, and Azure capacity management team, plan for sufficient infrastructure capacity on a best-effort basis. When you start a failover, the teams also help ensure VM instances that are protected by Site Recovery can deploy to the target region.

+The Site Recovery team and Azure capacity management team plan for sufficient infrastructure capacity on a best-effort basis. When you start a failover, the teams also help ensure VM instances that are protected by Site Recovery can deploy to the target region.

+### Does Site Recovery work with Capacity Reservation?

+Yes, you can create a Capacity Reservation for your VM SKU in the disaster recovery region and/or zone, and configure it in the Compute properties of the Target VM. Once done, site recovery will use the earmarked capacity for the failover. [Learn more](https://aka.ms/on-demand-capacity-reservations-docs).

+### Why should I reserve capacity using Capacity Reservation at the destination location?

+While Site Recovery team makes a best effort to ensure that capacity is available, we do not guarantee the same. Site Recovery's best effort is backed by a 2-hour RTO SLA. But if you require further assurance and _guaranteed compute capacity,_ then we recommend you to purchase [Capacity Reservations](https://aka.ms/on-demand-ca.pacity-reservations-docs)

+|Azure SQL Managed Instance|Preview|No|Yes|<ul><li>[Data virtualization with Azure SQL Managed Instance (preview)](../../azure-sql/managed-instance/data-virtualization-overview.md)</li></ul>|

+- [Best practices for using Azure Data Lake Storage Gen2](data-lake-storage-best-practices.md)