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

Este artigo descreve o que são gêmeos digitais no contexto dos Gêmeos Digitais do Azure e como as relações entre eles podem formar um gráfico de gêmeos. Em uma solução de Gêmeos Digitais do Azure, as entidades em seu ambiente são representadas por gêmeos digitais. Um gêmeo digital é uma instância de um de seus modelos personalizados. Ele pode ser conectado a outros gêmeos digitais através de relacionamentos para formar um grafo gêmeo: este gráfico gêmeo é a representação de todo o seu ambiente.

Gorjeta

"Gêmeos Digitais do Azure" refere-se a este serviço do Azure como um todo. "Gêmeo(s) digital(is)" ou apenas "gêmeo(s)" refere-se a nós gêmeos individuais dentro de sua instância do serviço.

Digital Twins

Antes de criar um gêmeo digital em sua instância do Azure Digital Twins, você precisa ter um modelo carregado no serviço. Um modelo descreve o conjunto de propriedades e relações que um determinado gêmeo pode ter, entre outras coisas. Para obter os tipos de informações definidos em um modelo, consulte Modelos personalizados.

Depois de criar e carregar um modelo, seu aplicativo cliente pode criar uma instância do tipo. Esta instância é um gêmeo digital. Por exemplo, depois de criar um modelo de Floor, você pode criar um ou vários gêmeos digitais que usam esse tipo (como um gêmeo tipo Floor chamado GroundFloor, outro chamado Floor2 e assim por diante).

Nota

Os gêmeos digitais no Azure Digital Twins são diferentes dos gêmeos de dispositivo no Hub IoT. Os gêmeos de dispositivo do Hub IoT geralmente se concentram em descrever os aspetos e os recursos de um dispositivo em si, enquanto os gêmeos nos Gêmeos Digitais do Azure são representações mais conceituais que podem armazenar informações definidas pelo usuário sobre um dispositivo ou muitos dispositivos relacionados.

Os dispositivos no Hub IoT podem ser conectados aos Gêmeos Digitais do Azure como parte de uma solução de ponta a ponta que representa seu dispositivo em todos os serviços.

Relacionamentos: um gráfico de gêmeos digitais

Gêmeos são conectados em um gráfico de gêmeos por seus relacionamentos. 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 destinada a gêmeos do tipo Room. Com esta definição, os Gêmeos Digitais do Azure permitirão que você crie contains relacionamentos de qualquer gêmeo de piso para qualquer gêmeo de quarto (incluindo gêmeos que são de subtipos de quarto).

O resultado desse processo é um conjunto de nós (os gêmeos digitais) conectados via arestas (suas relações) em um gráfico.

Visualização

O Azure Digital Twins Explorer é uma ferramenta visual para explorar os dados no seu gráfico de Gêmeos Digitais do Azure. Pode utilizar o explorador para ver, consultar e editar os seus modelos, gémeos e relações.

Para ler sobre a ferramenta Azure Digital Twins Explorer, consulte Azure Digital Twins Explorer. Para obter etapas detalhadas sobre como usar seus recursos, consulte Usar o Azure Digital Twins Explorer.

Veja como é a visualização:

Criar com as APIs

Esta seção mostra como é criar gêmeos digitais e relacionamentos a partir de um aplicativo cliente. Ele contém exemplos do SDK do .NET que usam as APIs do DigitalTwins para fornecer mais contexto sobre o que acontece dentro de cada um desses conceitos.

Criar duplos digitais

Abaixo está um trecho do código do cliente que usa as APIs do DigitalTwins para instanciar um gêmeo do tipo Room com um twinId que é definido durante a instanciação.

Você pode inicializar as propriedades de um gêmeo quando ele é 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("temperature")]
    public double Temperature { get; set; }

    [JsonPropertyName("humidity")]
    public double 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
        {
            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 value: {response.Value.Temperature}");
    }
}

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

Nota

Embora as propriedades gêmeas sejam tratadas como opcionais e, portanto, não precisem ser inicializadas, todos os componentes do gêmeo precisam ser definidos quando o gêmeo é criado. Podem ser objetos vazios, mas os próprios componentes devem existir.

Criar relações

Aqui está um exemplo de código de cliente que usa as APIs do DigitalTwins para construir um relacionamento de um gêmeo digital (o gêmeo "origem") para outro gêmeo digital (o gêmeo "destino").

public async Task CreateRelationship(DigitalTwinsClient client)
{
    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);
}

Crie gêmeos e relacionamentos em massa com a API de Trabalhos de Importação

Você pode carregar muitos gêmeos e relacionamentos em uma única chamada de API usando a API de Trabalhos de Importação. Gêmeos e relacionamentos criados com essa API podem, opcionalmente, incluir a inicialização de suas propriedades. Para obter instruções detalhadas e exemplos que usam essa API, consulte instruções de importação em massa para gêmeos e relacionamentos.

Excluir elementos do gráfico

Para excluir gêmeos e relacionamentos específicos, use as APIs DigitalTwins Delete e DigitalTwins DeleteRelationship (também disponíveis como comandos CLI e chamadas SDK).

Para excluir todos os modelos, gêmeos e relacionamentos em uma instância de uma só vez, use a API Excluir Trabalhos.

Representações JSON de elementos gráficos

Os dados de gêmeos digitais e os dados de relacionamento são armazenados no formato JSON, o que significa que, quando você consulta o gráfico de gêmeos em sua instância de Gêmeos Digitais do Azure, o resultado será uma representação JSON de gêmeos digitais e relacionamentos que você criou.

Formato JSON de gêmeos digitais

Quando representado como um objeto JSON, um gêmeo digital exibirá os seguintes campos:

Nome do campo	Description
$dtId	Uma cadeia de caracteres fornecida pelo usuário que representa a ID do gêmeo digital
$etag	Campo HTTP padrão atribuído pelo servidor Web
$metadata.$model	O ID da interface do modelo que caracteriza este gêmeo digital
$metadata.<property-name>	Outras informações de metadados sobre as propriedades do gêmeo digital
$metadata.<property-name>.lastUpdateTime	A data/hora em que a mensagem de atualização de propriedade foi processada pelos Gêmeos Digitais do Azure
$metadata.<property-name>.sourceTime	Uma propriedade opcional gravável que representa o carimbo de data/hora quando a atualização da propriedade foi observada no mundo real. Essa propriedade só pode ser gravada usando a versão 2022-05-31 das APIs/SDKs do Azure Digital Twins e o valor deve estar em conformidade com o formato de data e hora ISO 8601. Para obter mais informações sobre como atualizar essa propriedade, consulte Atualizar sourceTime de uma propriedade.
<property-name>	O valor de uma propriedade em JSON (string, tipo de número ou objeto)
$relationships	A URL do caminho para a coleção de relações. Este campo está ausente se o gêmeo digital não tiver arestas de relacionamento de saída.
<component-name>	Um objeto JSON que contém os valores de propriedade e metadados do componente, semelhantes aos do objeto raiz. Este objeto existe mesmo se o componente não tiver propriedades.
<component-name>.$metadata	As informações de metadados para o componente, semelhante ao nível 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 gémeo tem duas propriedades, Humidade e Temperatura, e um componente chamado Termostato.

{
    "$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": {}
    }

Formato JSON de relacionamento

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

Nome do campo	Description
$relationshipId	Uma cadeia de caracteres fornecida pelo usuário que representa a ID dessa relação. Essa cadeia de caracteres é exclusiva no contexto do gêmeo digital de origem, o que também significa que sourceId + relationshipId é exclusiva no contexto da instância dos Gêmeos Digitais do Azure.
$etag	Campo HTTP padrão atribuído pelo servidor Web
$sourceId	O ID do gêmeo digital de origem
$targetId	O ID do gêmeo digital de destino
$relationshipName	O nome da relação
<property-name>	[Opcional] O valor de uma propriedade dessa 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"
}

Próximos passos

Veja como gerenciar elementos gráficos com as APIs do Gêmeo Digital do Azure:

• Gerenciar gêmeos digitais
• Gerencie o gráfico gêmeo e os relacionamentos

Ou, saiba como consultar o gráfico de gêmeos do Azure Digital Twins para obter informações:

• Linguagem da consulta