Saiba mais sobre modelos de gêmeos e como defini-los no Azure Digital Twins

Artigo
01/04/2024

Uma característica fundamental dos Gêmeos Digitais do Azure é a capacidade de definir seu próprio vocabulário e criar seu gráfico de gêmeos nos termos autodefinidos de sua empresa. Esta capacidade é fornecida através de modelos fornecidos pelo utilizador. Você pode pensar em modelos como os substantivos em uma descrição do seu mundo. Os modelos de Gêmeos Digitais do Azure são representados na DTDL (Digital Twin Definition Language) baseada em JSON-LD.

Um modelo é semelhante a uma classe em uma linguagem de programação orientada a objetos, definindo uma forma de dados para um conceito específico em seu ambiente de trabalho real. Os modelos têm nomes (como Room ou TemperatureSensor) e contêm elementos como propriedades, componentes e relações que descrevem o que esse tipo de entidade em seu ambiente faz. Mais tarde, você usará esses modelos para criar gêmeos digitais que representam entidades específicas que atendem a essa descrição de tipo.

Digital Twin Definition Language (DTDL) para modelos

Os modelos para Gêmeos Digitais do Azure são definidos usando a DTDL (Digital Twins Definition Language).

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

A DTDL tem como base JSON-LD e é independente de linguagens de programação. A DTDL não é exclusiva dos Gêmeos Digitais do Azure. Ele também é usado para representar dados de dispositivos em outros serviços de IoT, como IoT Plug and Play.

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

Versões DTDL suportadas

O Azure Digital Twins suporta DTDL versões 2 e 3 (abreviadas na documentação para v2 e v3, respetivamente). A V3 é a opção recomendada para modelagem em Gêmeos Digitais do Azure com base em seus recursos expandidos, incluindo:

Relaxamento da versão DTMI
Suporte de array 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 na 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 para v3.

Nota

Atualmente, o Azure Digital Twins Explorer suporta totalmente modelos DTDL v2 e suporta 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 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.

Descrição geral do modelo

Os modelos de tipo duplo podem ser escritos em qualquer editor de texto. A linguagem DTDL segue a sintaxe JSON, portanto, você deve armazenar modelos com a extensão .json. O uso da extensão JSON permitirá que muitos editores de texto de programação forneçam verificação de sintaxe básica e realce para seus documentos DTDL. Há também uma extensão DTDL disponível para 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>`. Na 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ção que está sendo descrita. Para uma interface, o tipo é `Interface`.
`@context`	Define o contexto para o documento JSON. Os modelos devem usar `dtmi:dtdl:context;2` para DTDL v2 ou `dtmi:dtdl:context;3` para DTDL v3. Os modelos DTDL v3 também podem nomear extensões de recursos adicionais neste campo.
`displayName`	[opcional] Dá-lhe 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 restantes da interface são colocados aqui, como uma matriz de definições de atributo. Cada atributo deve fornecer um (`Property`, , ou ) para identificar o tipo de informações de interface que descreve e, em seguida, `RelationshipComponent`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. Este modelo descreve um Home, com uma propriedade para um ID. O modelo Home também define uma relação com um modelo Floor, que pode ser usado para indicar que um Home twin está ligado a determinados Floor twins.

{
  "@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 do modelo

As principais informações sobre um modelo são dadas por seus atributos, que são definidos dentro da seção da contents interface do modelo.

Aqui estão os atributos disponíveis na DTDL que são suportados 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 - Propriedades são campos de dados que representam o estado de uma entidade (como as propriedades em muitas linguagens de programação orientadas a objetos). As propriedades têm armazenamento de backup e podem ser lidas a qualquer momento. Para obter mais informações, consulte Propriedades abaixo.
Relacionamento - Os relacionamentos permitem que você represente como um gêmeo digital pode estar envolvido com outros gêmeos digitais. As relações podem representar diferentes significados semânticos, como contains ("chão contém sala"), ("hvac resfria sala"), coolsisBilledTo ("compressor é cobrado ao usuário") e assim por diante. As relações permitem que a solução forneça um gráfico de entidades inter-relacionadas. As relações também podem ter propriedades próprias. Para obter mais informações, consulte Relações abaixo.
Componente - Os componentes permitem que você construa sua interface de modelo como uma montagem de outras interfaces, se desejar. Um exemplo de um componente é uma interface frontCamera (e outra interface componente backCamera) que é usada na definição de um modelo para um telefone. Primeiro, defina uma interface para frontCamera como se fosse seu próprio modelo e, em seguida, faça referência a ela ao definir Phone.

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

Gorjeta

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

Para obter mais informações, consulte 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.

Nota

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 SendTelemetry . Isso dispara um evento Digital Twin Telemetry Message 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 as 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 de idioma DTDL v3.

Nota

O writable atributo DTDL para propriedades não é suportado atualmente nos Gêmeos Digitais do Azure. Ele pode ser adicionado ao modelo, mas os Gêmeos Digitais do Azure não o imporão. Para obter mais informações, consulte Notas DTDL específicas do serviço.

Esquema

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

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

Object
Map
Enum
Array, apenas na DTDL v3. Array type for properties não é suportado na DTDL v2.

Eles também podem ser tipos semânticos, que permitem anotar valores com unidades. Na DTDL v2, os tipos semânticos são suportados nativamente, na 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 DTDL. Este exemplo mostra a propriedade ID de um Home.

{
  "@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 Home, com uma propriedade para seu endereço. address é um objeto, com seus próprios campos para rua, cidade, estado e zip.

{
  "@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 suportados pela DTDL.

Na DTDL v2, tipos semânticos são suportados nativamente. Para obter mais informações sobre tipos semânticos na DTDL v2, consulte Tipos semânticos na Descrição da linguagem DTDL v2. Para saber mais sobre tipos semânticos na 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 primeiro elemento da @type matriz, seguido pelo tipo semântico. Caso contrário, o campo pode não estar visível no Azure Digital Twins Explorer.

Relações

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

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

Nota

Os writableatributos , minMultiplicitye maxMultiplicity DTDL para relacionamentos não são suportados atualmente nos Gêmeos Digitais do Azure. Eles podem ser adicionados ao modelo, mas os Gêmeos Digitais do Azure não os imporão. Para obter mais informações, consulte Notas DTDL específicas do serviço.

Exemplo de relacionamento básico

Aqui está um exemplo básico de um relacionamento em um modelo DTDL. Este exemplo mostra uma relação em um modelo Home que permite que ele se conecte a um modelo Floor.

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

Nota

Para relacionamentos, @id é um campo opcional. Se não @id for fornecido, o processador de interface de gêmeo digital atribuirá um.

Relações direcionadas e não direcionadas

As relações podem ser definidas com ou sem um alvo. Um alvo especifica quais tipos de gêmeos o relacionamento 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.

Às vezes, você pode querer definir um relacionamento sem um alvo específico, para que o relacionamento possa se conectar a muitos tipos diferentes de gêmeos.

Aqui está um exemplo de um relacionamento em um modelo DTDL que não tem um destino. Neste exemplo, a relação serve para definir 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

A DTDL também permite que os relacionamentos 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 Home, onde a rel_has_floors relação tem uma propriedade que representa quando o Floor 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 entra em mais detalhes sobre componentes em modelos 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 DTDL. Este exemplo mostra um modelo de sala que usa um modelo de 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 nesta solução também devem conter um termostato, eles podem fazer referência ao mesmo modelo de termostato como um componente em suas próprias definições, assim como Room faz.

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.

Modelo de herança

Às vezes, você pode querer especializar ainda mais um modelo. Por exemplo, pode ser útil ter um modelo genérico de Sala e variantes especializadas de Sala de Conferências e Ginásio. Para expressar a especialização, a DTDL suporta herança. As interfaces podem herdar de uma ou mais outras interfaces. Você pode fazer isso adicionando um extends campo ao modelo.

A extends seção é 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 modelo base para várias interfaces de extensão.

Nota

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

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

O exemplo a seguir reimagina o modelo Home do exemplo DTDL anterior como um subtipo de um modelo "core" maior. O modelo pai (Core) é definido primeiro e, em seguida, o modelo filho (Home) baseia-se 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": [
    {

Neste caso, o Core contribui com um ID e um nome para a Página Inicial. Outros modelos também podem estender o modelo Core para obter essas propriedades também. 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; só pode acrescentar-lhes. Ele também não pode redefinir um recurso já definido em qualquer uma de suas interfaces pai (mesmo que os recursos sejam definidos como os mesmos). Por exemplo, se uma interface pai define uma propriedademass, a interface de extensão não pode conter uma double declaração de mass, mesmo que também seja um doublearquivo .

Extensões de recursos DTDL v3

A DTDL v3 permite 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 exclusivo do Digital Twin Model Identifier (DTMI). 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 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 adjuntos dessa extensão dentro do modelo. Você pode adicionar tipos adjuntos ao campo de um elemento DTDL, para dar ao @type elemento recursos adicionais. 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. Esta extensão tem um tipo adjunto chamado ValueAnnotation, que é adicionado no exemplo abaixo a um elemento de propriedade. Adicionar esse tipo 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 da 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 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 de 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.

Extensão de substituiçã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 é cotipada com ValueAnnotation (da extensão de anotação). O Override tipo adiciona um campo ao elemento , , que permite nomear um campo no elemento anotado para ser substituído pelo valor do elemento overridesatual.

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 na 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 suportados, consulte a extensão QuantitativeTypes na Descrição da linguagem DTDL v3.

Notas DTDL específicas do serviço

Nem todos os serviços que usam DTDL implementam exatamente os mesmos recursos da DTDL. Existem algumas funcionalidades DTDL que o Azure Digital Twins não suporta atualmente, incluindo:

Comandos DTDL
O writable atributo em propriedades ou relações. Embora esse atributo possa ser definido de acordo com as especificações DTDL, o valor não é usado pelos Gêmeos Digitais do Azure. Em vez disso, esses atributos são sempre tratados como graváveis por clientes externos que têm permissões gerais de gravação para o serviço Gêmeos Digitais do Azure.
As minMultiplicity e maxMultiplicity propriedades nas relações. Embora esses atributos possam ser definidos de acordo com as especificações DTDL, os valores não são impostos pelos Gêmeos Digitais do Azure.

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

Todos os elementos DTDL de nível superior em um modelo devem ser do tipo Interface. A razão para esse requisito é que as APIs de modelo do Azure Digital Twins podem receber objetos JSON que representam uma interface ou uma matriz de interfaces. Como resultado, nenhum outro tipo de elemento DTDL é permitido no nível superior.
DTDL para 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 está sendo usada como um componente não pode ter nenhum componente em si.
As interfaces não podem ser definidas em linha dentro de outras interfaces DTDL; eles devem ser definidos como entidades de nível superior separadas com suas próprias IDs. Em seguida, quando outra interface quiser incluir essa interface como um componente ou por herança, ela poderá fazer referência ao seu ID.

Ferramentas de modelagem e práticas recomendadas

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

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

Considerar as implicações da consulta

Ao projetar modelos para refletir as entidades em seu ambiente, pode ser útil olhar para o futuro e considerar as implicações de consulta do seu design. Você pode querer projetar propriedades de uma forma que evite grandes conjuntos de resultados da travessia de gráficos. Você também pode querer modelar relacionamentos que precisarão ser respondidos em uma única consulta como relacionamentos de nível único.

Validar modelos

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.

Carregue e exclua modelos em massa

Quando terminar de criar, estender ou selecionar seus modelos, você precisará carregá-los em sua instância do Azure Digital Twins para disponibilizá-los para uso em sua solução.

Você pode carregar muitos modelos em uma única chamada de API usando a API de Importação de 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 Trabalhos de Importação é o Exemplo de carregador de modelo, que usa as APIs de modelo individual 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 do modelo. Atualmente, só funciona com a versão 2 da DTDL.

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

Ou, se você quiser limpar os dados em uma instância excluindo todos os modelos junto com todos os gêmeos e relacionamentos, você pode usar a API Excluir trabalhos.

Visualizar modelos

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

Nota

Aqui está um exemplo de como um gráfico de modelo pode parecer:

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

Próximos passos

Saiba mais sobre como criar modelos baseados em ontologias padrão do setor: O que é uma ontologia?
Aprofunde-se no gerenciamento de modelos com operações de API: gerencie modelos DTDL
Saiba como os modelos são usados para criar gêmeos digitais: Gêmeos digitais e o gráfico de gêmeos

Saiba mais sobre modelos de gêmeos e como defini-los no Azure Digital Twins

Digital Twin Definition Language (DTDL) para modelos

Versões DTDL suportadas

Descrição geral do modelo

Atributos do modelo

Propriedades

Esquema

Exemplo de propriedade básica

Exemplo de tipo de objeto complexo

Exemplo de tipo semântico DTDL v2

Relações

Exemplo de relacionamento básico

Relações direcionadas e não direcionadas

Propriedades das relações

Componentes

Exemplo de componente básico

Modelo de herança

Extensões de recursos DTDL v3

Extensão da anotação

Extensão de historização

Extensão de substituição

Extensão QuantitativeTypes

Notas DTDL específicas do serviço

Ferramentas de modelagem e práticas recomendadas

Use ontologias padrão do setor existentes

Considerar as implicações da consulta

Validar modelos

Carregue e exclua modelos em massa

Visualizar modelos

Próximos passos

Recursos adicionais