Gerenciar gêmeos digitais

As entidades são representadas no ambiente por gêmeos digitais. O gerenciamento de gêmeos digitais pode incluir criação, modificação e remoção.

Este artigo aborda o gerenciamento de gêmeos digitais. Para trabalhar com as relações e o grafo de gêmeo digital como um todo, confira Como gerenciar o grafo de gêmeo digital com relações.

Pré-requisitos

Para trabalhar com os Gêmeos Digitais do Azure neste artigo, você precisará ter uma instância dos Gêmeos Digitais do Azure e as permissões necessárias para usá-la. Se você já tiver uma instância dos Gêmeos Digitais do Azure configurada, use essa instância e vá direto para a próxima seção. Caso contrário, siga as instruções descritas em Configurar uma instância e uma autenticação. As instruções contêm informações que ajudarão você a verificar se cada etapa foi concluída com êxito.

Após configurar a instância, anote o nome do host da instância. Encontre o nome do host no portal do Azure.

Interfaces do desenvolvedor

Este artigo destaca como concluir diferentes operações de gerenciamento usando o SDK do .NET (C#). Você também pode criar essas mesmas chamadas de gerenciamento usando os SDKs de outras linguagens descritos em APIs e SDKs dos Gêmeos Digitais do Azure.

Outras interfaces de desenvolvedores que podem ser usadas para concluir essas operações incluem:

• Azure Digital Twins Explorer
• Chamadas API REST
• Comandos da CLI do Azure

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 um gêmeo digital

Para criar um gêmeo, use o método CreateOrReplaceDigitalTwinAsync() no cliente de serviço da seguinte maneira:

await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinId, initData);

Para criar um gêmeo digital, você precisa fornecer:

• Um valor de ID que você deseja atribuir ao gêmeo digital (define-se essa ID quando o gêmeo é criado)
• O modelo que deseja usar
• Qualquer inicialização desejada de dados gêmeos, incluindo...
  • Propriedades (inicialização opcional): você pode definir valores iniciais para as propriedades de um gêmeo digital, se desejar. As propriedades são tratadas como opcionais e podem ser definidas posteriormente, mas observe que elas não aparecerão como parte do gêmeo até que tenham sido definidas.
  • Componentes (inicialização obrigatória se estiverem presentes em um gêmeo): se o seu gêmeo contiver componentes, eles deverão ser inicializados quando o gêmeo for criado. Eles podem ser objetos vazios, mas os próprios componentes precisam existir.

O modelo e todos os valores de propriedade iniciais são fornecidos por meio do parâmetro initData, que é uma cadeia de caracteres JSON que contém os dados relevantes. Para obter mais informações sobre como estruturar o objeto, vá para a próxima seção.

Inicializar o modelo e as propriedades

Você pode inicializar as propriedades de um gêmeo no momento em que ele é criado.

A API de criação de gêmeo aceita um objeto que é serializado em uma descrição JSON válida das propriedades do gêmeo. Consulte Gêmeos digitais e o grafo de gêmeo para obter uma descrição do formato JSON para um gêmeo.

Você pode criar um objeto de dados para representar o gêmeo e os dados de propriedade. Você pode criar um objeto de parâmetro manualmente ou usando uma classe auxiliar já fornecida. Aqui está um exemplo de cada uma dessas ações.

Criar gêmeos usando dados criados manualmente

Sem o uso de classes auxiliares personalizadas, você pode representar as propriedades de um gêmeo em um Dictionary<string, object>, em que string é o nome da propriedade e object é um objeto que representa a propriedade e seu valor.

// 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}");
    }
}

Criar gêmeos com classe auxiliar

A classe auxiliar do BasicDigitalTwin permite que você armazene campos de propriedade em um objeto "gêmeo" diretamente. Talvez você ainda queira criar a lista de propriedades usando um Dictionary<string, object>, que pode ser adicionado ao objeto gêmeo como o seu CustomProperties diretamente.

string twinId = "myTwinID";
var initData = new BasicDigitalTwin
{
    Id = twinId,
    Metadata = { ModelId = "dtmi:example:Room;1" },
    // Initialize properties
    Contents =
    {
        { "Temperature", 25.0 },
        { "Humidity", 50.0 },
    },
};

await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinId, initData);

twin.Id = "myRoomId";

Criar gêmeos em massa com a API de Trabalhos de Importação

Você pode usar a API de Importação de Trabalhos para criar muitos gêmeos ao mesmo tempo em uma única chamada à API. Este método requer o uso do Armazenamento de Blobs do Azure e permissões de gravação em sua instância dos Gêmeos Digitais do Azure para gêmeos e trabalhos em massa.

Para importar gêmeos em massa, você precisa estruturar seus gêmeos (e quaisquer outros recursos incluídos no trabalho de importação em massa) como um arquivo NDJSON. A seção Twins vem após a seção Models (e antes da seção Relationships). Os gêmeos definidos no arquivo podem referenciar modelos definidos neste arquivo ou já presentes na instância e, opcionalmente, podem incluir a inicialização das propriedades do gêmeo.

Você pode exibir um arquivo de importação de exemplo e um projeto de exemplo para criar esses arquivos na introdução à API de Importação de Trabalhos.

Em seguida, o arquivo precisa ser carregado em um blob de acréscimo no Armazenamento de Blobs do Azure. Para obter instruções sobre como criar um contêiner de armazenamento do Azure, confira Criar um contêiner. Em seguida, carregue o arquivo usando seu método de carregamento preferido (algumas opções são o comando AzCopy, a CLI do Azure ou o portal do Azure).

Depois que o arquivo NDJSON for carregado no contêiner, obtenha sua URL dentro do contêiner de blob. Você usará esse valor posteriormente no corpo da chamada à API de importação em massa.

Aqui está uma captura de tela que mostra o valor da URL de um arquivo de blob no portal do Azure:

Em seguida, o arquivo pode ser usado em uma chamada à API de Importação de Trabalhos. Você fornece a URL de armazenamento de blobs do arquivo de entrada e uma nova URL de armazenamento de blobs para indicar onde deseja que o log de saída seja armazenado depois que ele for criado pelo serviço.

Obter dados para um gêmeo digital

Você pode acessar os detalhes de qualquer gêmeo digital chamando o método GetDigitalTwin() desta forma:

Response<BasicDigitalTwin> twinResponse = await client.GetDigitalTwinAsync<BasicDigitalTwin>(twinId);
twin = twinResponse.Value;

Essa chamada retorna dados de um gêmeo como um tipo de objeto fortemente tipado, como BasicDigitalTwin. BasicDigitalTwin é uma classe auxiliar de serialização incluída no SDK, que retorna os metadados e as propriedades do gêmeo principal em forma pré-preparada. Você sempre pode desserializar dados de gêmeos usando a biblioteca JSON de sua escolha, como System.Text.Json ou Newtonsoft.Json. No entanto, as classes auxiliares podem tornar mais conveniente o acesso básico a um gêmeo.

A classe auxiliar BasicDigitalTwin também fornece acesso a propriedades definidas no gêmeo por meio de um Dictionary<string, object>. Para listar as propriedades do gêmeo, você pode usar:

BasicDigitalTwin twin;
Response<BasicDigitalTwin> twinResponse = await client.GetDigitalTwinAsync<BasicDigitalTwin>(twinId);
twin = twinResponse.Value;
Console.WriteLine($"Model id: {twin.Metadata.ModelId}");
foreach (string prop in twin.Contents.Keys)
{
    if (twin.Contents.TryGetValue(prop, out object value))
        Console.WriteLine($"Property '{prop}': {value}");
}

Somente as propriedades que foram definidas pelo menos uma vez são retornadas quando você recupera um gêmeo com o método GetDigitalTwin().

Para recuperar vários gêmeos usando uma única chamada à API, confira os exemplos de API de Consulta em Consultar o grafo gêmeo.

Considere o seguinte modelo (escrito em DTDL (Linguagem de Definição de Gêmeos Digitais)) que define um moon:

{
    "@id": "dtmi:example:Moon;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "contents": [
        {
            "@type": "Property",
            "name": "radius",
            "schema": "double",
            "writable": true
        },
        {
            "@type": "Property",
            "name": "mass",
            "schema": "double",
            "writable": true
        }
    ]
}

O resultado de chamar object result = await client.GetDigitalTwinAsync("my-moon"); em um gêmeo do tipo Lua pode ter esta aparência:

{
  "$dtId": "myMoon-001",
  "$etag": "W/\"e59ce8f5-03c0-4356-aea9-249ecbdc07f9\"",
  "radius": 1737.1,
  "mass": 0.0734,
  "$metadata": {
    "$model": "dtmi:example:Moon;1",
    "radius": {
      "lastUpdateTime": "2022-12-06T20:00:32.8209188Z"
    },
    "mass": {
      "lastUpdateTime": "2022-12-04T12:04:43.3859361Z"
    }
  }
}

As propriedades definidas do gêmeo digital são retornadas como propriedades de nível superior no gêmeo digital. As informações de metadados ou do sistema que não fazem parte da definição DTDL são retornadas com um prefixo $. As propriedades de metadados incluem os seguintes valores:

• $dtId: ID do gêmeo digital na instância dos Gêmeos Digitais do Azure
• $etag: campo HTTP padrão atribuído pelo servidor Web. Ele é atualizado para um novo valor sempre que o gêmeo é atualizado, o que pode ser útil para determinar se o dado do gêmeo foi atualizado no servidor desde a última verificação. Você pode usar If-Match para executar atualizações e exclusões que só serão concluídas se a etag da entidade corresponder à etag fornecida. Para obter mais informações sobre essas operações, consulte a documentação para Atualização de DigitalTwins e para Exclusão de DigitalTwins.
• $metadata: um conjunto de propriedades de metadados, que pode incluir o seguinte:
  • $model, o DTMI do modelo do gêmeo digital.
  • lastUpdateTime para propriedades gêmeas. Este é um carimbo de data/hora que indica a data e hora em que os Gêmeos Digitais do Azure processaram a mensagem de atualização de propriedade
  • sourceTime para propriedades gêmeas. Esta é uma propriedade opcional e gravável que representa o carimbo de data/hora de quando a atualização da propriedade foi observada no mundo real.

Você pode ler mais sobre os campos contidos em um gêmeo digital no formato JSON do gêmeo digital. Você pode ler mais sobre as classes auxiliares de serialização como a BasicDigitalTwin em APIs e SDKs dos Gêmeos Digitais do Azure.

Exibir todos os gêmeos digitais

Para exibir todos os gêmeos digitais na instância, use uma consulta. Você pode executar uma consulta com as APIs de consulta ou os Comandos da CLI.

Aqui está o corpo da consulta básica que retorna uma lista de todos os gêmeos digitais na instância:

SELECT * FROM DIGITALTWINS

Atualizar um gêmeo digital

Para atualizar as propriedades de um gêmeo digital, escreva as informações que deseja substituir no formato de Patch JSON. Para obter uma lista completa de operações do patch JSON que podem ser usadas, incluindo replace, add e remove, confira Operações para patch JSON.

Depois de criar o documento de patch JSON que contém informações de atualização, passe o documento para o método UpdateDigitalTwin():

await client.UpdateDigitalTwinAsync(twinId, updateTwinData);

Uma chamada de patch única pode atualizar quantas propriedades de um gêmeo você desejar (inclusive todas elas). Se você precisar atualizar as propriedades de vários gêmeos, será necessária uma chamada de atualização separada para cada gêmeo.

Este é um exemplo de código de Patch JSON. Este documento substitui os valores de propriedade mass e radius do gêmeo digital no qual é aplicado. Esse exemplo mostra a operação replace do patch JSON, que substitui o valor de uma propriedade existente.

[
    {
      "op": "replace",
      "path": "/mass",
      "value": 0.0799
    },
    {
      "op": "replace",
      "path": "/radius",
      "value": 0.800
    }
  ]

Ao atualizar um gêmeo a partir de um projeto de código usando o SDK do .NET, você pode criar patches JSON usando o JsonPatchDocument do SDK do .NET do Azure. Aqui está um exemplo de criação de um documento de Patch JSON e do uso de UpdateDigitalTwin() no código do projeto.

var updateTwinData = new JsonPatchDocument();
updateTwinData.AppendAdd("/Temperature", 25.0);
updateTwinData.AppendAdd("/myComponent/Property", "Hello");
// Un-set a property
updateTwinData.AppendRemove("/Humidity");

await client.UpdateDigitalTwinAsync("myTwin", updateTwinData).ConfigureAwait(false);

Atualizar subpropriedades em componentes do gêmeo digital

Lembre-se de que um modelo pode conter componentes, o que permite que ele seja composto por outros modelos.

Para aplicar as propriedades de patch em um dos componentes do gêmeo digital, você pode usar a sintaxe de patch no Patch JSON:

[
  {
    "op": "replace",
    "path": "/mycomponentname/mass",
    "value": 0.0799
  }
]

Atualizar subpropriedades em propriedades de tipo de objeto

Os modelos podem conter propriedades que são de um tipo de objeto. Esses objetos podem ter suas próprias propriedades e talvez você queira atualizar uma dessas sub-propriedades pertencentes à propriedade do tipo objeto. Esse processo é semelhante ao processo de atualização de sub-propriedades em componentes, mas pode exigir algumas etapas adicionais.

Considere um modelo com uma propriedade de tipo de objeto, ObjectProperty. O ObjectProperty tem uma propriedade de cadeia de caracteres chamada StringSubProperty.

Quando um gêmeo é criado usando esse modelo, não é necessário criar uma instância do ObjectProperty no momento. Se não for criada uma instância da propriedade do objeto durante a criação do gêmeo, não haverá nenhum caminho padrão criado para acessar o ObjectProperty e o respectivo StringSubProperty para uma operação de patch. Você mesmo precisa adicionar o caminho ObjectProperty antes de atualizar suas propriedades.

Isso pode ser feito com uma operação add de patch JSON, desta forma:

[
  {
    "op": "add", 
    "path": "/ObjectProperty", 
    "value": {"StringSubProperty":"<string-value>"}
  }
]

... "value": {"StringSubProperty":"<string-value>", "Property2":"<property2-value>", ...}

Depois que isso tiver sido feito uma vez, existe um caminho para StringSubProperty e ele pode ser atualizado diretamente de agora em diante com uma operação replace típica:

[
  {
    "op": "replace",
    "path": "/ObjectProperty/StringSubProperty",
    "value": "<string-value>"
  }
]

Embora a primeira etapa não seja necessária nos casos em que ObjectProperty foi instanciado quando o gêmeo foi criado, é recomendável usá-la sempre que você atualizar uma sub-propriedade pela primeira vez, já que você pode nem sempre saber com certeza se a propriedade do objeto foi inicialmente instanciada ou não.

Atualizar um modelo de gêmeo digital

A função UpdateDigitalTwin() também pode ser usada para migrar um gêmeo digital para um modelo diferente.

Por exemplo, considere o seguinte documento de Patch JSON que substitui o campo $model dos metadados do gêmeo digital:

[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:example:foo;1"
  }
]

Esta operação só terá sucesso se o gêmeo digital que está sendo modificado pelo patch estiver em conformidade com o novo modelo.

Considere o seguinte exemplo:

1. Imagine um gêmeo digital com um modelo de foo_old. foo_old define uma massa de propriedade necessária.
2. O novo modelo foo_new define uma massa de propriedade e adiciona uma nova temperatura de propriedade necessária.
3. Depois do patch, o gêmeo digital deve ter a propriedade mass e a propriedade temperature.

O patch para essa situação precisa atualizar a propriedade temperature do gêmeo e do modelo desta forma:

[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:example:foo_new;1"
  },
  {
    "op": "add",
    "path": "/temperature",
    "value": 60
  }
]

Atualizar o sourceTime de uma propriedade

Opcionalmente, você pode decidir usar o campo sourceTime em propriedades gêmeas para registrar carimbos de data/hora para quando as atualizações de propriedade forem observadas no mundo real. Os Gêmeos Digitais do Azure dão suporte nativamente a sourceTime nos metadados para cada propriedade gêmea. O valor sourceTime deve estar em conformidade com o formato de data e hora ISO 8601. Para obter mais informações sobre esse campo e outros campos em gêmeos digitais, consulte Formato JSON de gêmeo digital.

A versão mínima da API REST estável para dar suporte a esse campo é a versão de 31-05-2022. Para trabalhar com esse campo usando os SDKs dos Gêmeos Digitais do Azure, recomendamos usar a versão mais recente do SDK para garantir que esse campo esteja incluído.

Aqui está um exemplo de um documento de patch JSON que atualiza o valor e o campo sourceTime de uma propriedade Temperature:

[
  {
    "op": "replace",
    "path": "/Temperature",
    "value": "22.3"
  },
  {
    "op": "replace",
    "path": "/$metadata/Temperature/sourceTime",
    "value": "2021-11-30T18:47:53.7648958Z"
  }
]

Para atualizar o campo sourceTime em uma propriedade que faz parte de um componente, inclua o componente no início do caminho. No exemplo acima, você faria isso alterarando o valor do caminho de /$metadata/Temperature/sourceTime para myComponent/$metadata/Temperature/sourceTime.

Lidar com chamadas de atualização conflitantes

Os Gêmeos Digitais do Azure garantem que todas as solicitações de entrada sejam processadas uma após a outra. Isso significa que, mesmo que várias funções tentem atualizar a mesma propriedade em um gêmeo ao mesmo tempo, não há necessidade de gravar um código de bloqueio explícito para lidar com o conflito.

Esse comportamento acontece em cada gêmeo.

Como exemplo, imagine um cenário no qual estas três chamadas chegam ao mesmo tempo:

• Gravar a propriedade A no Gêmeo1
• Gravar a propriedade B no Gêmeo1
• Gravar a propriedade A no Gêmeo2

As duas chamadas que modificam o Gêmeo1 são executadas uma após a outra e as mensagens de alteração são geradas para cada alteração. A chamada para modificar o Twin2 pode ser executada simultaneamente sem conflitos, assim que ela chegar.

Excluir um gêmeo digital

Você pode excluir gêmeos usando o método DeleteDigitalTwin(). No entanto, você só pode excluir um gêmeo quando ele não tiver mais relações. Exclua primeiro as relações de entrada e saída do gêmeo.

Aqui está um exemplo do código para excluir gêmeos e seus relacionamentos. A chamada do SDK DeleteDigitalTwin é realçada para esclarecer onde ela se encontra no contexto de exemplo mais amplo.

private static async Task CustomMethod_DeleteTwinAsync(DigitalTwinsClient client, string twinId)
{
    await CustomMethod_FindAndDeleteOutgoingRelationshipsAsync(client, twinId);
    await CustomMethod_FindAndDeleteIncomingRelationshipsAsync(client, twinId);
    try
    {
        await client.DeleteDigitalTwinAsync(twinId);
        Console.WriteLine("Twin deleted successfully");
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine($"*** Error:{ex.Message}");
    }
}

private static async Task CustomMethod_FindAndDeleteOutgoingRelationshipsAsync(DigitalTwinsClient client, string dtId)
{
    // Find the relationships for the twin

    try
    {
        // GetRelationshipsAsync will throw an error if a problem occurs
        AsyncPageable<BasicRelationship> rels = client.GetRelationshipsAsync<BasicRelationship>(dtId);

        await foreach (BasicRelationship rel in rels)
        {
            await client.DeleteRelationshipAsync(dtId, rel.Id).ConfigureAwait(false);
            Console.WriteLine($"Deleted relationship {rel.Id} from {dtId}");
        }
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine($"*** Error {ex.Status}/{ex.ErrorCode} retrieving or deleting relationships for {dtId} due to {ex.Message}");
    }
}

private static async Task CustomMethod_FindAndDeleteIncomingRelationshipsAsync(DigitalTwinsClient client, string dtId)
{
    // Find the relationships for the twin

    try
    {
        // GetRelationshipsAsync will throw an error if a problem occurs
        AsyncPageable<IncomingRelationship> incomingRels = client.GetIncomingRelationshipsAsync(dtId);

        await foreach (IncomingRelationship incomingRel in incomingRels)
        {
            await client.DeleteRelationshipAsync(incomingRel.SourceId, incomingRel.RelationshipId).ConfigureAwait(false);
            Console.WriteLine($"Deleted incoming relationship {incomingRel.RelationshipId} from {dtId}");
        }
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine($"*** Error {ex.Status}/{ex.ErrorCode} retrieving or deleting incoming relationships for {dtId} due to {ex.Message}");
    }
}

Excluir todos os gêmeos digitais

Para obter um exemplo de como excluir todos os gêmeos de uma vez, baixe o aplicativo de amostra usado em Explorar os conceitos básicos com um aplicativo cliente de amostra. O arquivo CommandLoop.cs faz isso em uma função CommandDeleteAllTwins().

Exemplo de código de gêmeo digital executável

Você pode usar o exemplo de código executável abaixo para criar, atualizar os detalhes e excluir um gêmeo.

Configurar arquivos de projeto de exemplo

O snippet usa uma definição de modelo de exemplo, Room.json. Para baixar o arquivo de modelo para que você possa usá-lo no seu código, use este link para acessar diretamente o arquivo no GitHub. Depois, clique com o botão direito do mouse em qualquer lugar na tela, selecione Salvar como no menu ativado pelo botão direito do mouse do navegador e use a janela Salvar como para salvar o arquivo como Room.json.

Depois, crie um projeto de aplicativo de console no Visual Studio ou no editor de sua preferência.

Copie o seguinte código do exemplo executável no seu projeto:

using System;
using System.Threading.Tasks;
using System.Collections.Generic;
using Azure;
using Azure.DigitalTwins.Core;
using Azure.Identity;
using System.IO;

namespace DigitalTwins_Samples
{
    class TwinOperationsSample
    {
        public static async Task Main(string[] args)
        {
            Console.WriteLine("Hello World!");

            // Create the Azure Digital Twins client for API calls
            string adtInstanceUrl = "https://<your-instance-hostname>";
            var credentials = new DefaultAzureCredential();
            var client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credentials);
            Console.WriteLine($"Service client created – ready to go");

            // Upload models
            Console.WriteLine($"Upload a model");
            string dtdl = File.ReadAllText("<path-to>/Room.json");
            var models = new List<string> { dtdl };
            // Upload the model to the service
            await client.CreateModelsAsync(models);

            // Create new digital twin
            // <CreateTwin_withHelper>
            string twinId = "myTwinID";
            var initData = new BasicDigitalTwin
            {
                Id = twinId,
                Metadata = { ModelId = "dtmi:example:Room;1" },
                // Initialize properties
                Contents =
                {
                    { "Temperature", 25.0 },
                    { "Humidity", 50.0 },
                },
            };

            // <CreateTwinCall>
            await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinId, initData);
            // </CreateTwinCall>
            // </CreateTwin_withHelper>
            Console.WriteLine("Twin created successfully");

            //Print twin
            Console.WriteLine("--- Printing twin details:");
            await CustomMethod_FetchAndPrintTwinAsync(twinId, client);
            Console.WriteLine("--------");

            //Update twin data
            var updateTwinData = new JsonPatchDocument();
            updateTwinData.AppendAdd("/Temperature", 30.0);
            // <UpdateTwinCall>
            await client.UpdateDigitalTwinAsync(twinId, updateTwinData);
            // </UpdateTwinCall>
            Console.WriteLine("Twin properties updated");
            Console.WriteLine();

            //Print twin again
            Console.WriteLine("--- Printing twin details (after update):");
            await CustomMethod_FetchAndPrintTwinAsync(twinId, client);
            Console.WriteLine("--------");
            Console.WriteLine();

            //Delete twin
            await CustomMethod_DeleteTwinAsync(client, twinId);
        }

        private static async Task<BasicDigitalTwin> CustomMethod_FetchAndPrintTwinAsync(string twinId, DigitalTwinsClient client)
        {
            // <GetTwin>
            BasicDigitalTwin twin;
            // <GetTwinCall>
            Response<BasicDigitalTwin> twinResponse = await client.GetDigitalTwinAsync<BasicDigitalTwin>(twinId);
            twin = twinResponse.Value;
            // </GetTwinCall>
            Console.WriteLine($"Model id: {twin.Metadata.ModelId}");
            foreach (string prop in twin.Contents.Keys)
            {
                if (twin.Contents.TryGetValue(prop, out object value))
                    Console.WriteLine($"Property '{prop}': {value}");
            }
            // </GetTwin>

            return twin;
        }

        // <DeleteTwin>
        private static async Task CustomMethod_DeleteTwinAsync(DigitalTwinsClient client, string twinId)
        {
            await CustomMethod_FindAndDeleteOutgoingRelationshipsAsync(client, twinId);
            await CustomMethod_FindAndDeleteIncomingRelationshipsAsync(client, twinId);
            try
            {
                await client.DeleteDigitalTwinAsync(twinId);
                Console.WriteLine("Twin deleted successfully");
            }
            catch (RequestFailedException ex)
            {
                Console.WriteLine($"*** Error:{ex.Message}");
            }
        }

        private static async Task CustomMethod_FindAndDeleteOutgoingRelationshipsAsync(DigitalTwinsClient client, string dtId)
        {
            // Find the relationships for the twin

            try
            {
                // GetRelationshipsAsync will throw an error if a problem occurs
                AsyncPageable<BasicRelationship> rels = client.GetRelationshipsAsync<BasicRelationship>(dtId);

                await foreach (BasicRelationship rel in rels)
                {
                    await client.DeleteRelationshipAsync(dtId, rel.Id).ConfigureAwait(false);
                    Console.WriteLine($"Deleted relationship {rel.Id} from {dtId}");
                }
            }
            catch (RequestFailedException ex)
            {
                Console.WriteLine($"*** Error {ex.Status}/{ex.ErrorCode} retrieving or deleting relationships for {dtId} due to {ex.Message}");
            }
        }

        private static async Task CustomMethod_FindAndDeleteIncomingRelationshipsAsync(DigitalTwinsClient client, string dtId)
        {
            // Find the relationships for the twin

            try
            {
                // GetRelationshipsAsync will throw an error if a problem occurs
                AsyncPageable<IncomingRelationship> incomingRels = client.GetIncomingRelationshipsAsync(dtId);

                await foreach (IncomingRelationship incomingRel in incomingRels)
                {
                    await client.DeleteRelationshipAsync(incomingRel.SourceId, incomingRel.RelationshipId).ConfigureAwait(false);
                    Console.WriteLine($"Deleted incoming relationship {incomingRel.RelationshipId} from {dtId}");
                }
            }
            catch (RequestFailedException ex)
            {
                Console.WriteLine($"*** Error {ex.Status}/{ex.ErrorCode} retrieving or deleting incoming relationships for {dtId} due to {ex.Message}");
            }
        }
        // </DeleteTwin>

    }
}

Configurar o projeto

Conclua as seguintes etapas para configurar o código do projeto:

1. Adicione o arquivo Room.json que você já baixou no projeto e substitua o espaço reservado <path-to> no código para informar ao programa onde encontrá-lo.

2. Substitua o espaço reservado <your-instance-hostname> pelo nome do host da instância dos Gêmeos Digitais do Azure.

3. Adicione duas dependências ao projeto necessárias para trabalhar com os Gêmeos Digitais do Azure. A primeira é o pacote do SDK dos Gêmeos Digitais do Azure para .NET e a segunda fornece ferramentas para ajudar com a autenticação no Azure.

   dotnet add package Azure.DigitalTwins.Core
   dotnet add package Azure.Identity
   

Você também precisa configurar credenciais locais se quiser executar o exemplo diretamente. A próxima seção descreve isso.

Configurar credenciais locais do Azure

Quando você o executa em seu computador local, este exemplo usa o DefaultAzureCredential (parte da biblioteca Azure.Identity) para autenticar usuários com uma instância dos Gêmeos Digitais do Azure. Para obter mais informações sobre as diferentes maneiras como um aplicativo cliente pode se autenticar com os Gêmeos Digitais do Azure, confira Escrever o código de autenticação do aplicativo.

Com DefaultAzureCredential, o exemplo pesquisará as credenciais no ambiente local, como uma conexão do Azure em uma DefaultAzureCredential local ou no Visual Studio ou Visual Studio Code. Por isso, será necessário entrar no Azure localmente por meio de um desses mecanismos para configurar as credenciais do exemplo.

Caso esteja usando o Visual Studio ou o Visual Studio Code para executar exemplos de código, verifique se está conectado a esse editor com as mesmas credenciais do Azure que deseja usar para acessar a instância dos Gêmeos Digitais do Azure. Se estiver usando uma janela da CLI local, execute o comando az login para entrar na sua conta do Azure. Depois disso, quando você executar o exemplo de código, será autenticado automaticamente.

Execute o exemplo

Agora que a instalação está concluída, você pode executar o projeto de código de exemplo.

Aqui está a saída do console do programa acima:

Próximas etapas

Consulte como criar e gerenciar relações entre os gêmeos digitais:

• Gerenciar o grafo gêmeo e as relações