Partilhar via

Gerenciar modelos de Gêmeos Digitais do Azure

  • Artigo

Este artigo descreve como gerenciar os modelos em sua instância do Azure Digital Twins. As operações de gerenciamento incluem upload, validação, recuperação e exclusão de modelos.

Pré-requisitos

Para trabalhar com Gêmeos Digitais do Azure neste artigo, você precisará de uma instância de Gêmeos Digitais do Azure e as permissões necessárias para usá-la. Se você já tiver uma instância do Azure Digital Twins configurada, poderá usar essa instância e pular para a próxima seção. Caso contrário, siga as instruções em Configurar uma instância e autenticação. As instruções contêm informações para ajudá-lo a verificar se você concluiu cada etapa com êxito.

Depois de configurar sua instância, anote o nome do host da instância. Você pode encontrar o nome do host no portal do Azure.

Interfaces de desenvolvimento

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 outros SDKs de linguagem descritos em APIs e SDKs do Azure Digital Twins.

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

Nota

Atualmente, o Azure Digital Twins Explorer suporta totalmente modelos DTDL v2 e suporta funcionalidade limitada para modelos DTDL v3.

Os modelos DTDL v3 podem ser visualizados no painel Modelos, e os gêmeos criados com modelos DTDL v3 podem ser visualizados e editados (incluindo aqueles com propriedades de matriz). No entanto, os modelos DTDL v3 não aparecerão no painel Gráfico de modelo e não podem ser importados usando o Azure Digital Twins Explorer. Para importar modelos DTDL v3 para sua instância, use outra interface de desenvolvedor, como APIs e SDKs ou a CLI do Azure.

Visualização

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

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:

Captura de ecrã do Azure Digital Twins Explorer a mostrar um gráfico de modelo de exemplo.

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 escritos em DTDL e salvos como arquivos JSON. Há também uma extensão DTDL disponível para Visual Studio Code, que fornece validação de sintaxe e outros recursos para facilitar a escrita de documentos DTDL.

Considere um exemplo em que um hospital quer representar digitalmente os seus quartos. Cada sala contém um dispensador de sabão inteligente para monitorar a lavagem das mãos e sensores para monitorar o tráfego pela sala.

O primeiro passo para a solução é criar modelos para representar aspetos do hospital. Um quarto de paciente neste cenário pode ser descrito assim:

{
    "@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"
      }
    ]
  }

Nota

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

Este modelo define um nome e um ID exclusivo para o quarto do paciente e propriedades para representar a contagem de visitantes e o status de lavagem das 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 quaisquer gêmeos digitais baseados neste modelo de sala para os dispositivos reais.

Nota

Existem algumas funcionalidades DTDL que o Azure Digital Twins não suporta atualmente, incluindo o writable atributo em propriedades e relações, e minMultiplicity maxMultiplicity para relações. Para obter mais informações, consulte Notas 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 o domínio do setor, considere se existe uma ontologia do setor que você pode usar para facilitar a criação de modelos. A próxima seção descreve as ontologias do setor com mais detalhes.

Use 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 de 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 ler mais sobre essas ontologias, incluindo como usá-las e quais ontologias estão disponíveis agora, em O que é uma ontologia?.

Validar sintaxe

Depois de criar um modelo, é recomendável validar seus modelos offline antes de carregá-los em sua instância do Azure Digital Twins.

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 que os modelos forem criados, você poderá carregá-los na instância do Azure Digital Twins.

Quando estiver pronto para carregar um modelo, você pode usar o seguinte trecho de código para o SDK do .NET:

// '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 upload, os arquivos de modelo são validados pelo serviço.

Normalmente, terá de carregar mais do que um modelo para o serviço. Há várias maneiras de carregar muitos modelos de uma só vez em uma única transação. Para ajudá-lo a escolher uma estratégia, considere o tamanho do seu conjunto de modelos enquanto continua o restante desta seção.

Carregue 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 de Gêmeos Digitais do Azure.

Se você estiver usando o SDK, poderá carregar vários arquivos de modelo com o CreateModels método assim:

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 a ser carregado juntos. Nesse caso, os modelos devem ser colocados em uma matriz JSON dentro do arquivo, como no 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"
    }
]

Carregue conjuntos de modelos grandes com a API de Importação de Trabalhos

Para conjuntos de modelos grandes, você pode usar a API de Trabalhos de Importação 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 do Azure Digital Twins para modelos e trabalhos em massa.

Gorjeta

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 de Trabalhos de Importação.

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 gráficos 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 para o 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:

Captura de ecrã do portal do Azure a mostrar o URL de um ficheiro num contentor de armazenamento.

Em seguida, o arquivo pode ser usado em uma chamada da API Import Jobs. Você fornecerá a URL de armazenamento de blob do arquivo de entrada, bem como uma nova URL de armazenamento de blob para indicar onde 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 do Azure Digital Twins.

As suas opções incluem:

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

Aqui estão alguns exemplos de chamadas:

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

O SDK chama para recuperar modelos todos os objetos de retorno DigitalTwinsModelData . DigitalTwinsModelData contém metadados sobre o modelo armazenado na instância do Azure Digital Twins, como nome, DTMI e data de criação do modelo. O DigitalTwinsModelData objeto também inclui opcionalmente o próprio modelo. O que significa que, dependendo dos parâmetros, você pode usar as chamadas de recuperação para recuperar apenas 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 o modelo inteiro.

A RetrieveModelWithDependencies chamada 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 necessariamente devolvidos exatamente no formato do documento em que foram carregados. Os Gêmeos Digitais do Azure garantem apenas que o formulário de retorno será semanticamente equivalente.

Atualizar modelos

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

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

Antes de fazer atualizações em seus modelos, é recomendável pensar de forma holística sobre toda a sua solução e o impacto das alterações de modelo que você está prestes a fazer. Os modelos em uma solução de Gêmeos Digitais do Azure geralmente estão interconectados, por isso é 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 pode afetar a entrada e o processamento de código, aplicativos cliente e relatórios automatizados.

Aqui estão algumas recomendações para ajudá-lo a gerenciar suas transições de modelo sem problemas:

  • Em vez de pensar em modelos como entidades separadas, considere evoluir todo o seu conjunto de modelos quando apropriado para manter os modelos e seus relacionamentos atualizados juntos.
  • Trate modelos como código-fonte e gerencie-os no controle do código-fonte. Aplique o mesmo rigor e atenção aos modelos e alterações de modelo que aplica a outros códigos na sua solução.

Quando estiver pronto para continuar com o processo de atualização dos modelos, o restante desta seção descreve as estratégias que você pode usar para implementar as atualizações.

Estratégias para atualização de modelos

Depois que um modelo é carregado em sua instância do Azure Digital Twins, a interface do modelo é imutável, o que significa que não há "edição" tradicional de modelos. Os Gêmeos Digitais do Azure também não permitem o recarregamento do mesmo modelo exato enquanto um modelo correspondente já estiver 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: Carregue a nova versão do modelo: Carregue o modelo, com um novo número de versão, e atualize seus gêmeos para usar esse novo modelo. As versões nova e antiga do modelo existirão em sua instância até que você exclua uma.
    • Use essa estratégia quando quiser atualizar apenas alguns de seus gêmeos que usam o modelo, ou quando quiser garantir que os gêmeos permaneçam em conformidade com seus modelos e graváveis durante a transição do modelo.
  • Estratégia 2: Excluir o modelo antigo e recarregar: exclua o modelo original e carregue o novo modelo com o mesmo nome e ID (valor DTMI) em seu lugar. 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 reagir aos modelos. Se a atualização do seu modelo contiver uma alteração de rutura com a atualização do modelo, os gêmeos ficarão não conformes com seus modelos por um curto período de tempo enquanto você os faz a transição do modelo antigo para o novo, o que significa que eles não poderão receber atualizações até que o novo modelo seja carregado e os gêmeos estejam em conformidade com ele.

Nota

Fazer mudanças significativas em seus modelos é desencorajado 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: Carregar nova versão do modelo

Essa opção envolve a criação de uma nova versão do modelo e o upload 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 a nova versão do modelo ou a versão mais antiga, o que significa que o upload de 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 do modelo antigo, e você pode atualizar esses gêmeos para a nova versão do modelo corrigindo-os.

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

1. Crie e carregue uma nova versão do modelo

Para criar uma nova versão de um modelo existente, comece com a DTDL do modelo original. Atualize, adicione ou remova os campos que pretende alterar.

Em seguida, marque este modelo como uma versão mais recente do modelo atualizando o id campo do modelo. A última seção do ID do modelo, após o ;, representa o número do modelo. Para indicar que este modelo é agora uma versão mais atualizada, incremente o número no final do id valor para qualquer número maior do que o número da versão atual.

Por exemplo, se o ID do modelo anterior tiver esta aparência:

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

A versão 2 deste modelo pode ter esta aparência:

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

Em seguida, carregue a nova versão do modelo para sua instância.

Esta versão do modelo estará disponível em sua instância para uso em gêmeos digitais. Ele não substitui versões anteriores do modelo, portanto, várias versões do modelo agora coexistem em sua instância.

2. Atualize os elementos do gráfico conforme necessário

Em seguida, atualize os gêmeos e relacionamentos em sua instância para usar a nova versão do modelo em vez da antiga.

Você pode usar as instruções a seguir para atualizar gêmeos e atualizar relacionamentos. A operação de patch para atualizar o modelo de um gêmeo será mais ou menos assim:

[
  {
    "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 quaisquer campos que devam ser alterados no gêmeo para torná-lo compatível com o novo modelo.

Também pode ser necessário atualizar relacionamentos e outros modelos em sua instância que fazem referência a esse modelo, para 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 mais modelos que precisem de atualização.

3. (Opcional) Descomissionar 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, mas não pode ser usado para criar novos gêmeos digitais.

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

As seções vinculadas acima contêm código de exemplo e considerações para descomissionamento e exclusão de modelos.

Estratégia 2: Excluir modelo antigo e recarregar

Em vez de incrementar a versão de um modelo, você pode excluir um modelo completamente e recarregar um modelo editado para a instância.

O Azure Digital Twins não se lembra que o modelo antigo já foi carregado, por isso esta ação será como 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 de como a nova definição difere da antiga, esses gêmeos podem ter propriedades e relacionamentos que correspondem à definição excluída e não são válidos com a nova, então você pode precisar corrigi-los para garantir que permaneçam válidos.

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

1. Excluir modelo antigo

Como o Azure Digital Twins não permite dois modelos com a mesma ID, comece excluindo o modelo original da sua instância.

Nota

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 esses modelos dependentes primeiro para remover temporariamente as referências ou excluir os modelos dependentes e recarregá-los em uma etapa posterior.

Use as instruções a seguir para excluir seu modelo original. Essa ação deixará seus gêmeos que estavam usando esse modelo temporariamente "órfãos", pois agora estão usando um modelo que não existe mais. Esse estado será reparado na próxima etapa quando você recarregar o modelo atualizado.

2. Crie e carregue um novo modelo

Comece com a DTDL do modelo original. Atualize, adicione ou remova os campos que pretende alterar.

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

3. Atualize os elementos do gráfico conforme necessário

Agora que seu novo modelo foi carregado no lugar do antigo, os gêmeos em seu gráfico começarão automaticamente a usar a nova definição de modelo assim que o cache em sua instância expirar e for redefinido. Esse processo pode levar de 10 a 15 minutos ou mais, dependendo do tamanho do gráfico. 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.

Nota

Se você removeu outros modelos dependentes anteriormente para excluir o modelo original, recarregue-os agora depois que o cache for redefinido. Se você atualizou os modelos dependentes para remover temporariamente as referências ao modelo original, poderá atualizá-los novamente para colocar a referência de volta.

Em seguida, atualize os gêmeos e relacionamentos em sua instância para que suas propriedades correspondam às propriedades definidas pelo novo modelo. Antes de esta etapa ser concluída, os gêmeos que não correspondem ao seu modelo ainda podem ser lidos, mas não podem ser gravados. Para obter mais informações sobre o estado de gêmeos sem um modelo válido, consulte Gêmeos sem modelos.

Há duas maneiras de atualizar gêmeos e relacionamentos para o novo modelo para que eles sejam graváveis novamente:

  • Conserte os gêmeos e relacionamentos conforme necessário para que eles se encaixem no novo modelo. Você pode usar as instruções a seguir para atualizar gêmeos e atualizar relacionamentos.
    • Se você adicionou propriedades: Não é necessário atualizar gêmeos e relacionamentos para ter os novos valores, já que gêmeos sem os novos valores ainda serão gêmeos válidos. Você pode corrigi-los como quiser adicionar valores para as novas propriedades.
    • Se você removeu propriedades: é necessário corrigir gêmeos para remover as propriedades que agora são inválidas com o novo modelo.
    • Se você atualizou propriedades: é necessário corrigir gêmeos para atualizar os valores das propriedades alteradas para serem válidos com o novo modelo.
  • Exclua gêmeos e relacionamentos que usam o modelo e recrie-os. Você pode usar as instruções a seguir para excluir gêmeos e recriar gêmeos, além de excluir relacionamentos e recriar relacionamentos.
    • Você pode querer fazer essa operação se estiver fazendo muitas alterações no modelo, e será difícil atualizar os gêmeos existentes para correspondê-lo. No entanto, a recreação pode ser complicada se você tiver muitos gêmeos que estão interligados por muitos relacionamentos.

Remover modelos

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

  • Descomissionamento: Uma vez que um modelo é desativado, você não pode mais usá-lo para criar novos gêmeos digitais. Os gêmeos digitais existentes que já usam esse modelo não são afetados, então você ainda pode atualizá-los com coisas como alterações de propriedade e adição ou exclusão de relacionamentos.
  • Exclusão: Esta operação removerá completamente o modelo da solução. Os gémeos que usavam este modelo já não estão associados a nenhum modelo válido, pelo que são tratados como se não tivessem um modelo. Você ainda pode ler esses gêmeos, mas não pode fazer atualizações sobre eles até que eles sejam reatribuídos a um modelo diferente.

Essas operações são recursos separados e não afetam umas às outras, embora possam ser usadas juntas para remover um modelo gradualmente.

Nota

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

Desmantelamento

Para encerrar um modelo, você pode usar o método DecommissionModel 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 de API REST DigitalTwinModels Update. A decommissioned propriedade é a única propriedade que pode ser substituída por esta chamada de API. O documento do patch JSON terá a seguinte aparência:

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

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

Eliminação

Você pode excluir todos os modelos em sua instância de uma só vez ou pode fazê-lo individualmente.

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

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

Antes da exclusão: Requisitos de exclusão

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

A exceção são os modelos dos quais outros modelos dependem, seja com uma extends relação ou como um componente. Por exemplo, se um modelo de Sala de Conferência estender um modelo de Sala e tiver um modelo ACUnit como componente, você não poderá excluir Sala ou ACUnit até que a Sala de Conferência remova essas respetivas referências.

Você pode 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 cumpra os requisitos para excluí-lo imediatamente, você pode querer passar por algumas etapas primeiro para evitar consequências não intencionais para os gêmeos deixados para trás. Aqui estão algumas etapas que podem ajudá-lo a gerenciar o processo:

  1. Primeiro, descomissionar o modelo
  2. Aguarde alguns minutos para se certificar de que o serviço processou quaisquer solicitações de criação de gêmeos de última hora enviadas antes da desativação
  3. Consulte gêmeos por modelo para ver todos os gêmeos que estão usando o modelo agora desativado
  4. Elimine os gémeos, se já não precisar deles, ou remova-os para um novo modelo, se necessário. Você também pode optar por deixá-los em paz, caso em que eles se tornarão gêmeos sem modelos assim que o modelo for excluído. Consulte a próxima seção para as implicações desse estado.
  5. Aguarde mais alguns minutos para se certificar de que as alterações foram concluídas
  6. Excluir o modelo

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

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

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

Após a eliminação: gémeos sem modelos

Uma vez que um modelo é excluído, todos os gêmeos digitais que estavam usando o modelo são agora considerados sem um modelo. Não há nenhuma consulta que possa lhe dar uma lista de todos os gêmeos neste estado, embora você ainda possa consultar os gêmeos pelo modelo excluído para saber quais gêmeos são afetados.

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

Coisas que pode fazer:

  • Consultar o gémeo
  • Ler propriedades
  • Ler relações de saída
  • Adicionar e excluir relacionamentos de entrada (como em, outros gêmeos ainda podem formar relacionamentos com este gêmeo)
    • A target definição de relacionamento ainda pode refletir a DTMI do modelo excluído. Uma relação sem um alvo definido também pode funcionar aqui.
  • Eliminar relações
  • Eliminar o gémeo

Coisas que não pode fazer:

  • Editar relacionamentos de saída (como em, relacionamentos deste gêmeo para outros gêmeos)
  • Editar propriedades

Após a exclusão: Recarregando um modelo

Depois de um modelo ter sido eliminado, pode decidir mais tarde carregar um novo modelo com o mesmo ID do modelo que eliminou. Veja o que acontece nesse caso.

  • Do ponto de vista da loja de soluções, essa operação é a mesma que carregar um modelo totalmente novo. O serviço não se lembra que o antigo já foi carregado.
  • Se houver gêmeos restantes no gráfico fazendo referência ao modelo excluído, eles não ficarão mais órfãos; este ID de modelo é válido novamente com a nova definição. No entanto, se a nova definição para o modelo for diferente da definição de modelo que foi excluída, esses gêmeos podem ter propriedades e relações que correspondem à definição excluída e não são válidas com a nova.

Os Gêmeos Digitais do Azure não impedem esse estado, portanto, tenha cuidado para corrigir gêmeos adequadamente para garantir que eles permaneçam válidos por meio da opção de definição de modelo.

Converter modelos v2 para v3

O Azure Digital Twins suporta DTDL versões 2 e 3 (abreviadas na documentação para v2 e v3, respetivamente). 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 valor de dtmi:dtdl:context;2 contexto para dtmi:dtdl:context;3. Para muitos modelos, esta será a única mudança necessária.
    1. Valor em v2: "@context": "dtmi:dtdl:context;2"
    2. Valor em v3: "@context": "dtmi:dtdl:context;3".
  2. Se necessário, atualize os tipos semânticos. Na DTDL v2, tipos semânticos são suportados nativamente. Na DTDL v3, eles estã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 @context campo na interface de um único valor para uma matriz de valores e, em seguida, adicione o valor dtmi:dtdl:extension:quantitativeTypes;1.
    1. Valor em v2: "@context": "dtmi:dtdl:context;2"
    2. Valor em 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 é muito grande, você pode querer rever 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 querer considerar novos recursos da DTDL v3, como propriedades de tipo de matriz, relaxamento de versão e extensões de recursos adicionais, para ver se algum deles seria uma adição benéfica. Para obter uma lista completa das diferenças entre DTDL v2 e v3, consulte Alterações da versão 2 na Descrição de idioma DTDL v3.

Nota

Atualmente, o Azure Digital Twins Explorer suporta totalmente modelos DTDL v2 e suporta funcionalidade limitada para modelos DTDL v3.

Os modelos DTDL v3 podem ser visualizados no painel Modelos, e os gêmeos criados com modelos DTDL v3 podem ser visualizados e editados (incluindo aqueles com propriedades de matriz). No entanto, os modelos DTDL v3 não aparecerão no painel Gráfico de modelo e não podem ser importados usando o Azure Digital Twins Explorer. Para importar modelos DTDL v3 para sua instância, use outra interface de desenvolvedor, como APIs e SDKs ou a CLI do Azure.

Próximos passos

Veja como criar e gerir gémeos digitais com base nos seus modelos: