Azure Digital Twins

To connect to the Azure Digital Twins service, create an Azure Digital Twins connector and configure it as a persistence provider on the Creating a Connection screen. This enables real-time digital twin instances to persist updates to their state properties in the corresponding digital twin instances stored in Azure Digital Twins. It also allows real-time digital twin instances to retrieve the current values of their state properties when they are created, as well as retrieve and update those properties in the service at any point during their lifetime.

To connect to the Azure Digital Twins service, you need to supply the following account parameters when creating the connector. The first parameter is the Azure Digital Twins Service URL, which is the host name listed in the Azure Digital Twins resource created in your Azure subscription. More information on creating an Azure Digital Twins resource group and resource can be found here.

The next three parameters are account credentials in your Azure Digital Twins App Registration in Azure Active Directory. The first two credentials are listed in the registration. The client secret is supplied to when you create the registration and must be saved at that time. More information on creating an app registration can be found here.

Azure Digital Twins Tenant ID: tenant id listed in the Azure Digital Twins App Registration in AD
Client ID: client id listed in the Azure Digital Twins App Registration in AD
Client Secret: client secret supplied when creating the Azure Digital Twins App Registration in AD

In addition, you can supply the following parameters for the connection:

Update Interval: the minimum period in seconds between successive updates to an Azure Digital Twins instance after updates to its corresponding real-time digital twins instance
Retrieve State on Create: indication whether to retrieve properties from Azure Digital Twins when creating a real-time digital twin instance; 1 = retrieve state; 0 = do not retrieve state

Note

The Update Interval parameter allows real-time digital twin deployments with high message rates and/or many data sources to throttle their updates to the Azure Digital Twins service and avoid hitting its resource limits (currently 1000 updates per second). More information on Azure Digital Twins resource limits can be found here.

The screenshot below shows the dialog in the ScaleOut Digital Twins™ UI used to create an Azure Digital Twins connector:

adt_connector_image

You can deploy the connector immediately after it is created, or you can deploy it at a later time. The connector authenticates with the Azure Digital Twins service when it is deployed.

Enabling Persistence for a Digital Twin Model

Both Java and .NET models can enable persistence to the Azure Digital Twins service when the model is deployed. In addition to the standard backing store policy options (Read-Through and Write-Behind), the Azure Digital Twins persistence provider also supports an additional option: None. This option disables implicit persistence of digital twin instances to the Azure Digital Twins service while still allowing your model to retrieve existing instances and updating their state properties in the Azure Digital Twins service.

deploy_new_model_with_adt_image

When implementing message processing logic for a real-time digital twin model, you can use the AzureDigitalTwinsProvider property of the ProcessingContext object to retrieve and update any digital twin instance in the Azure Digital Twins service.

The following example shows a ProcessMessageAsync method for a digital twin model, RealTimeWindTurbineModel, which retrieves the corresponding digital twin instance in Azure Digital Twins and updates one of its property values.

public override async Task<ProcessingResult> ProcessMessageAsync(
      ProcessingContext<RealTimeWindTurbineModel> context,
      RealTimeWindTurbineModel dt,
      byte[] msgBytes)
{
      // Deserialize the message bytes into a specific message type
      WindTurbineMessage? msg = JsonSerializer.Deserialize<WindTurbineMessage>(msgBytes);

      // Process incoming message
      // ...

      // Retrieve the corresponding state properties of the digital twin instance
      // in Azure Digital Twins and update one of its property values
      if (context.AzureDigitalTwinsProvider != null)
      {
          try
          {
              var adtInstance = await context.AzureDigitalTwinsProvider.GetInstanceAsync(
                     dt?.Model, dt?.Id);

              if (adtInstance != null)
                  await context.AzureDigitalTwinsProvider.UpdatePropertyAsync(
                     dt?.Model,
                     dt?.Id,
                     nameof(dt.NumberMsgsWithOverTemp),
                     dt?.NumberMsgsWithOverTemp);
          }
          catch(Exception ex)
          {
              await context.LogMessageAsync(
                  LogSeverity.Error,
                  $"Failed to update DT instance {dt?.Id} in Azure Digital Twins: {ex.Message}");
          }
      }

      return ProcessingResult.DoUpdate;
}