Gerenciar modelos dos Gêmeos Digitais do Azure

Este artigo descreve como gerenciar os modelos em sua instância dos Gêmeos Digitais do Azure. As operações de gerenciamento incluem o carregamento, a validação, a recuperação e a exclusão de modelos.

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 modelos

Você pode criar seus próprios modelos do zero ou usar ontologias existentes que estão disponíveis para o seu setor.

Modelos de autor

Os modelos para Gêmeos Digitais do Azure são gravados em DTDL e salvos como arquivos JSON. Também há uma extensão DTDL disponível para o Visual Studio Code, que fornece a validação de sintaxe e outros recursos para facilitar a gravação de documentos DTDL.

Considere um exemplo em que um hospital deseja representar os quartos digitalmente. Cada quarto contém um dispenser de sabão inteligente para monitorar a lavagem de mãos e sensores para monitorar o tráfego no quarto.

A primeira etapa da solução é criar modelos para representar os aspectos do hospital. O quarto de um paciente nesse cenário pode ser descrito da seguinte maneira:

{
    "@id": "dtmi:com:contoso:PatientRoom;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Patient Room",
    "contents": [
      {
        "@type": "Property",
        "name": "visitorCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashPercentage",
        "schema": "double"
      },
      {
        "@type": "Relationship",
        "name": "hasDevices"
      }
    ]
  }

Observação

Este é um corpo de exemplo para um arquivo JSON no qual um modelo é definido e salvo, a ser carregado como parte de um projeto cliente. Por outro lado, a chamada à API REST usa uma matriz de definições de modelo como a exibida acima (que é mapeada para um IEnumerable<string> no SDK do .NET). Portanto, para usar esse modelo diretamente na API REST, coloque-o entre colchetes.

Esse modelo define um nome e ID exclusivo para a sala dos pacientes e as propriedades para representar a contagem de visitantes e o status da lavagem de mãos. Esses contadores serão atualizados a partir de sensores de movimento e dispensadores de sabão inteligentes e serão usados juntos para calcular uma handwash percentage propriedade. O modelo também define uma relação hasDevices, que será usada para conectar todos os gêmeos digitais com base nesse modelo Room aos dispositivos propriamente ditos.

Observação

Há alguns recursos do DTDL aos quais os Gêmeos Digitais do Azure atualmente não oferecem suporte, incluindo o writable atributo em propriedades e relações, minMultiplicity e maxMultiplicity para relações. Para obter mais informações, confira as Notas da DTDL específicas do serviço.

Seguindo esse método, você pode definir modelos para as enfermarias, zonas ou o próprio hospital do hospital.

Se o seu objetivo é criar um conjunto de modelos abrangente que descreva seu domínio do setor, considere se há uma ontologia do setor existente que você possa usar para facilitar a criação de modelos. A próxima seção descreve ontologias do setor com mais detalhes.

Usar ontologias padrão do setor existentes

Uma ontologia é um conjunto de modelos que descrevem de forma abrangente um determinado domínio, como manufatura, estruturas de edifícios, sistemas IoT, cidades inteligentes, redes de energia, conteúdo da web e muito mais.

Se sua solução for para um determinado setor que usa qualquer tipo de padrão de modelagem, considere começar com um conjunto pré-existente de modelos projetados para seu setor em vez de projetar seus modelos do zero. A Microsoft fez parceria com especialistas do domínio para criar ontologias de modelo DTDL com base nos padrões do setor, para ajudar a minimizar a reinvenção e incentivar a consistência e a simplicidade em todas as soluções do setor. Você pode saber mais sobre essas ontologias, incluindo como usá-las e quais estão disponíveis no momento, em O que é uma ontologia?.

Validar sintaxe

Depois de criar um modelo, é recomendável validar seus modelos offline antes de carregá-los na instância dos Gêmeos Digitais do Azure.

Para ajudá-lo a validar seus modelos, uma biblioteca de análise DTDL do lado do cliente .NET é fornecida no NuGet: DTDLParser. Você pode usar a biblioteca do analisador diretamente em seu código C#. Você também pode exibir o uso de exemplo do analisador no DTDLParserResolveSample no GitHub.

Carregar modelos

Depois de criar os modelos, carregue-os na instância dos Gêmeos Digitais do Azure.

Quando estiver pronto para carregar um modelo, use o seguinte snippet de código para o .NET SDK:

// 'client' is an instance of DigitalTwinsClient
// Read model file into string (not part of SDK)
// fileName is the name of the JSON model file
string dtdl = File.ReadAllText(fileName);
await client.CreateModelsAsync(new[] { dtdl });

No carregamento, os arquivos de modelo são validados pelo serviço.

Normalmente, você precisará carregar mais de um modelo para o serviço. Há várias maneiras de carregar vários modelos de uma só vez em uma única transação. Para ajudá-lo a escolher uma estratégia, considere o tamanho do conjunto de modelos ao continuar no restante desta seção.

Carregar pequenos conjuntos de modelos

Para conjuntos de modelos menores, você pode carregar vários modelos de uma só vez usando chamadas de API individuais. Você pode verificar o limite atual de quantos modelos podem ser carregados em uma única chamada de API nos limites dos Gêmeos Digitais do Azure.

Caso esteja usando o SDK, você poderá carregar vários arquivos de modelo com o método CreateModels desta forma:

var dtdlFiles = Directory.EnumerateFiles(sourceDirectory, "*.json");

var dtdlModels = new List<string>();
foreach (string fileName in dtdlFiles)
{
    // Read model file into string (not part of SDK)
    string dtdl = File.ReadAllText(fileName);
    dtdlModels.Add(dtdl);
}
await client.CreateModelsAsync(dtdlModels);

Se você estiver usando as APIs REST ou a CLI do Azure, poderá carregar vários modelos colocando várias definições de modelo em um único arquivo JSON para ser carregado juntos. Nesse caso, os modelos devem ser colocados em uma matriz JSON dentro do arquivo, conforme o exemplo a seguir:

[
    {
      "@id": "dtmi:com:contoso:Planet;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    },
    {
      "@id": "dtmi:com:contoso:Moon;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    }
]

Carregar grandes conjuntos de modelos com a API Importar Trabalhos

Para grandes conjuntos de modelos, você pode usar a API Importar Trabalhos para carregar vários modelos de uma só vez em uma única chamada de API . A API pode aceitar simultaneamente até o limite de Gêmeos Digitais do Azure para o número de modelos em uma instância e reordena automaticamente os modelos, se necessário, para resolver dependências entre eles. Esse método requer o uso do Armazenamento de Blobs do Azure, bem como permissões de gravação em sua instância de Gêmeos Digitais do Azure para modelos e trabalhos em massa.

Dica

A API de Trabalhos de Importação também permite que gêmeos e relacionamentos sejam importados na mesma chamada, para criar todas as partes de um gráfico de uma só vez. Para obter mais informações sobre esse processo, consulte Carregar modelos, gêmeos e relacionamentos em massa com a API Importar Trabalhos.

Para importar modelos em massa, você precisará estruturar seus modelos (e quaisquer outros recursos incluídos no trabalho de importação em massa) como um arquivo NDJSON . A Models seção vem imediatamente após Header a seção, tornando-se a primeira seção de dados do gráfico no arquivo. Você pode exibir um arquivo de importação de exemplo e um projeto de exemplo para criar esses arquivos na introdução da API de Trabalhos de Importação.

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, consulte 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 tiver sido carregado no contêiner, obtenha sua URL dentro do contêiner de blob. Você usará esse valor posteriormente no corpo da chamada de API de importação em massa.

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

Em seguida, o arquivo pode ser usado em uma chamada de API de Trabalhos de Importação. Você fornecerá a URL de armazenamento de blob do arquivo de entrada, bem como uma nova URL de armazenamento de blob para indicar onde você deseja que o log de saída seja armazenado quando for criado pelo serviço.

Recuperar modelos

Você pode listar e recuperar modelos armazenados em sua instância dos Gêmeos Digitais do Azure.

Suas opções incluem:

• Recuperar um único modelo
• Recuperar todos os modelos
• Recuperar os metadados e as dependências para modelos

Estas são chamadas de exemplo:

// 'client' is a valid DigitalTwinsClient object

// Get a single model, metadata and data
Response<DigitalTwinsModelData> md1 = await client.GetModelAsync("<model-Id>");
DigitalTwinsModelData model1 = md1.Value;

// Get a list of the metadata of all available models; print their IDs
AsyncPageable<DigitalTwinsModelData> md2 = client.GetModelsAsync();
await foreach (DigitalTwinsModelData md in md2)
{
    Console.WriteLine($"Type ID: {md.Id}");
}

// Get models and metadata for a model ID, including all dependencies (models that it inherits from, components it references)
AsyncPageable<DigitalTwinsModelData> md3 = client.GetModelsAsync(new GetModelsOptions { IncludeModelDefinition = true });

Todas as chamadas de SDK para recuperar modelos retornam objetos DigitalTwinsModelData. DigitalTwinsModelData contém metadados sobre o modelo armazenado na instância dos Gêmeos Digitais do Azure, como nome, DTMI e data de criação do modelo. O objeto DigitalTwinsModelData também inclui o próprio modelo como opcional. Significa que, dependendo dos parâmetros, você pode usar as chamadas de recuperação para recuperar apenas os metadados (o que é útil em cenários em que você deseja exibir uma lista de ferramentas disponíveis da interface do usuário, por exemplo) ou para o modelo inteiro.

A chamada RetrieveModelWithDependencies retorna não apenas o modelo solicitado, mas também todos os modelos dos quais o modelo solicitado depende.

Os modelos não são retornados necessariamente no mesmo formulário de documento em que foram carregados. Os Gêmeos Digitais do Azure só garantem que o formulário de retorno será semanticamente equivalente.

Atualizar modelos

Esta seção descreve considerações e estratégias para atualizar modelos.

Antes de atualizar: pense no contexto de toda a solução

Antes de atualizar os seus modelos, recomendamos pensar holisticamente sobre toda a solução e o impacto das alterações que você está prestes a fazer. Os modelos em uma solução Gêmeos Digitais do Azure geralmente são interconectados, portanto, é importante estar ciente das alterações em cascata em que a atualização de um modelo requer a atualização de vários outros. A atualização de modelos afetará os gêmeos que usam os modelos e também poderá afetar a entrada e o código de processamento, os aplicativos cliente e os relatórios automatizados.

Veja algumas recomendações para ajudar a gerenciar sem dificuldades suas transições de modelo:

• Em vez de pensar nos modelos como entidades separadas, considere a evolução de todo o conjunto de modelos quando apropriado para manter os modelos e as suas relações atualizadas.
• Trate os modelos como código-fonte e gerencie-os no controle do código-fonte. Tenha o mesmo rigor e atenção em modelos e alterações de modelo aplicados a outros códigos na solução.

Quando estiver tudo pronto para continuar com o processo de atualização dos modelos, o restante desta seção descreve as estratégias que podem ser usadas para implementar as atualizações.

Estratégias para atualizar modelos

Depois que um modelo é carregado em sua instância de Gêmeos Digitais do Azure, a interface do modelo se torna imutável, o que significa que não há nenhuma "edição" tradicional de modelos. Os Gêmeos Digitais do Azure também não permitem o um novo upload do mesmo modelo exato enquanto um modelo correspondente já está presente na instância.

Em vez disso, se você quiser fazer alterações em um modelo, como atualizar displayName ou description, ou adicionar e remover propriedades, precisará substituir o modelo original.

Há duas estratégias para escolher ao substituir um modelo:

• Estratégia 1: Fazer upload da nova versão do modelo: faça upload do modelo com um novo número de versão e atualize seus gêmeos para usar esse novo modelo. As versões novas e antigas do modelo existirão na sua instância até que você exclua uma.
  • Use essa estratégia quando quiser atualizar apenas alguns dos gêmeos que usam o modelo ou quando quiser garantir que os gêmeos permaneçam em conformidade com seus modelos e que podem ser escritos durante a transição do modelo.
• Estratégia 2: excluir o modelo antigo e fazer um novo upload: exclua o modelo original e faça upload do novo modelo com o mesmo nome e ID (valor DTMI) em substituição. Substitui completamente o modelo antigo pelo novo.
  • Use essa estratégia quando quiser atualizar todos os gêmeos que usam esse modelo de uma só vez, além de todo o código que reage aos modelos. Se a atualização do modelo contiver uma alteração interruptiva com a atualização do modelo, os gêmeos não serão compatíveis com seus modelos por um breve período durante a transição do modelo antigo para o novo. Isso significa que eles não poderão ser atualizados até que o novo modelo seja carregado e os gêmeos sejam compatíveis com ele.

Observação

Não recomendamos fazer alterações interruptivas fora do desenvolvimento.

Continue para as próximas seções para ler mais sobre cada opção de estratégia em detalhes.

Estratégia 1: Fazer upload da nova versão do modelo

Essa opção envolve criar uma nova versão do modelo e fazer upload dela para sua instância.

Essa operação não substitui versões anteriores do modelo, portanto, várias versões do modelo coexistirão em sua instância até que você as remova. Como a nova versão do modelo e a versão do modelo antigo coexistem, os gêmeos podem usar tanto a versão nova quanto a mais antiga, o que significa que carregar uma nova versão de um modelo não afeta automaticamente os gêmeos existentes. Os gêmeos existentes permanecerão como instâncias da versão antiga do modelo e você poderá atualizar esses gêmeos para a nova versão do modelo ao aplicat um patch.

Para usar essa estratégia, siga as etapas abaixo.

1. Criar e fazer upload da nova versão do modelo

Para criar uma versão de um modelo existente, comece com o DTDL do modelo original. Atualize, adicione ou remova os campos que você deseja mudar.

Em seguida, marque esse modelo como uma versão mais recente atualizando o campo id do modelo. A última seção da ID do modelo depois do ; representa o número do modelo. Para indicar que esse modelo é uma versão mais atualizada, aumente o número no final do valor id para um que seja maior que o número de versão atual.

Por exemplo, se a ID do modelo anterior for esta:

"@id": "dtmi:com:contoso:PatientRoom;1",

A versão 2 desse modelo pode ser esta:

"@id": "dtmi:com:contoso:PatientRoom;2",

Faça upload da nova versão do modelo em sua instância.

Essa versão do modelo vai estar disponível na instância para ser usada para os gêmeos digitais. Isso não substitui as versões anteriores do modelo, portanto, várias versões coexistirão na instância.

2. Atualizar elementos de grafo conforme necessário

Em seguida, atualize os gêmeos e as relações na sua instância para usar a nova versão do modelo em vez da antiga.

Siga as instruções a seguir para atualizar gêmeos e atualizar relações. A operação de patch para atualizar o modelo de um gêmeo será parecida com isto:

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

Importante

Ao atualizar gêmeos, use o mesmo patch para atualizar o ID do modelo (para a nova versão do modelo) e os campos que precisam ser alterados no gêmeo para torná-lo compatível com o novo modelo.

Pode ser necessário atualizar as relações e outros modelos na sua instância que referenciam esse modelo para fazer com que eles se refiram à nova versão do modelo. Você precisará fazer outra operação de atualização de modelo para atingir essa finalidade, portanto, retorne ao início desta seção e repita o processo para outros modelos que precisem de atualização.

3. (Opcional) Desativar ou excluir a versão antiga do modelo

Se você não estiver mais usando a versão antiga do modelo, poderá desativar o modelo mais antigo. Essa ação permite que o modelo continue existindo na instância sem poder ser usado para criar novos gêmeos digitais.

Você também poderá excluir completamente o modelo antigo se não quiser mais ele na instância.

Os links das seções acima contêm exemplo de código e considerações para desativação e exclusão de modelos.

Estratégia 2: Excluir o modelo antigo e recarregar

Em vez de incrementar a versão de um modelo, você pode excluí-lo e recarregar um modelo editado para a instância.

Gêmeos Digitais do Azure não se lembram de que o modelo antigo foi carregado, portanto, essa ação será igual a carregar um modelo totalmente novo. Os gêmeos que usam o modelo mudam automaticamente para a nova definição assim que ela estiver disponível. Dependendo das diferenças entre a nova definição e a antiga, esses gêmeos podem ter propriedades e relações que correspondem à definição excluída e que não são válidas com a nova. Portanto, talvez seja necessário corrigi-las para que permaneçam válidas.

Para usar essa estratégia, siga as etapas abaixo.

1. Excluir modelo antigo

Como Gêmeos Digitais do Azure não permitem dois modelos com o mesma ID, comece com a exclusão do modelo original da sua instância.

Observação

Se você tiver outros modelos que dependem desse modelo (por herança ou componentes), precisará remover essas referências antes de excluir o modelo. Você pode atualizar primeiro esses modelos dependentes para remover temporariamente as referências ou excluí-los e recarregá-los em uma etapa posterior.

Siga as instruções a seguir para excluir o modelo original. Essa ação deixará os gêmeos que usavam esse modelo temporariamente "órfãos", pois o modelo que usavam não existe mais. Esse estado será reparado na próxima etapa ao recarregar o modelo atualizado.

2. Criar e carregar novos modelos

Comece pelo DTDL do modelo original. Atualize, adicione ou remova os campos que você deseja mudar.

Em seguida, carregue o modelo na instância, como se fosse um novo modelo sendo carregado pela primeira vez.

3. Atualizar elementos de grafo conforme necessário

Agora que o novo modelo foi carregado para substituir o antigo, os gêmeos no seu grafo começarão a usar automaticamente a nova definição de modelo depois que o cache em sua instância vencer e redefinir. Esse processo pode levar de 10 a 15 minutos ou mais, dependendo do tamanho do grafo. Depois disso, as propriedades novas e alteradas no seu modelo devem estar acessíveis e as propriedades removidas não estarão mais acessíveis.

Observação

Se você removeu outros modelos dependentes para excluir o modelo original, recarregue-os agora após a redefinição do cache. Se você atualizou os modelos dependentes para remover temporariamente as referências ao modelo original, atualize-as novamente para recuperar a referência.

Em seguida, atualize os gêmeos e as relações em sua instância para que suas propriedades corresponderem às propriedades definidas pelo novo modelo. Antes da conclusão dessa etapa, os gêmeos que não corresponderem ao modelo ainda poderão ser lidos, mas não gravados. Para obter mais informações sobre o estado dos gêmeos sem um modelo válido, consulte Gêmeos sem modelos.

Há duas maneiras de atualizar os gêmeos e as relações para o novo modelo para que eles voltem a ser graváveis:

• Corrigir os gêmeos e as relações conforme necessário para que se ajustem ao novo modelo. Siga as instruções a seguir para atualizar gêmeos e atualizar relações.
  • Se você adicionou propriedades : a atualização de gêmeos e relações para que os novos valores não sejam necessários, pois os gêmeos que não têm os novos valores ainda serão gêmeos válidos. Você pode corrigi-los da maneira que quiser para adicionar valores às novas propriedades.
  • Se você removeu as propriedades: é necessário corrigir os gêmeos para remover as propriedades que se tornam inválidas com o novo modelo.
  • Se você atualizou as propriedades: é necessário aplicar patch aos gêmeos para atualizar os valores das propriedades alteradas para serem válidos com o novo modelo.
• Exclua gêmeos e relações que usam o modelo e recrie-os. Siga as instruções a seguir para excluir gêmeos e recriar gêmeos, e excluir relações e recriar relações.
  • Se estiver fazendo muitas alterações no modelo, você poderá querer fazer essa operação, e será difícil atualizar os gêmeos existentes para corresponder a ele. No entanto, pode ser complicado recriar se você tiver muitos gêmeos interconectados por muitas relações.

Remover modelos

Os modelos podem ser removidos do serviço de uma destas duas maneiras:

• Desativação: depois que um modelo é desativado, você não pode mais usá-lo para criar Gêmeos Digitais. Os gêmeos digitais existentes que já usam esse modelo não são afetados e ainda podem ser atualizados com alterações de propriedade e adição ou exclusão de relações.
• Exclusão: essa operação removerá completamente o modelo da solução. Os gêmeos que usam esse modelo não estarão mais associados a nenhum modelo válido e serão tratados como se não tivessem um modelo. Você ainda pode ler esses gêmeos, mas não pode fazer nenhuma atualização até que eles sejam reatribuídos a um modelo diferente.

Essas operações são recursos separados e não afetam uns aos outros, embora possam ser usados juntos para remover um modelo gradualmente.

Observação

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

Desativação

Para desativar um modelo, você pode usar o método DecommissionMode do SDK:

// 'client' is a valid DigitalTwinsClient
await client.DecommissionModelAsync(dtmiOfPlanetInterface);
// Write some code that deletes or transitions digital twins
//...

Você também pode desativar um modelo usando a chamada à API REST DigitalTwinModels Update. A propriedade decommissioned é a única que pode ser substituída por essa chamada à API. O documento de patch JSON terá esta aparência:

[
  {
    "op": "replace",
    "path": "/decommissioned",
    "value": true
  }
]

O status de desativação de um modelo é incluído nos ModelData registros retornados pelas APIs de recuperação de modelo.

Exclusão

Você pode excluir todos os modelos da instância ao mesmo tempo ou um de cada vez.

Para ver um exemplo de como excluir todos os modelos ao mesmo tempo, consulte o repositório de amostras de ponta a ponta para Gêmeos Digitais do Azure no GitHub. O arquivo CommandLoop.cs contém uma função CommandDeleteAllModels com código para excluir todos os modelos na instância.

Para excluir um modelo individual, siga as instruções e considerações no restante desta seção.

Antes da exclusão: requisitos de exclusão

Normalmente, os modelos podem ser excluídos a qualquer momento.

A exceção são os modelos que tem outros modelos dependentes, com uma relação extends ou como um componente. Por exemplo, se um modelo de ConferenceRoom estende um modelo de Room e tem um modelo de ACUnit como componente, você não pode excluir o Room ou o ACUnit até que o ConferenceRoom remova essas respectivas referências.

É possível fazer isso atualizando o modelo dependente para remover as dependências ou excluindo completamente o modelo dependente.

Durante a exclusão: processo de exclusão

Mesmo que um modelo atenda aos requisitos para ser excluído imediatamente, primeiro percorra algumas etapas para evitar consequências indesejadas para os gêmeos deixados para trás. Estas são algumas etapas que podem ajudar a gerenciar o processo:

1. Desativar o modelo
2. Aguarde alguns minutos para certificar-se de que o serviço processou todas as solicitações de criação de gêmeos enviadas antes da desativação
3. Consulte os gêmeos por modelo para ver todos que estão usando o modelo desativado
4. Exclua os gêmeos que não são mais necessários ou corrija-os para um novo modelo, se necessário. Você pode deixá-los sem alteração; nesse caso, eles vão se tornar gêmeos sem modelos depois que o modelo for excluído. Consulte a próxima seção para as implicações desse status.
5. Aguarde alguns minutos para se certificar de que as alterações tenham sido completadas
6. Excluir o modelo

Para excluir um modelo, você pode usar a chamada DeleteModel do SDK:

// 'client' is a valid DigitalTwinsClient
await client.DeleteModelAsync(IDToDelete);

Você também pode excluir um modelo com a chamada à API REST DigitalTwinModels Delete.

Após a exclusão: gêmeos sem modelos

Depois que um modelo é excluído, todos os gêmeos digitais que estavam usando o modelo agora são considerados sem um modelo. Não há nenhuma consulta que possa fornecer uma lista de todos os gêmeos com esse status, embora seja possível consultar os gêmeos pelo modelo excluído para saber quais foram afetados.

Está é uma visão geral do que você pode e não pode fazer com os gêmeos que não têm um modelo.

O que você pode fazer:

• Consultar o gêmeo
• Ler propriedades
• Ler as relações de saída
• Adicionar e excluir relacionamentos de entrada (como em, outros gêmeos ainda podem formar relacionamentos com esse gêmeo)
  • O target na definição de relação ainda pode refletir o DTMI do modelo excluído. Uma relação sem um destino definido também pode funcionar.
• Exclusão de relacionamentos
• Excluir o gêmeo

Coisas que você não pode fazer:

• Editar relações de saída (relações deste gêmeo para outros gêmeos)
• Editar propriedades

Após a exclusão: recarregar um modelo

Depois que um modelo foi excluído, você pode carregar um novo modelo com a mesma ID daquele que você excluiu. Isto é o que acontece nesse caso.

• Da perspectiva do armazenamento de soluções, essa operação é igual a carregar um modelo completamente novo. O serviço não se lembra de que o antigo já foi carregado.
• Se houver qualquer gêmeo restante no grafo que referencia o modelo excluído, eles não serão mais órfãos. Essa ID de modelo é válida de novo com a outra definição. No entanto, se a nova definição para o modelo for diferente da definição excluída, os gêmeos podem ter propriedades e relações que correspondam à definição excluída mas não sejam válidas com a nova.

Os Gêmeos Digitais do Azure não impedem esse status, portanto, tenha cuidado para aplicar o patch nos gêmeos adequadamente para garantir que eles permaneçam válidos durante a troca de definição de modelos.

Converter modelos v2 para v3

Os Gêmeos Digitais do Azure dão suporte às versões 2 e 3 do DTDL (encurtadas na documentação para v2 e v3, respectivamente). V3 é a escolha recomendada com base em suas capacidades expandidas. Esta seção explica como atualizar um modelo DTDL v2 existente para DTDL v3.

1. Atualize o contexto. A principal característica que identifica um modelo como v2 ou v3 é o @context campo na interface. Para converter um modelo de v2 para v3, altere o dtmi:dtdl:context;2 valor de contexto para dtmi:dtdl:context;3. Para muitos modelos, essa será a única mudança necessária.
   1. Valor em v2: "@context": "dtmi:dtdl:context;2"
   2. Valor na v3: "@context": "dtmi:dtdl:context;3".
2. Se necessário, atualize os tipos semânticos. No DTDL v2, os tipos semânticos são suportados nativamente. No DTDL v3, eles são incluídos com a extensão de recurso QuantitativeTypes. Portanto, se o seu modelo v2 usou tipos semânticos, você precisará adicionar a extensão de recurso ao converter o modelo para v3. Para fazer isso, primeiro altere o campo na interface de um único valor para uma matriz de valores e, em seguida, adicione o @context valor dtmi:dtdl:extension:quantitativeTypes;1.
   1. Valor em v2: "@context": "dtmi:dtdl:context;2"
   2. Valor na v3: "@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:quantitativeTypes;1"]
3. Se necessário, considere limites de tamanho. V2 e v3 têm limites de tamanho diferentes, portanto, se sua interface for muito grande, convém revisar os limites nas diferenças entre DTDL v2 e v3.

Após essas alterações, um antigo modelo DTDL v2 foi convertido em um modelo DTDL v3.

Você também pode considerar novos recursos do DTDL v3, como propriedades de tipo de matriz, relaxamento de versão e extensões de recursos adicionais, para ver se algum deles seria adições benéficas. Para obter uma lista completa das diferenças entre DTDL v2 e v3, consulte Alterações da versão 2 na Descrição da linguagem DTDL v3.

Próximas etapas

Veja como criar e gerenciar os gêmeos digitais com base em seus modelos:

• Gerenciar gêmeos digitais