Compreenda os gémeos digitais e o seu gráfico gémeoUnderstand digital twins and their twin graph

Numa solução Azure Digital Twins, as entidades do seu ambiente são representadas por gémeos digitais Azure.In an Azure Digital Twins solution, the entities in your environment are represented by Azure digital twins. Um gémeo digital é um exemplo de um dos seus modelos personalizados.A digital twin is an instance of one of your custom-defined models. Pode ser conectado a outros gémeos digitais através de relações para formar um gráfico gémeo: este gráfico gémeo é a representação de todo o seu ambiente.It can be connected to other digital twins via relationships to form a twin graph: this twin graph is the representation of your entire environment.

Dica

"Azure Digital Twins" refere-se a este serviço Azure como um todo."Azure Digital Twins" refers to this Azure service as a whole. "Digital twin(s)" ou apenas "twin(s)" refere-se a nódoas gémeas individuais dentro do seu caso do serviço."Digital twin(s)" or just "twin(s)" refers to individual twin nodes inside your instance of the service.

Digital TwinsDigital twins

Antes de criar um gémeo digital na sua instância Azure Digital Twins, precisa de ter um modelo carregado para o serviço.Before you can create a digital twin in your Azure Digital Twins instance, you need to have a model uploaded to the service. Um modelo descreve o conjunto de propriedades, mensagens de telemetria e relacionamentos que um gémeo em particular pode ter, entre outras coisas.A model describes the set of properties, telemetry messages, and relationships that a particular twin can have, among other things. Para os tipos de informação que são definidos num modelo, consulte Conceitos: Modelos personalizados.For the types of information that are defined in a model, see Concepts: Custom models.

Depois de criar e carregar um modelo, a sua aplicação de clientes pode criar uma instância do tipo; este é um gémeo digital.After creating and uploading a model, your client app can create an instance of the type; this is a digital twin. Por exemplo, depois de criar um modelo de Floor, pode criar um ou vários gémeos digitais que usam este tipo (como um twin tipo chão chamado GroundFloor, outro chamado Floor2, etc.).For example, after creating a model of Floor, you may create one or several digital twins that use this type (like a Floor-type twin called GroundFloor, another called Floor2, etc.).

Nota

Gémeos digitais em Azure Digital Twins são diferentes dos gémeos dispositivo no IoT Hub.Digital twins in Azure Digital Twins are different from device twins in IoT Hub. Os gémeos ioT Hub focam-se frequentemente em descrever os aspetos e capacidades de um dispositivo em si, enquanto os gémeos em Azure Digital Twins são representações mais conceptuais que podem armazenar insights definidos pelo utilizador sobre um dispositivo ou muitos dispositivos relacionados.IoT Hub device twins often focus on describing the aspects and capabilities of a device itself, while twins in Azure Digital Twins are more conceptual representations that can store user-defined insights about a device or many related devices.

Os gémeos do dispositivo IoT Hub podem ser ligados à Azure Digital Twins como parte de uma solução de ponta a ponta que representa dispositivos em todos os serviços.IoT Hub device twins can be connected to Azure Digital Twins as part of an end-to-end solution that represents devices across services.

Relacionamentos: um gráfico de gémeos digitaisRelationships: a graph of digital twins

Os gémeos estão ligados a um gráfico gémeo pelas suas relações.Twins are connected into a twin graph by their relationships. As relações que um gémeo pode ter são definidas como parte do seu modelo.The relationships that a twin can have are defined as part of its model.

Por exemplo, o modelo Floor pode definir uma relação de contenção que visa gémeos de tipo quarto.For example, the model Floor might define a contains relationship that targets twins of type room. Com esta definição, a Azure Digital Twins permitirá criar relações de qualquer gémeo do Chão a qualquer quarto gémeo (incluindo gémeos que são de subtipos de Quarto).With this definition, Azure Digital Twins will allow you to create contains relationships from any Floor twin to any Room twin (including twins that are of Room subtypes).

O resultado deste processo é um conjunto de nós (os gémeos digitais) ligados através de bordas (suas relações) num gráfico.The result of this process is a set of nodes (the digital twins) connected via edges (their relationships) in a graph.

VisualizaçãoVisualization

Embora a principal forma de interagir com o seu exemplo de Azure Digital Twins seja através das APIs e SDKs,pode ser útil ver uma visualização dos gémeos e gráficos que está a criar no seu caso.While the primary way to interact with your Azure Digital Twins instance is through the APIs and SDKs, it can be helpful to see a visualization of the twins and graphs that you are creating in your instance.

O explorador Azure Digital Twins (ADT) é uma aplicação de amostra para visualizar e trabalhar com a Azure Digital Twins.The Azure Digital Twins (ADT) explorer is a sample application for visualizing and working with Azure Digital Twins. Siga as instruções fornecidas com a amostra para descarregar e executar o código de aplicação.Follow the instructions provided with the sample to download and run the application code.

Com esta amostra, pode ver uma representação visual dos seus gémeos digitais e o gráfico que criam, entre outras atividades de criação e gestão.With this sample, you can see a visual representation of your digital twins and the graph that they create, among other creation and management activities.

Aqui está uma visão de como a visualização da amostra parece:Here's a view of what the sample visualization looks like:

Screenshot da aplicação de amostra de explorador de Azure Digital Twins, mostrando um gráfico de nóles representando gémeos digitais

Também pode usar a amostra para...You can also use the sample to...

  • Carregar e explorar modelosUpload and explore models
  • Carregar e editar gráficos de gémeosUpload and edit graphs of twins
  • Visualizar o gráfico de gémeos com uma série de técnicas de layoutVisualize the twins graph with a number of layout techniques
  • Editar propriedades de gémeosEdit properties of twins
  • Executar consultas contra o gráfico de gémeosRun queries against the twins graph

Criar com as APIsCreate with the APIs

Esta secção mostra o que parece criar gémeos digitais e relacionamentos a partir de uma aplicação de cliente.This section shows what it looks like to create digital twins and relationships from a client application. Contém exemplos de código .NET que utilizam as APIs DigitalTwins,para fornecer contexto adicional sobre o que se passa dentro de cada um destes conceitos.It contains .NET code examples that utilize the DigitalTwins APIs, to provide additional context on what goes on inside each of these concepts.

Criar duplos digitaisCreate digital twins

Abaixo está um corte de código de cliente que usa as APIs DigitalTwins para instantaneaizar um twin de tipo Room.Below is a snippet of client code that uses the DigitalTwins APIs to instantiate a twin of type Room.

Pode inicializar as propriedades de um gémeo quando é criado, ou defini-las mais tarde.You can initialize the properties of a twin when it is created, or set them later. Para criar um gémeo com propriedades inicializadas, crie um documento JSON que forneça os valores de inicialização necessários.To create a twin with initialized properties, create a JSON document that provides the necessary initialization values.

Você também pode usar uma classe de ajudante chamada BasicDigitalTwin para armazenar campos de propriedade em um objeto "twin" mais diretamente, como uma alternativa para usar um dicionário.You can also use a helper class called BasicDigitalTwin to store property fields in a "twin" object more directly, as an alternative to using a dictionary. Para obter mais informações sobre a classe de ajudante e exemplos da sua utilização, consulte a secção Digital Twin de How-to: Manage digital twins.For more information about the helper class and examples of its use, see the Create a digital twin section of How-to: Manage digital twins.

Nota

Enquanto as propriedades gémeas são tratadas como opcionais e, portanto, não têm de ser inicializadas, quaisquer componentes no twin precisam de ser definidos quando o gémeo é criado.While twin properties are treated as optional and thus don't have to be initialized, any components on the twin do need to be set when the twin is created. Podem ser objetos vazios, mas os próprios componentes devem existir.They can be empty objects, but the components themselves must exist.

Criar relaçõesCreate relationships

Aqui está um código de cliente exemplo que usa as APIs DigitalTwins para construir uma relação entre um twin digital tipo Floor chamado GroundFloor e um twin digital tipo Quarto chamado Café.Here is some example client code that uses the DigitalTwins APIs to build a relationship between a Floor-type digital twin called GroundFloor and a Room-type digital twin called Cafe.

Representações de JSON de elementos gráficosJSON representations of graph elements

Os dados digitais de gémeos e de relacionamento são armazenados no formato JSON.Digital twin data and relationship data are both stored in JSON format. Isto significa que quando consultar o gráfico gémeo no seu exemplo de Azure Digital Twins, o resultado será uma representação JSON de gémeos digitais e relações que criou.This means that when you query the twin graph in your Azure Digital Twins instance, the result will be a JSON representation of digital twins and relationships you have created.

Formato JSON twin digitalDigital twin JSON format

Quando representado como um objeto JSON, um gémeo digital apresentará os seguintes campos:When represented as a JSON object, a digital twin will display the following fields:

Nome do campoField name DescriptionDescription
$dtId Uma cadeia fornecida pelo utilizador que representa o ID do gémeo digitalA user-provided string representing the ID of the digital twin
$etag Campo HTTP padrão atribuído pelo servidor webStandard HTTP field assigned by the web server
$conformance Um enum que contém o estado de conformidade deste gémeo digital (conformante, não-conformante, desconhecido)An enum containing the conformance status of this digital twin (conformant, non-conformant, unknown)
{propertyName} O valor de um imóvel em JSON string (, tipo de número ou objeto)The value of a property in JSON (string, number type, or object)
$relationships A URL do caminho para a coleção de relacionamentos.The URL of the path to the relationships collection. Este campo está ausente se o gémeo digital não tiver limites de relacionamento.This field is absent if the digital twin has no outgoing relationship edges.
$metadata.$model [Opcional] O ID da interface de modelo que caracteriza este gémeo digital[Optional] The ID of the model interface that characterizes this digital twin
$metadata.{propertyName}.desiredValue [Apenas para propriedades writable] O valor desejado do imóvel especificado[Only for writable properties] The desired value of the specified property
$metadata.{propertyName}.desiredVersion [Apenas para propriedades writable] A versão do valor desejado[Only for writable properties] The version of the desired value
$metadata.{propertyName}.ackVersion A versão reconhecida pela aplicação do dispositivo implementando o twin digitalThe version acknowledged by the device app implementing the digital twin
$metadata.{propertyName}.ackCode [Apenas para propriedades writable] O ack código devolvido pela aplicação do dispositivo implementando o twin digital[Only for writable properties] The ack code returned by the device app implementing the digital twin
$metadata.{propertyName}.ackDescription [Apenas para propriedades writable] A ack descrição devolvida pela aplicação do dispositivo implementando o twin digital[Only for writable properties] The ack description returned by the device app implementing the digital twin
{componentName} Um objeto JSON contendo os valores de propriedade e metadados do componente, semelhantes aos do objeto raiz.A JSON object containing the component's property values and metadata, similar to those of the root object. Este objeto existe mesmo que o componente não tenha propriedades.This object exists even if the component has no properties.
{componentName}.{propertyName} O valor da propriedade do componente em JSON string (, tipo de número ou objeto)The value of the component's property in JSON (string, number type, or object)
{componentName}.$metadata A informação de metadados para o componente, semelhante ao nível de raiz $metadataThe metadata information for the component, similar to the root-level $metadata

Aqui está um exemplo de um gémeo digital formatado como um objeto JSON:Here is an example of a digital twin formatted as a JSON object:

{
  "$dtId": "Cafe",
  "$etag": "W/\"e59ce8f5-03c0-4356-aea9-249ecbdc07f9\"",
  "Temperature": 72,
  "Location": {
    "x": 101,
    "y": 33
  },
  "component": {
    "TableOccupancy": 1,
    "$metadata": {
      "TableOccupancy": {
        "desiredValue": 1,
        "desiredVersion": 3,
        "ackVersion": 2,
        "ackCode": 200,
        "ackDescription": "OK"
      }
    }
  },
  "$metadata": {
    "$model": "dtmi:com:contoso:Room;1",
    "Temperature": {
      "desiredValue": 72,
      "desiredVersion": 5,
      "ackVersion": 4,
      "ackCode": 200,
      "ackDescription": "OK"
    },
    "Location": {
      "desiredValue": {
        "x": 101,
        "y": 33,
      },
      "desiredVersion": 8,
      "ackVersion": 8,
      "ackCode": 200,
      "ackDescription": "OK"
    }
  }
}

Relacionamento JSON formatoRelationship JSON format

Quando representado como um objeto JSON, uma relação de um gémeo digital mostrará os seguintes campos:When represented as a JSON object, a relationship from a digital twin will display the following fields:

Nome do campoField name DescriptionDescription
$relationshipId Uma cadeia fornecida pelo utilizador que representa a identificação desta relação.A user-provided string representing the ID of this relationship. Esta cadeia é única no contexto da fonte digital twin, o que também significa que sourceId + relationshipId é única no contexto da instância Azure Digital Twins.This string is unique in the context of the source digital twin, which also means that sourceId + relationshipId is unique in the context of the Azure Digital Twins instance.
$etag Campo HTTP padrão atribuído pelo servidor webStandard HTTP field assigned by the web server
$sourceId O ID da fonte digital twinThe ID of the source digital twin
$targetId A ID do gémeo digital alvoThe ID of the target digital twin
$relationshipName O nome da relaçãoThe name of the relationship
{propertyName} [Opcional] O valor de uma propriedade desta relação, em JSON string (, tipo de número, ou objeto)[Optional] The value of a property of this relationship, in JSON (string, number type, or object)

Aqui está um exemplo de uma relação formatada como um objeto JSON:Here is an example of a relationship formatted as a JSON object:

{
  "$relationshipId": "relationship-01",
  "$etag": "W/\"506e8391-2b21-4ac9-bca3-53e6620f6a90\"",
  "$sourceId": "GroundFloor",
  "$targetId": "Cafe",
  "$relationshipName": "contains",
  "startDate": "2020-02-04"
}

Passos seguintesNext steps

Veja como gerir elementos gráficos com APIs Azure Digital Twin:See how to manage graph elements with Azure Digital Twin APIs:

Ou, saiba se consulta o gráfico gémeo Azure Digital Twins para obter informações:Or, learn about querying the Azure Digital Twins twin graph for information: