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

Artigo
06/18/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. Eles têm nomes (como Room ou TemperatureSensor) e contêm elementos como propriedades, componentes e relacionamentos que descrevem o que esse tipo de entidade no 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 (Linguagem de Definição de Gêmeos Digitais).

Você pode exibir a descrição completa da linguagem para DTDL v3 no GitHub: Descrição da linguagem DTDL versão 3. Esta página inclui exemplos e detalhes de referência de DTDL para ajudar você a começar a escrever seus modelos em 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. Ela é usada para representar dados de dispositivo 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 com suporte

Os Gêmeos Digitais do Azure dão suporte ao DTDL versões 2 e 3 (abreviadas na documentação como 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 do DTMI
Matriz de suporte para propriedades
Aumento dos limites para herança do modelo
Extensões de recurso
- 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 de 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 dos modelos v2 e v3 na mesma instância. Ao usar modelos de ambas as versões em conjunto, 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.
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, confira Converter modelos v2 para v3.

Observação

Atualmente, o Azure Digital Twins Explorer dá suporte total a modelos DTDL v2 e funcionalidade limitada para modelos DTDL v3.

Os modelos DTDL v3 podem ser exibidos no painel Modelos, e os gêmeos criados com modelos DTDL v3 podem ser exibidos e editados (inclusive aqueles com propriedades de matriz). Entretanto, os modelos DTDL v3 não serão exibidos no painel do Gráfico de Modelos e não poderão ser importados usando o Azure Digital Twins Explorer. Para importar modelos DTDL v3 para sua instância, utilize outra interface de desenvolvedor, como as 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 DTMI (Identificador de Modelo de Gêmeo Digital) 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 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] 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 `@type` (`Property`, `Relationship` ou `Component`) para identificar o tipo de informações de interface que ele descreve e, em seguida, um 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 com suporte nos Gêmeos Digitais do Azure. Uma interface de modelo do DTDL usada para os Gêmeos Digitais do Azure pode conter zero, um ou muitos 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 significados semânticos diferentes, como contains ("andar contém sala"), cools ("ar-condicionado resfria sala"), isBilledTo ("o 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 componente é a interface frontCamera (e outra interface de componente backCamera) que é usada na definição de um modelo de 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 da 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 dos Gêmeos Digitais do Azure. Em vez de usar a telemetria do DTDL, você deve usar as propriedades do DTDL para armazenar informações do estado do gêmeo.

Observação

Embora não haja necessidade de 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 de Mensagem de Telemetria do Gêmeo Digital que pode ser recebido por um manipulador de eventos para executar ações em outros gêmeos ou disparar serviços downstream.

Propriedades

Esta seção apresenta mais detalhes sobre as propriedades nos modelos de DTDL.

Para obter informações abrangentes sobre os campos que podem aparecer como parte de uma propriedade, confira Propriedade na Descrição de 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 de atributos de propriedade pode ser de tipos primitivos padrão (integer, double, string e boolean) e outros tipos, como dateTime e duration.

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

Object
Map
Enum
Array, somente no DTDL v3. Tipo Array de propriedades não tem suporte no DTDL v2.

Eles também podem ser tipos semânticos, que permitem anotar valores com unidades. No DTDL v2, tipos semânticos têm suporte nativo; 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 do tipo de objeto complexo

As propriedades podem ser do tipo complexo, incluindo um tipo Object.

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 do DTDL v2

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 do DTDL.

No DTDL v2, os tipos semânticos têm suporte nativo. Para obter mais informações sobre tipos semânticos no DTDL v2, consulte Tipos semânticos na Descrição de Linguagem DTDL v2. Para saber mais sobre tipos semânticos no DTDL v3, consulte a extensão de recurso QuantitativeTypes do DTDL v3.

O exemplo a seguir mostra um modelo do Sensor do 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 matriz @type, 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 apresenta mais detalhes sobre as relações nos modelos de DTDL.

Para obter uma lista abrangente dos campos que podem aparecer como parte de uma relação, confira Relação na Descrição de 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 de Casa só pode ter uma relação de rel_has_floors com gêmeos que são de gêmeos de Andar.

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. Ao definir uma relação em um modelo DTDL, a relação pode ter seu próprio campo properties, onde você pode definir propriedades personalizadas para descrever o estado específico da relação.

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, confira Componente na Descrição de 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 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 extends.

No DTDL v2 e v3, o limite de profundidade total para uma hierarquia de extends é 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",
  "extends": "dtmi:com:adt:dtsample:core;1",

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 do DTDL v3

O 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 de DTMI (Identificador de Modelo de Gêmeo Digital) exclusivo. Para habilitar uma extensão de recurso em um modelo, adicione o especificador de contexto da extensão ao campo @context do modelo (juntamente com o especificador de contexto DTDL geral de dtmi:dtdl:context;3). Você pode adicionar várias extensões de recursos ao mesmo modelo.

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

  "@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 @type de um elemento DTDL para fornecer ao elemento de 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 de anotação. Essa 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 annotates adicional, que é usado para indicar outra propriedade anotada por esse elemento.

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

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

Extensão de anotação

A extensão de anotação é 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 tipo adjunto ValueAnnotation, que pode ser adicionado a um elemento de propriedade DTDL. O tipo ValueAnnotation adiciona um campo ao elemento, annotates, que permite nomear outra propriedade anotada pelo elemento atual.

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 Historização é 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 horários em que os valores são alterados). Seu especificador de contexto é dtmi:dtdl:extension:historization;1.

Essa extensão inclui o tipo adjunto Historized, que pode ser adicionado como um co-tipo a um elemento de propriedade DTDL para indicar que o serviço deve persistir os valores históricos do elemento e disponibilizá-los para consulta e análise. O tipo adjunto Historized não adiciona campos 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. Ela é usada em conjunto com a extensão de anotação e seu especificador de contexto é dtmi:dtdl:extension:overriding;1.

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

Para obter mais detalhes e exemplos dessa extensão, consulte Extensão de substituiçã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, Campo, MapValue ou a uma propriedade no DTDL v3. 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 semânticos e unidades com suporte, consulte Extensão QuantitativeTypes na Descrição da Linguagem DTDL v3.

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 da DTDL de nível superior no 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 as atuais ontologias padrão do setor

Uma ontologia é um conjunto de modelos que descrevem de forma abrangente um determinado domínio, como a fabricação, criação de estruturas, sistemas de IoT, cidades inteligentes, grades de energia, conteúdo da Web e muito mais.

Se sua solução for destinada a um determinado setor que usa qualquer tipo de padrão de modelo, considere começar com um conjunto preexistente de modelos para seu setor, em vez de criar modelos do zero. A Microsoft estabeleceu parcerias com especialistas no assunto para criar ontologias de modelos DTDL com base em padrões do setor, a fim de ajudar a minimizar a reinvenção e incentivar a consistência e a simplicidade nas 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 ajudar você a fazer isso, uma biblioteca de análise de DTDL do lado do cliente .NET é fornecida no NuGet: DTDLParser. Você pode usar a biblioteca do analisador diretamente no código C#. Também é possível 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 muitos modelos em uma única chamada à API usando a API de Trabalhos de Importação. A API pode aceitar simultaneamente até o limite dos 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 uploader de modelo, que usa as APIs de modelo individuais para carregar vários arquivos de modelo ao mesmo tempo. 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 dos Gêmeos Digitais do Azure de uma só vez, você pode usar o Exemplo de Excluidor de Modelo. Este é um projeto que contém lógica recursiva para lidar com 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 relações, poderá usar a API de Trabalhos de Exclusão.

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

Atualmente, o Azure Digital Twins Explorer dá suporte total a modelos DTDL v2 e funcionalidade limitada para modelos DTDL v3.

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

Compartilhar via

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 com suporte

Visão geral do modelo

Atributos de modelo

Propriedades

Esquema

Exemplo de propriedade básica

Exemplo do tipo de objeto complexo

Exemplo de tipo semântico do DTDL v2

Relações

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 do DTDL v3

Extensão de anotação

Extensão de historização

Extensão de substituição

Extensão QuantitativeTypes

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

Ferramentas de modelagem e melhores práticas

Usar as atuais ontologias padrão do setor

Considerar as implicações de consulta

Validar modelos

Carregar e excluir modelos em massa

Visualizar modelos

Próximas etapas

Comentários

Recursos adicionais