Saiba mais sobre os modelos de gêmeos e como defini-los no serviço Gêmeos Digitais do Azure

Artigo
01/04/2024

Uma característica importante dos Gêmeos Digitais do Azure é que você pode definir um vocabulário próprio e criar um grafo de gêmeos nos termos definidos por sua empresa. Esse recurso funciona por meio de modelos fornecidos pelo usuário. Os modelos são como os substantivos em uma descrição do seu mundo. Os modelos dos Gêmeos Digitais do Azure são representados na DTDL (Linguagem de Definição de Gêmeo Digital), baseada em JSON-LD.

Os modelos são semelhantes às classes em uma linguagem de programação orientada a objeto, que definem uma forma de dados para um determinado conceito no ambiente de trabalho real. Os modelos têm nomes (como Room ou TemperatureSensor) e contêm elementos como propriedades, componentes e relacionamentos que descrevem o que esse tipo de entidade em seu ambiente faz. Posteriormente, você usará esses modelos para criar gêmeos digitais que representam entidades específicas que seguem essa descrição de tipo.

DTDL para modelos

Os modelos dos Gêmeos Digitais do Azure são definidos usando a DTDL.

Você pode exibir a descrição completa do idioma do DTDL v3 no GitHub: Descrição do idioma DTDL versão 3. Esta página inclui detalhes de referência DTDL e exemplos para ajudá-lo a começar a escrever seus próprios modelos DTDL.

O DTDL é baseado em JSON-LD e é uma linguagem de programação independente. O DTDL não é exclusivo dos Gêmeos Digitais do Azure. Ele também é usado para representar dados de dispositivos em outros serviços de IoT, como o IoT Plug and Play.

O restante deste artigo resume como a linguagem é usada nos Gêmeos Digitais do Azure.

Versões DTDL suportadas

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). A V3 é a opção recomendada para modelagem nos Gêmeos Digitais do Azure com base em seus recursos expandidos, incluindo:

Relaxamento da versão DTMI
Suporte de matriz para propriedades
Limites aumentados para herança de modelo
Extensões de recursos
- A capacidade de decorar esquemas de interface personalizados com tipos semânticos (fornecidos com a extensão QuantitativeTypes)

Quando esses recursos são discutidos na documentação, eles são acompanhados por uma observação de que eles só estão disponíveis no DTDL v3. Para obter uma lista completa das diferenças entre DTDL v2 e v3, consulte Descrição da linguagem DTDL v3: alterações da versão 2.

Os Gêmeos Digitais do Azure também dão suporte ao uso de uma combinação de modelos v2 e v3 na mesma instância. Ao usar modelos de ambas as versões juntos, tenha em mente as seguintes restrições:

Uma interface v2 não pode estender uma interface v3 ou ter um componente com uma interface v3 como seu esquema.
Por outro lado, uma interface v3 pode estender uma interface v2, e uma interface v3 pode ter um componente com uma interface v2 como seu esquema.
As relações podem apontar em qualquer direção, de uma origem de modelo v2 para um destino de modelo v3 ou vice-versa de uma origem de modelo v3 para um destino de modelo v2.

Você também pode migrar modelos v2 existentes para v3. Para obter instruções sobre como fazer isso, consulte Converter modelos v2 em v3.

Observação

Atualmente, o Azure Digital Twins Explorer oferece suporte total a modelos DTDL v2 e oferece suporte a funcionalidade limitada para modelos DTDL v3. No Azure Digital Twins Explorer, os modelos DTDL v3 podem ser exibidos no painel Modelos, e os gêmeos criados com modelos DTDL v3 podem ser exibidos 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 poderão ser importados usando o Gerenciador de Gêmeos Digitais do Azure. Para importar modelos DTDL v3 para sua instância, use outra interface de desenvolvedor, como APIs e SDKs ou a CLI do Azure.

Visão geral do modelo

Os modelos de tipo de gêmeos podem ser programados em qualquer editor de texto. A linguagem DTDL segue a sintaxe JSON, portanto, você deve armazenar modelos com a extensão .json. Com a extensão JSON, muitos editores de texto de programação oferecem os recursos de verificação de sintaxe básica e realce em documentos da DTDL. Também há uma extensão da DTDL disponível para o Visual Studio Code.

Aqui estão os campos dentro de uma interface de modelo:

Campo	Descrição
`@id`	Um Digital Twin Model Identifier (DTMI) para o modelo, no formato `dtmi:<domain>:<unique-model-identifier>;<model-version-number>`. No DTDL v3, o número da versão pode ser omitido ou estruturado como um número de versão de duas partes (`<major>.<minor>`).
`@type`	Identifica o tipo de informações que estão sendo descritas. Para uma interface, o tipo é `Interface`.
`@context`	Define o contexto do documento JSON. Os modelos devem ser usados `dtmi:dtdl:context;2` para DTDL v2 ou `dtmi:dtdl:context;3` DTDL v3. Os modelos DTDL v3 também podem nomear extensões de recursos adicionais nesse campo.
`displayName`	[opcional] Oferece a opção de definir um nome amigável para o modelo. Se você não usar esse campo, o modelo usará seu valor DTMI completo.
`contents`	Todos os dados de interface restantes são colocados aqui, como uma matriz de definições de atributo. Cada atributo deve fornecer um (`Property`, ou `Component`) para identificar o tipo de informação de interface que descreve e, em seguida, `Relationship`um `@type` conjunto de propriedades que definem o atributo real. A próxima seção descreve os atributos do modelo em detalhes.

Aqui está um exemplo de um modelo DTDL básico. Esse modelo descreve uma Página Inicial, com uma propriedade para uma ID. O modelo de Casa também define uma relação com um modelo de Andar, que pode ser usado para indicar que um gêmeo de Casa está conectado a determinados gêmeos de Andar.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

Atributos de modelo

As principais informações sobre um modelo são fornecidas pelos respectivos atributos, que são definidos na seção contents da interface do modelo.

Aqui estão os atributos disponíveis no DTDL que têm suporte nos Gêmeos Digitais do Azure. Uma interface de modelo DTDL usada para Gêmeos Digitais do Azure pode conter zero, um ou muitos de cada um dos seguintes campos:

Propriedade – As propriedades são campos de dados que representam o estado de uma entidade, como as propriedades de várias linguagens de programação orientadas a objeto. As propriedades têm armazenamento de backup e podem ser lidas a qualquer momento. Para obter mais informações, consulte Propriedades abaixo.
Relacionamento – Com os relacionamentos, você representa a relação entre pares de gêmeos digitais. As relações podem representar diferentes significados semânticos, como contains ("piso contém sala"), ("hvac resfria sala"), coolsisBilledTo ("compressor é cobrado do usuário") e assim por diante. As relações permitem que a solução forneça um grafo das entidades inter-relacionadas. As relações também podem ter propriedades próprias. Para obter mais informações, consulte Relações abaixo.
Componente – Componentes permitem que você crie sua interface de modelo como um conjunto de outras interfaces, se desejar. Um exemplo de um componente é uma interface frontCamera (e outro componente interface backCamera) que é usado na definição de um modelo para um telefone. Primeiro, defina uma interface para frontCamera como se fosse um modelo próprio e, em seguida, referencie-a ao definir o telefone.

Use um componente para descrever algo que faz parte da sua solução, mas não precisa de uma identidade separada nem precisa ser criado, excluído ou reorganizado no grafo de gêmeos de maneira independente. Se você quiser que as entidades tenham existências independentes no grafo de gêmeos, represente-as como gêmeos digitais separados de modelos diferentes, conectados por relações.

Dica

Os componentes também podem ser usados para a organização, para agrupar conjuntos de propriedades relacionadas em uma interface de modelo. Nessa situação, você pode considerar cada componente como um namespace ou "pasta" dentro da interface.

Para saber mais, consulte os Componentes abaixo.

A Descrição de Linguagem DTDL v3 também define Comandos e Telemetria, mas nenhum deles é usado nos Gêmeos Digitais do Azure. Não há suporte para comandos e a Telemetria, embora seja permitida em definições de modelo, não tem nenhum caso de uso exclusivo na modelagem de Gêmeos Digitais do Azure. Em vez de usar a telemetria DTDL, você deve usar propriedades DTDL para armazenar informações de estado gêmeo.

Observação

Embora não seja necessário definir campos de Telemetria em seus modelos DTDL para armazenar dados de dispositivo de entrada, os Gêmeos Digitais do Azure podem emitir eventos como telemetria usando a API SendTelemetria. Isso dispara um evento de Mensagem de Telemetria Digital Twin que pode ser recebido por um manipulador de eventos para executar ações em outros gêmeos ou acionar serviços downstream.

Propriedades

Esta seção entra em mais detalhes sobre propriedades em modelos DTDL.

Para obter informações abrangentes sobre os campos que podem aparecer como parte de uma propriedade, consulte Propriedade na Descrição da linguagem DTDL v3.

Observação

O atributo DTDL writable para propriedades não tem suporte no momento no Azure digital gêmeos. Ele pode ser adicionado ao modelo, mas o Azure digital gêmeos não irá imaplicá-lo. Para obter mais informações, confira as Notas da DTDL específicas do serviço.

Esquema

De acordo com o DTDL, o esquema para atributos de propriedade pode ser um tipo primitivo padrão — , , e —integer e outros tipos como dateTime e booleanduration. stringdouble

Além dos tipos primitivos, os campos de propriedade podem ter estes tipos complexos:

Object
Map
Enum
Array, somente em DTDL v3. Array não há suporte para o tipo de propriedades no DTDL v2.

Eles também podem ser tipos semânticos, que permitem anotar valores com unidades. No DTDL v2, os tipos semânticos são suportados nativamente, no DTDL v3, você pode incluí-los com uma extensão de recurso.

Exemplo de propriedade básica

Aqui está um exemplo básico de uma propriedade em um modelo de DTDL. Este exemplo mostra a propriedade ID de uma Casa.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

Exemplo de tipo de objeto complexo

As propriedades podem ser de tipos complexos, incluindo um Object tipo.

O exemplo a seguir mostra outra versão do modelo de Casa, com uma propriedade em seu endereço. address é um objeto, com seus próprios campos para rua, cidade, estado e CEP.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": "Property",
      "name": "address",
      "schema": {
        "@type": "Object",
        "fields": [
          {
            "name": "street",
            "schema": "string"
          },
          {
            "name": "city",
            "schema": "string"
          },
          {
            "name": "state",
            "schema": "string"
          },
          {
            "name": "zip",
            "schema": "string"
          }
        ]
      }
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1",
      "properties": [
        {
          "@type": "Property",
          "name": "lastOccupied",
          "schema": "dateTime"
        }
      ]
    }
  ]
}

Exemplo de tipo semântico DTDL v2

Os tipos semânticos são para expressar um valor com uma unidade. As propriedades dos Gêmeos Digitais do Azure podem usar qualquer um dos tipos semânticos com suporte no DTDL.

No DTDL v2, os tipos semânticos são suportados nativamente. Para obter mais informações sobre tipos semânticos no DTDL v2, consulte Tipos semânticos na Descrição da linguagem DTDL v2. Para saber mais sobre tipos semânticos no DTDL v3, consulte a extensão de recurso QuantitativeTypes DTDL v3.

O exemplo a seguir mostra um modelo de sensor DTDL v2 com propriedades de tipo semântico para Umidade e Temperatura.

{
  "@id": "dtmi:com:adt:dtsample:v2sensor;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;2",
  "displayName": "Sensor (v2 model)",
  "contents": [
    {
      "@type": ["Property", "Temperature"],
      "name": "Temperature",
      "schema": "double",
      "unit": "degreeFahrenheit"    
    },
    {
      "@type": ["Property", "Humidity"],
      "name": "Humidity",
      "schema": "double",
      "unit": "gramPerCubicMetre" 
    }
  ]
}

Importante

"Property" deve ser o @type primeiro elemento da matriz, seguido pelo tipo semântico. Caso contrário, o campo pode não estar visível no Azure Digital Twins Explorer.

Relacionamentos

Esta seção apresenta mais detalhes sobre as relações nos modelos de DTDL.

Para obter uma lista abrangente dos campos que podem aparecer como parte de um relacionamento, consulte Relacionamento na Descrição da Linguagem DTDL v3.

Observação

No momento, os atributos do DTDL writable, minMultiplicity e maxMultiplicity para relações não têm suporte nos Gêmeos Digitais do Azure. Eles podem ser adicionados ao modelo, mas os Gêmeos Digitais do Azure não irão aplicá-los. Para obter mais informações, confira as Notas da DTDL específicas do serviço.

Exemplo de relação básica

Aqui está um exemplo básico de uma relação em um modelo de DTDL. Este exemplo mostra uma relação em um modelo de Casa que permite que ela se conecte a um modelo de Andar.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

Observação

Para relações, @id é um campo opcional. Se nenhum @id for fornecido, o processador de interface do gêmeo digital atribuirá um.

Relações direcionadas e não direcionadas

As relações podem ser definidas com ou sem um destino. Um destino especifica quais tipos de gêmeos a relação pode alcançar. Por exemplo, você pode incluir um destino para especificar que um modelo Home só pode ter um rel_has_floors relacionamento com gêmeos que são gêmeos Floor.

Eventualmente, você pode querer definir uma relação sem um destino específico, para que a relação possa se conectar a vários tipos de gêmeos diferentes.

Aqui está um exemplo de uma relação em um modelo DTDL sem um destino. Neste exemplo, a relação define quais sensores uma Sala pode ter, e a relação pode se conectar a qualquer tipo.

{
  "@id": "dtmi:com:adt:dtsample:room;1",
  "@type": "Interface",
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1"
  ],
  "displayName": "Room",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": ["Property", "Humidity"],
      "name": "humidity",
      "schema": "double",
      "unit": "gramPerCubicMetre"
    },
    {
      "@type": "Component",
      "name": "thermostat",
      "schema": "dtmi:com:adt:dtsample:thermostat;1"
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:room:rel_has_sensors;1",
      "name": "rel_has_sensors",
      "displayName": "Room has sensors"

Propriedades das relações

O DTDL também permite que as relações tenham propriedades próprias. Quando você define um relacionamento dentro de um modelo DTDL, o relacionamento pode ter seu próprio properties campo onde você pode definir propriedades personalizadas para descrever o estado específico do relacionamento.

O exemplo a seguir mostra outra versão do modelo de Casa, onde a relação rel_has_floors tem uma propriedade representando quando o Andar relacionado foi ocupado pela última vez.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": "Property",
      "name": "address",
      "schema": {
        "@type": "Object",
        "fields": [
          {
            "name": "street",
            "schema": "string"
          },
          {
            "name": "city",
            "schema": "string"
          },
          {
            "name": "state",
            "schema": "string"
          },
          {
            "name": "zip",
            "schema": "string"
          }
        ]
      }
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1",
      "properties": [
        {
          "@type": "Property",
          "name": "lastOccupied",
          "schema": "dateTime"
        }
      ]
    }
  ]
}

Componentes

Esta seção apresenta mais detalhes sobre os componentes nos modelos de DTDL.

Para obter uma lista abrangente dos campos que podem aparecer como parte de um componente, consulte Componente na Descrição da linguagem DTDL v3.

Exemplo de componente básico

Aqui está um exemplo básico de um componente em um modelo de DTDL. Este exemplo mostra um modelo de Sala que utiliza um modelo termostato como componente.

[
  {
    "@id": "dtmi:com:adt:dtsample:room;1",
    "@type": "Interface",
    "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1"
    ],
    "displayName": "Room",
    "extends": "dtmi:com:adt:dtsample:core;1",
    "contents": [
      {
        "@type": ["Property", "Humidity"],
        "name": "humidity",
        "schema": "double",
        "unit": "gramPerCubicMetre"
      },
      {
        "@type": "Component",
        "name": "thermostat",
        "schema": "dtmi:com:adt:dtsample:thermostat;1"
      },
      {
        "@type": "Relationship",
        "@id": "dtmi:com:adt:dtsample:room:rel_has_sensors;1",
        "name": "rel_has_sensors",
        "displayName": "Room has sensors"
      }
    ]
  },
  {
    "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1"
    ],
    "@id": "dtmi:com:adt:dtsample:thermostat;1",
    "@type": "Interface",
    "displayName": "thermostat",
    "contents": [
      {
        "@type": ["Property", "Temperature"],
        "name": "temperature",
        "schema": "double",
        "unit": "degreeFahrenheit"
      }
    ]
  }
]

Se outros modelos nessa solução também contiverem um termostato, poderão fazer referência ao mesmo modelo termostato como um componente em suas próprias definições, assim como a Sala.

Importante

A interface do componente (termostato no exemplo acima) deve ser definida na mesma matriz que qualquer interface que a utilize (Sala no exemplo acima), para que a referência do componente seja encontrada.

Herança de modelo

Às vezes, você quer especializar ainda mais um modelo. Por exemplo, pode ser útil ter um modelo genérico Room e variações especializadas ConferenceRoom e Gym. Para expressar especialização, o DTDL dá suporte à herança. As interfaces podem herdar de uma ou mais interfaces. Você pode fazer isso adicionando um campo extends ao modelo.

A seção extends é um nome de interface ou uma matriz de nomes de interface (permitindo que a interface de extensão herde de vários modelos pai). Um único pai pode servir como o modelo de base para várias interfaces de extensão.

Observação

No DTDL v2, cada extends um pode ter no máximo duas interfaces listadas para ele. No DTDL v3, não há limite no número de valores imediatos para um extendsarquivo .

Tanto no DTDL v2 quanto no v3, o limite de profundidade total para uma extends hierarquia é 10.

O exemplo a seguir reimagina o modelo de Casa do exemplo da DTDL anterior como um subtipo do modelo maior de “núcleo”. O modelo pai (Núcleo) é definido primeiro e, em seguida, o modelo filho (Casa) é criado com base nele usando extends.

{
    "@id": "dtmi:com:adt:dtsample:core;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Core",
    "contents": [
        {
            "@type": "Property",
            "name": "id",
            "schema": "string"
        },
        {
            "@type": "Property",
            "name": "name",
            "schema": "string"
        }
    ]
}

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {

Nesse caso, o Núcleo contribui com uma ID e um nome para Casa. Outros modelos também podem estender o modelo de Núcleo para obter essas propriedades. Aqui está um modelo de Sala que estende a mesma interface pai:

{
  "@id": "dtmi:com:adt:dtsample:room;1",
  "@type": "Interface",
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1"
  ],
  "displayName": "Room",

Depois que a herança é aplicada, a interface de extensão expõe todas as propriedades de toda a cadeia de herança.

A interface de extensão não pode alterar nenhuma das definições das interfaces pai. Ela só pode adicionar a elas. Ela também não pode redefinir um recurso já definido em qualquer uma das interfaces pai (mesmo definição seja igual). Por exemplo, se uma interface pai define a double propriedade mass, a interface de extensão não pode conter uma declaração de mass, mesmo que também seja um double.

Extensões de recurso DTDL v3

O DTDL v3 habilita extensões de linguagem que definem classes de metamodelo adicionais, que você pode usar para escrever modelos mais avançados. Esta seção descreve as classes de extensão de recurso que você pode usar para adicionar recursos não essenciais aos seus modelos DTDL v3.

Cada extensão de recurso é identificada por seu especificador de contexto, que é um valor DTMI (Digital Twin Model Identifier) exclusivo. Para habilitar uma extensão de recurso em um modelo, adicione o especificador de contexto da extensão ao campo do @context modelo (ao lado do especificador de contexto DTDL geral de dtmi:dtdl:context;3). Você pode adicionar várias extensões de recurso ao mesmo modelo.

Aqui está um exemplo de como esse @context campo pode se parecer com extensões de recurso. O trecho a seguir é de um modelo que usa a extensão QuantitativeTypes e a extensão Annotation.

  "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1",
      "dtmi:dtdl:extension:annotation;1"
  ]

Depois de adicionar uma extensão de recurso a um modelo, você terá acesso aos tipos de adjuntos dessa extensão dentro do modelo. Você pode adicionar tipos adjuntos ao campo de um elemento DTDL para fornecer recursos adicionais ao @type elemento. O tipo adjunto pode adicionar propriedades adicionais ao elemento.

Por exemplo, aqui está um trecho de um modelo que está usando a extensão Annotation. Essa extensão tem um tipo adjunto chamado ValueAnnotation, que é adicionado no exemplo abaixo a um elemento de propriedade. Adicionar esse tipo de adjunto ao elemento de propriedade permite que o elemento tenha um campo adicional annotates , que é usado para indicar outra propriedade que é anotada por esse elemento.

{
  "@type": [ "Property", "ValueAnnotation" ],
  "name": "currentTempAccuracy",
  "annotates": "currentTemp",
  "schema": "double"
  },

O restante desta seção explica a extensão Annotation e outras extensões de recurso DTDL v3 com mais detalhes.

Extensão de anotação

A extensão Annotation é usada para adicionar metadados personalizados a um elemento de propriedade em um modelo DTDL v3. Seu especificador de contexto é dtmi:dtdl:extension:annotation;1.

Essa extensão inclui o ValueAnnotation tipo adjunto, que pode ser adicionado a um elemento de propriedade DTDL. O ValueAnnotation tipo adiciona um campo ao elemento , , que permite nomear outra propriedade que é anotada pelo elemento annotatesatual.

Para obter mais detalhes e exemplos dessa extensão, consulte Extensão de anotação na Descrição da linguagem DTDL v3.

Extensão da historização

A extensão Historization é usada para designar uma propriedade em um modelo DTDL v3 como algo que deve ser historizado (o que significa que a sequência histórica de seus valores deve ser registrada, juntamente com os momentos em que os valores mudam). Seu especificador de contexto é dtmi:dtdl:extension:historization;1.

Essa extensão inclui o tipo adjunto, que pode ser adicionado como um cotipo a um elemento de propriedade DTDL para indicar que o Historized serviço deve persistir os valores históricos do elemento e disponibilizá-los para consulta e análise. O Historized tipo adjunto não adiciona nenhum campo ao elemento.

Para obter mais detalhes e exemplos dessa extensão, consulte Extensão de historização na Descrição da linguagem DTDL v3.

Substituindo extensão

A extensão de substituição é usada para substituir uma propriedade em um modelo DTDL V3 com um valor de instância. Ele é usado em combinação com a extensão de anotação, e seu especificador de contexto é dtmi:dtdl:extension:overriding;1.

Essa extensão inclui o Override tipo adjunto, que pode ser adicionado a uma propriedade DTDL que também é co-tipada com ValueAnnotation (da extensão de anotação). O Override tipo adiciona um campo ao elemento, , overridesque permite nomear um campo no elemento anotado para ser substituído pelo valor do elemento atual.

Para obter mais detalhes e exemplos dessa extensão, consulte Substituindo extensão na Descrição da linguagem DTDL v3.

Extensão QuantitativeTypes

A extensão QuantitativeTypes é usada para habilitar tipos semânticos, tipos de unidade e unidades em um modelo DTDL v3. Seu especificador de contexto é dtmi:dtdl:extension:quantitativeTypes;1.

Essa extensão permite o uso de muitos tipos semânticos como tipos adjuntos, que podem ser adicionados a um CommandRequest, um Field, um MapValue ou uma propriedade no DTDL v3. Os tipos semânticos adicionam um campo ao elemento, unit, que aceita uma unidade válida que corresponde ao tipo semântico.

Para obter mais detalhes sobre a extensão, incluindo exemplos e uma lista completa de tipos e unidades semânticas com suporte, consulte QuantitativeTypes extension na DTDL v3 Language Description.

Observações da DTDL específicas do serviço

Nem todos os serviços que usam a DTDL implementam exatamente os mesmos recursos dela. Há alguns recursos do DTDL aos quais o Azure digital gêmeos atualmente não dá suporte, incluindo:

Comandos DTDL
O atributo writable em propriedades ou relações. Apesar de ser possível definir esse atributo segundo as especificações da DTDL, o valor não é usado pelos Gêmeos Digitais do Azure. Em vez disso, considera-se que os clientes externos que têm permissões de gravação no serviço dos Gêmeos Digitais do Azure podem gravar nesse atributo.
As propriedades minMultiplicity e maxMultiplicity em relações. Embora esses atributos possam ser definidos de acordo com as especificações de DTDL, os valores não são impostos pelo Azure digital gêmeos.

Para que um modelo da DTDL seja compatível com os Gêmeos Digitais do Azure, ele deve atender a estes requisitos:

Todos os elementos DTDL de nível superior em um modelo devem ser do tipo Interface. O motivo para esse requisito é que as APIs de modelo dos Gêmeos Digitais do Azure podem receber objetos JSON que representam uma interface ou uma matriz de interfaces. Por isso, nenhum outro tipo de elemento da DTDL é permitido no nível superior.
A DTDL para os Gêmeos Digitais do Azure não deve definir nenhum comando.
Os Gêmeos Digitais do Azure permitem apenas um único nível de aninhamento de componentes, o que significa que uma interface que esteja sendo usada como um componente não pode ter nenhum componente.
Não é possível definir interfaces em linha com outras interfaces da DTDL. É necessário defini-las como entidades de nível superior separadas, com IDs próprias. Assim outras interfaces podem fazer referência a essa ID para incluir a interface como componente ou por herança.

Ferramentas de modelagem e melhores práticas

Esta seção descreve considerações adicionais e recomendações de modelagem.

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?.

Considerar as implicações de consulta

Ao criar modelos para refletir as entidades em seu ambiente, pode ser útil considerar as implicações do design sobre as consultas. É recomendado criar propriedades de maneira a evitar grandes conjuntos de resultados devido à travessia do grafo. Também recomendamos modelar as relações que precisarão ser respondidas em uma só consulta como relações de nível único.

Validar modelos

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 e excluir modelos em massa

Depois de criar, estender ou selecionar os seus modelos, você poderá carregá-los na sua instância dos Gêmeos Digitais do Azure para disponibilizá-los para uso na sua solução.

Você pode carregar vários modelos em uma única chamada de API usando a API Importar Trabalhos. 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. Para obter instruções detalhadas e exemplos que usam essa API, consulte instruções de importação em massa para modelos.

Uma alternativa à API de Importação de Trabalhos é o exemplo de carregador de modelo, que usa as APIs de modelo individuais para carregar vários arquivos de modelo de uma só vez. O exemplo também implementa a reordenação automática para resolver dependências de modelo. Atualmente, ele só funciona com a versão 2 do DTDL.

Se você precisar excluir todos os modelos em uma instância do Gêmeos Digitais do Azure de uma só vez, poderá usar o exemplo de Exclusão de Modelo. Este é um projeto que contém lógica recursiva para manipular dependências de modelo por meio do processo de exclusão. Atualmente, ele só funciona com a versão 2 do DTDL.

Ou, se você quiser limpar os dados em uma instância excluindo todos os modelos , juntamente com todos os gêmeos e relacionamentos, poderá usar a API Excluir Trabalhos.

Visualizar modelos

Depois de carregar modelos na sua instância dos Gêmeos Digitais do Azure, você pode usar o Azure Digital Twins Explorer para exibi-los. O gerenciador contém uma lista de todos os modelos na instância, bem como um grafo de modelo que ilustra como eles se relacionam entre si, incluindo as relações de herança e modelo.

Observação

Veja um exemplo de como pode ser um grafo de modelo:

Para obter mais informações sobre a experiência de modelo no Azure Digital Twins Explorer, confira Explorar modelos e o Grafo de Modelo.

Próximas etapas

Saiba mais sobre a criação de modelos com base em ontologias padrão do setor: O que é uma ontologia?
Aprofunde-se no gerenciamento de modelos com operações de API: Gerenciar modelos de DTDL
Saiba mais sobre o uso de modelos para criar gêmeos digitais: Gêmeos digitais e o grafo de gêmeos

Saiba mais sobre os modelos de gêmeos e como defini-los no serviço Gêmeos Digitais do Azure

DTDL para modelos

Versões DTDL suportadas

Visão geral do modelo

Atributos de modelo

Propriedades

Esquema

Exemplo de propriedade básica

Exemplo de tipo de objeto complexo

Exemplo de tipo semântico DTDL v2

Relacionamentos

Exemplo de relação básica

Relações direcionadas e não direcionadas

Propriedades das relações

Componentes

Exemplo de componente básico

Herança de modelo

Extensões de recurso DTDL v3

Extensão de anotação

Extensão da historização

Substituindo extensão

Extensão QuantitativeTypes

Observações da DTDL específicas do serviço

Ferramentas de modelagem e melhores práticas

Usar ontologias padrão do setor existentes

Considerar as implicações de consulta

Validar modelos

Carregar e excluir modelos em massa

Visualizar modelos

Próximas etapas

Recursos adicionais