Processamento de dados e funções definidas pelo usuário

Artigo
01/03/2020

Importante

Uma nova versão do serviço dos Gêmeos Digitais do Azure foi lançada. À luz dos recursos expandidos do novo serviço, o serviço original dos Gêmeos Digitais do Azure (descrito neste conjunto de documentação) foi desativado.

Para exibir a documentação do novo serviço, visite a documentação ativa dos Gêmeos Digitais do Azure.

O recurso Gêmeos Digitais do Azure oferece funcionalidades de computação avançadas. Os desenvolvedores podem definir e executar funções personalizadas contra mensagens de telemetria recebidas para enviar eventos para pontos de extremidade predefinidos.

Fluxo de processamento de dados

Depois que os dispositivos enviam dados de telemetria para o Azure Digital Twins, os desenvolvedores podem processar dados em quatro fases: validar, corresponder, computar, e despachar.

A fase de validação transforma a mensagem de telemetria recebida em um formato de objeto de transferência de dados comumente entendido. Essa fase também executa validação de dispositivo e sensor.
A fase corresponder localiza as funções definidas pelo usuário a serem executadas. Os correspondentes predefinidos descobrirão as funções definidas pelo usuário com base em informações de dispositivo, sensor e espaço da mensagem de telemetria de entrada.
O computador executa as funções definidas pelo usuário correspondente na fase anterior. Essas funções podem ler e atualizar valores calculados em nós de gráfico espacial e podem emitir notificações personalizadas.
A fase de expedição encaminha quaisquer notificações personalizadas da fase de cálculo para os pontos finais definidos no gráfico.

Objetos de processamento de dados

O processamento de dados no Gêmeos Digitais do Azure consiste na definição de três objetos: correspondentes, funções definidas pelo usuário e atribuições de funções.

Correspondências

Correspondentes definem um conjunto de condições que avaliam quais ações ocorrem com base na telemetria do sensor de entrada. As condições para determinar a correspondência podem incluir propriedades do sensor, do dispositivo pai do sensor e do espaço pai do sensor. As condições são expressas como comparações em relação a um caminho JSON, conforme descrito neste exemplo:

Todos os sensores de Datatype Temperatura representados pelo valor de cadeia de caracteres de escape \"Temperature\"
Tendo 01 em sua porta
Que pertencem a dispositivos com a chave de propriedade estendida Fabricante definido para o valor da cadeia de caracteres de escape\"Contoso\"
Que pertencem aos espaços do tipo especificado pela cadeia de caracteres com escape \"Venue\"
Que são descendentes do SpaceId pai DE8F06CA-1138-4AD7-89F4-F782CC6F69FD

{
  "id": "23535afafd-f39b-46c0-9b0c-0dd3892a1c30",
  "name": "My custom matcher",
  "spaceId": "DE8F06CA-1138-4AD7-89F4-F782CC6F69FD",
  "description": "All sensors of datatype Temperature with 01 in their port that belong to devices with the extended property key Manufacturer set to the value Contoso and that belong to spaces of type Venue that are somewhere below space Id DE8F06CA-1138-4AD7-89F4-F782CC6F69FD",
  "conditions": [
    {
      "id": "43898sg43-e15a-4e9c-abb8-2gw464364",
      "target": "Sensor",
      "path": "$.dataType",
      "value": "\"Temperature\"",
      "comparison": "Equals"
    },
    {
      "id": "wt3th44-e15a-35sg-seg3-235wf3ga463",
      "target": "Sensor",
      "path": "$.port",
      "value": "01",
      "comparison": "Contains"
    },
    {
      "id": "735hs33-e15a-37jj-23532-db901d550af5",
      "target": "SensorDevice",
      "path": "$.properties[?(@.name == 'Manufacturer')].value",
      "value": "\"Contoso\"",
      "comparison": "Equals"
    },
    {
      "id": "222325-e15a-49fg-5744-463643644",
      "target": "SensorSpace",
      "path": "$.type",
      "value": "\"Venue\"",
      "comparison": "Equals"
    }
  ]
}

Importante

Demarcadores JSON diferenciam maiúsculas de minúsculas.
A carga JSON é a mesma que a carga retornada por:
- /sensors/{id}?includes=properties,types para o sensor.
- /devices/{id}?includes=properties,types,sensors,sensorsproperties,sensorstypes para o dispositivo pai do sensor.
- /spaces/{id}?includes=properties,types,location,timezone para o espaço do pai do sensor.
As comparações são insensíveis a maiúsculas e minúsculas.

Funções definidas pelo usuário

Uma função definida pelo usuário é uma função personalizada executada em um ambiente isolado nos Gêmeos Digitais do Azure. As funções definidas pelo usuário têm acesso à mensagem de telemetria do sensor bruto à medida que foi recebida. As funções definidas pelo usuário também têm acesso ao serviço de gráfico espacial e despachante. Depois que a função definida pelo usuário é registrada no gráfico, um correspondente (detalhado acima) deve ser criado para especificar quando executar a função. Por exemplo, quando os Gêmeos Digitais do Azure recebem nova telemetria de um determinado sensor, a função definida pelo usuário correspondente pode calcular uma média móvel das últimas poucas leituras do sensor.

As funções definidas pelo usuário podem ser gravadas no JavaScript. Os métodos auxiliares interagem com o gráfico no ambiente de execução definido pelo usuário. Os desenvolvedores podem executar snippets personalizados de código contra mensagens de telemetria do sensor. Os exemplos incluem:

Defina a leitura do sensor diretamente para o objeto do sensor no grafo.
Execute uma ação com base em diferentes leituras de sensor dentro de um espaço no grafo.
Crie uma notificação quando determinadas condições forem atendidas para uma leitura de sensor de entrada.
Anexe metadados de grafo à leitura do sensor antes de enviar uma notificação do sensor.

Para obter mais informações, leia Como usar funções definidas pelo usuário.

Exemplos

O repositório GitHub para a amostra C# dos Gêmeos Digitais contém alguns exemplos das funções definidas pelo usuário:

Essa função procura os valores de dióxido de carbono, de movimento e de temperatura para determinar se uma sala está disponível com esses valores no intervalo. Os tutoriais dos Gêmeos Digitais exploram essa função mais detalhadamente.
Essa função procura os dados de vários sensores de movimento e determina que o espaço está disponível se nenhum deles detecta qualquer movimento. Você pode substituir com facilidade a função definida pelo usuário usada no início rápido, ou nos tutoriais, fazendo as alterações mencionadas na seção de comentários do arquivo.

Atribuição de função

As ações de uma função definida pelo usuário estão sujeitas a controle de acesso baseado em função de Gêmeos Digitais para proteger os dados dentro do serviço. As atribuições de função definem quais funções definidas pelo usuário têm as permissões adequadas para interagir com o gráfico espacial e suas entidades. Por exemplo, uma função definida pelo usuário pode ter a capacidade e a permissão para CIAR, LER, ATUALIZAR, ou EXCLUIR dados de gráfico em um determinado espaço. Um nível da função definido pelo usuário de acesso é verificado quando a função definida pelo usuário solicita o gráfico de dados ou tenta efetuar uma ação. Para obter mais informações, leia Controle de acesso baseado em função.

É possível uma correspondência disparar uma função definida pelo usuário que não tenha atribuições de função. Nesse caso, a função definida pelo usuário não consegue ler nenhum dado do gráfico.

Próximas etapas

Para saber mais sobre como rotear eventos e mensagens de telemetria para outros serviços do Azure, leia Rotear eventos e mensagens.
Para saber mais sobre como criar correspondentes, funções definidas pelo usuário e atribuições de função, leia o Guia para usar funções definidas pelo usuário.
Revise a documentação de referência da biblioteca de clientes de função definida pelo usuário.

Compartilhar via