Gémeos digitais e seu gráfico gémeo

Este artigo descreve o que são os gémeos digitais no contexto das Gémeas Digitais Azure, e como as relações entre eles podem formar um gráfico gémeo. Numa solução Azure Digital Twins, as entidades do seu ambiente são representadas por gémeos digitais. Um gémeo digital é um exemplo de um dos seus modelos personalizados. Pode ser conectado a outros gémeos digitais através de relacionamentos para formar um gráfico gémeo: este gráfico gémeo é a representação de todo o seu ambiente.

Dica

"Azure Digital Twins" refere-se a este serviço Azure como um todo. "Digital twin(s)" ou apenas "twin(s)" refere-se a nódoas gémeas individuais dentro do seu caso do serviço.

Digital Twins

Antes de criar um gémeo digital na sua instância Azure Digital Twins, precisa de ter um modelo carregado para o serviço. Um modelo descreve o conjunto de propriedades, mensagens de telemetria e relacionamentos que um gémeo em particular pode ter, entre outras coisas. Para os tipos de informação que são definidos num modelo, consulte modelos Personalizados.

Depois de criar e carregar um modelo, a sua aplicação de clientes pode criar uma instância do tipo. Este caso é um gémeo digital. Por exemplo, depois de criar um modelo de Floor, pode criar um ou vários gémeos digitais que usam este tipo (como um gémeo do tipo chão chamado GroundFloor, outro chamado Floor2, e assim por diante).

Nota

Gémeos digitais em Azure Digital Twins são diferentes dos gémeos do dispositivo em Hub IoT. Hub IoT os gémeos do dispositivo focam-se frequentemente em descrever os aspetos e capacidades de um dispositivo em si, enquanto os gémeos em Azure Digital Twins são representações mais conceptuais que podem armazenar insights definidos pelo utilizador sobre um dispositivo ou muitos dispositivos relacionados.

Os dispositivos em Hub IoT podem ser ligados à Azure Digital Twins como parte de uma solução de ponta a ponta que representa o seu dispositivo através dos serviços.

Relacionamentos: um gráfico de gémeos digitais

Os gémeos estão ligados a um gráfico gémeo pelas suas relações. As relações que um gémeo pode ter são definidas como parte do seu modelo.

Por exemplo, o modelo Floor pode definir uma contains relação que visa gémeos de tipo Room. Com esta definição, a Azure Digital Twins permitir-lhe-á criar contains relações de qualquer nó gémeo do Chão para qualquer quarto gémeo (incluindo gémeos que são de subtipos de Quarto).

O resultado deste processo é um conjunto de nós (os gémeos digitais) conectados através de bordas (suas relações) num gráfico.

Visualização

O Azure Digital Twins Explorer é uma ferramenta visual para explorar os dados no seu gráfico Azure Digital Twins. Você pode usar o explorador para ver, consultar e editar seus modelos, gémeos e relacionamentos.

Para ler sobre a ferramenta Azure Digital Twins Explorer, consulte o Azure Digital Twins Explorer. Para obter etapas detalhadas sobre como utilizar as suas funcionalidades, consulte Use Azure Digital Twins Explorer.

Aqui está o que a visualização parece:

Screenshot do Azure Digital Twins Explorer mostrando modelos de amostra e gémeos.

Criar com as APIs

Esta secção mostra o que parece criar gémeos digitais e relacionamentos a partir de uma aplicação de cliente. Contém exemplos de código .NET que utilizam as APIs DigitalTwins, para fornecer mais contexto sobre o que se passa dentro de cada um destes conceitos.

Criar duplos digitais

Abaixo está um corte de código de cliente que usa as APIs DigitalTwins para instantaneaizar um twin de tipo Room com um twinId que é definido durante a instantânea.

Pode inicializar as propriedades de um gémeo quando é criado, ou defini-las mais tarde. Para criar um gémeo com propriedades inicializadas, crie um documento JSON que forneça os valores de inicialização necessários.

// Define a custom model type for the twin to be created

internal class CustomDigitalTwin
{
    [JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinId)]
    public string Id { get; set; }

    [JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinETag)]
    public string ETag { get; set; }

    [JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinMetadata)]
    public MyCustomDigitalTwinMetadata Metadata { get; set; } = new MyCustomDigitalTwinMetadata();

    [JsonPropertyName("temperature")]
    public double Temperature { get; set; }

    [JsonPropertyName("humidity")]
    public double Humidity{ get; set; }
}

internal class MyCustomDigitalTwinMetadata
{
    [JsonPropertyName(DigitalTwinsJsonPropertyNames.MetadataModel)]
    public string ModelId { get; set; }

    [JsonPropertyName("temperature")]
    public DigitalTwinPropertyMetadata Temperature { get; set; }

    [JsonPropertyName("humidity")]
    public DigitalTwinPropertyMetadata Humidity { get; set; }
}

// Initialize properties and create the twin
public class TwinOperationsCreateTwin
{
    public async Task CreateTwinAsync(DigitalTwinsClient client)
    {
        // Initialize the twin properties
        var myTwin = new CustomDigitalTwin
        {
            Metadata = { ModelId = "dtmi:example:Room;1" },
            Temperature = 25.0,
            Humidity = 50.0,
        };

        // Create the twin
        const string twinId = "<twin-ID>";
        Response<CustomDigitalTwin> response = await client.CreateOrReplaceDigitalTwinAsync(twinId, myTwin);
        Console.WriteLine($"Temperature last updated on {response.Value.Metadata.Temperature.LastUpdatedOn}");
    }
}

Você também pode usar uma classe de ajudante chamada BasicDigitalTwin para armazenar campos de propriedade em um objeto "twin" mais diretamente, como uma alternativa para usar um dicionário. Para obter mais informações sobre a classe de ajudante e exemplos da sua utilização, consulte Criar um gémeo digital.

Nota

Enquanto as propriedades gémeas são tratadas como opcionais e, portanto, não têm de ser inicializadas, quaisquer componentes no gémeo precisam de ser definidos quando o gémeo é criado. Podem ser objetos vazios, mas os próprios componentes devem existir.

Criar relações

Aqui está um código de cliente exemplo que usa as APIs DigitalTwins para construir uma relação de um gémeo digital (o gémeo "source" ) para outro gémeo digital (o gémeo "alvo").

var rel = new BasicRelationship
{
    TargetId = "myTargetTwin",
    Name = "contains", // a relationship with this name must be defined in the model
    // Initialize properties
    Properties =
    {
        { "active", true },
    },
};
await client.CreateOrReplaceRelationshipAsync("mySourceTwin", "rel001", rel);

Representações de JSON de elementos gráficos

Os dados digitais de gémeos e de relacionamento são armazenados em formato JSON, o que significa que quando consultar o gráfico gémeo no seu exemplo de Azure Digital Twins, o resultado será uma representação JSON de gémeos digitais e relações que criou.

Formato JSON duplo digital

Quando representado como um objeto JSON, um gémeo digital apresentará os seguintes campos:

Nome do campo Description
$dtId Uma cadeia fornecida pelo utilizador que representa o ID do gémeo digital
$etag Campo HTTP padrão atribuído pelo servidor web
$metadata.$model O ID da interface modelo que caracteriza este twin digital
$metadata.<property-name> Outras informações de metadados sobre propriedades do twin digital
$metadata.<property-name>.lastUpdateTime A data/hora da mensagem de atualização da propriedade foi processada pela Azure Digital Twins
$metadata.<property-name>.sourceTime Um imóvel opcional e writable que representa o timetamp quando a atualização da propriedade foi observada no mundo real. Esta propriedade só pode ser escrita utilizando a versão 2022-05-31 das APIs/SDKs Azure Digital Twins e o valor deve estar em conformidade com a data e o formato de hora iso 8601. Para obter mais informações sobre como atualizar esta propriedade, consulte Update a sourceTime de uma propriedade.
<property-name> O valor de um imóvel em JSON (string, tipo de número ou objeto)
$relationships A URL do caminho para a coleção de relacionamentos. Este campo está ausente se o gémeo digital não tiver limites de relacionamento.
<component-name> Um objeto JSON contendo os valores de propriedade e metadados do componente, semelhantes aos do objeto raiz. Este objeto existe mesmo que o componente não tenha propriedades.
<component-name>.$metadata A informação de metadados para o componente, semelhante ao nível de raiz $metadata
<component-name>.<property-name> O valor da propriedade do componente em JSON (string, tipo de número ou objeto)

Aqui está um exemplo de um gémeo digital formatado como um objeto JSON. Este twin tem duas propriedades, humidade e temperatura, e um componente chamado Termóstato.

{
    "$dtId": "myRoomID",
    "$etag": "W/\"8e6d3e89-1166-4a1d-9a99-8accd8fef43f\"",
    "$metadata": {
        "$model": "dtmi:example:Room23;1",
        "Humidity": {
          "lastUpdateTime": "2021-11-30T18:47:53.7648958Z"
        },
        "Temperature": {
          "lastUpdateTime": "2021-11-30T18:47:53.7648958Z"
        }
    },
    "Humidity": 55,
    "Temperature": 35,
    "Thermostat": {
        "$metadata": {}
    }

Relacionamento JSON formato

Quando representado como um objeto JSON, uma relação de um gémeo digital mostrará os seguintes campos:

Nome do campo Description
$relationshipId Uma cadeia fornecida pelo utilizador que representa a identificação desta relação. Esta corda é única no contexto da fonte digital gémea, o que também significa que sourceId + relationshipId é única no contexto da instância Azure Digital Twins.
$etag Campo HTTP padrão atribuído pelo servidor web
$sourceId O ID da fonte digital twin
$targetId A ID do gémeo digital alvo
$relationshipName O nome da relação
<property-name> [Opcional] O valor de um imóvel desta relação, em JSON (string, tipo de número ou objeto)

Aqui está um exemplo de uma relação formatada como um objeto JSON:

{
  "$relationshipId": "relationship-01",
  "$etag": "W/\"506e8391-2b21-4ac9-bca3-53e6620f6a90\"",
  "$sourceId": "GroundFloor",
  "$targetId": "Cafe",
  "$relationshipName": "contains",
  "startDate": "2020-02-04"
}

Passos seguintes

Veja como gerir elementos gráficos com APIs Azure Digital Twin:

Ou, saiba se consulta o gráfico gémeo Azure Digital Twins para obter informações: