Gêmeos digitais e seu grafo 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 grafo gêmeo. 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 dos seus modelos personalizados. Ele pode ser conectado a outras gêmeos digitais por meio de relações para formar um grafo de gêmeos: este grafo de gêmeos é a representação de todo o seu ambiente.

Dica

Os "Gêmeos Digitais do Azure" se referem a esse serviço do Azure como um todo. "Gêmeos digitais" ou apenas "gêmeos" se referem aos nós de gêmeos individuais dentro da sua instância do serviço.

Gêmeos Digitais

Para criar uma cópia digital em sua instância dos Gêmeos Digitais do Azure, carregue um modelo no serviço. Um modelo descreve o conjunto de propriedades e relacionamentos que um determinado gêmeo pode ter, entre outras coisas. Para os tipos de informações que são definidas em um modelo, confira Modelos personalizados.

Após criar e carregar um modelo, o aplicativo do cliente pode criar uma instância do tipo. Essa instância é um gêmeo digital. Por exemplo, após criar um modelo Floor, é possível criar um ou vários gêmeos digitais que usam esse tipo (como um gêmeo do tipo Floor chamado GroundFloor, outro chamado Floor2 e assim por diante).

Observação

Os gêmeos digitais nos Gêmeos Digitais do Azure são diferentes dos gêmeos de dispositivo no Hub IoT. Os dispositivos gêmeos do Hub IoT muitas vezes focam em descrever aspectos e funcionalidades de um dispositivo, enquanto os gêmeos dos Gêmeos Digitais do Azure são representações mais conceituais que podem armazenar insights definidos pelo usuário sobre um dispositivo ou vários 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 entre serviços.

Relações: um grafo de gêmeos digitais

Os gêmeos são conectados a um grafo de gêmeos pelas relações deles. As relações que um gêmeo pode ter são definidas como parte do modelo dele.

Por exemplo, o modelo Floor pode definir uma contains relação destinada a gêmeos do tipo Room. Com essa definição, os Gêmeos Digitais do Azure permitirão que você crie contains relacionamentos de qualquer gêmeo do Andar para qualquer gêmeo do Quarto (incluindo gêmeos que são dos subtipos de Sala).

O resultado desse processo é um conjunto de nós (os gêmeos digitais) conectado por meio de bordas (as relações deles) em um grafo.

Visualização

O Azure Digital Twins Explorer é uma ferramenta visual para explorar os dados em seu grafo dos Gêmeos Digitais do Azure. Você pode usar o Explorer para exibir, consultar e editar seus modelos, gêmeos e relações.

Para ler sobre a ferramenta Azure Digital Twins Explorer, confira Azure Digital Twins Explorer. Para ver as etapas detalhadas sobre como usar seus recurso, confira Usar o Azure Digital Twins Explorer.

A visualização terá a seguinte aparência:

Criar usando as APIs

Esta seção mostra a aparência da criação de gêmeos digitais e as relações de um aplicativo cliente. Ele contém exemplos do SDK do .NET que usam as APIs DigitalTwins, para fornecer mais contexto sobre o que acontece dentro de cada um desses conceitos.

Criar gêmeos digitais

Abaixo há um snippet de código de cliente que usa as APIs DigitalTwins para criar uma instância de um gêmeo do tipo Room com um twinId que é definido durante a instalação.

É possível 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 uso, consulte Criar um gêmeo digital.

Observação

Embora as propriedades dos gêmeos sejam tratadas como opcionais e, portanto, não precisem ser inicializadas, todos os componentes no gêmeo precisam ser definidos quando ele é criado. Eles podem ser objetos vazios, mas os próprios componentes precisam existir.

Criar relações

Este é um código de cliente de exemplo que usa as APIs DigitalTwins para criar uma relação de um gêmeo digital (o gêmeo de "origem") com outro gêmeo digital (o gêmeo de "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 Importação de Trabalhos

Você pode carregar muitos gêmeos e relacionamentos em uma única chamada de API usando a API Importar Trabalhos. 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 DeleteRelationship do DigitalTwins e DeleRelacionamento do DigitalTwins (também disponíveis como comandos da CLI e chamadas do 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 de grafo

Os dados do gêmeo digital e os dados de relação são armazenados no formato JSON, ou seja, quando você consulta o grafo gêmeo na instância de Gêmeos Digitais do Azure, o resultado é uma representação JSON dos gêmeos digitais e das relações que você criou.

Formato JSON do gêmeo digital

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

Nome do campo	Descrição
$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	A 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 gravável opcional representando 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 de 31/05/2022 das APIs/SDKs dos Gêmeos Digitais do Azure, 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 até a coleção de relações. Esse campo estará ausente se o gêmeo digital não tiver nenhuma borda de relação de saída.
<component-name>	Um objeto JSON que contém os valores de propriedade e metadados do componente, semelhantes aos do objeto raiz. Esse objeto existirá mesmo que o componente não tenha nenhuma propriedade.
<component-name>.$metadata	As informações de metadados do componente, semelhantes ao $metadata do nível raiz
<component-name>.<property-name>	O valor da propriedade do componente em JSON (string, tipo de número ou objeto)

Este é um exemplo de um gêmeo digital formatado como um objeto JSON. Esse gêmeo tem duas propriedades, umidade 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 relação

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

Nome do campo	Descrição
$relationshipId	Uma cadeia de caracteres fornecida pelo usuário que representa a ID desta relação. Essa cadeia de caracteres é exclusiva no contexto do gêmeo digital de origem, o que também significa que sourceId + relationshipId é exclusivo no contexto da instância dos Gêmeos Digitais do Azure.
$etag	Campo HTTP padrão atribuído pelo servidor Web
$sourceId	A ID do gêmeo digital de origem
$targetId	A 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)

Este é 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óximas etapas

Veja como gerenciar elementos de grafo com as APIs dos Gêmeos Digitais do Azure:

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

Ou então, saiba como consultar o grafo de gêmeo dos Gêmeos Digitais do Azure para obter informações:

• Idioma de consulta