Ingerir telemetria do Hub IoT em Gêmeos Digitais do Azure

Artigo
01/04/2024

Este guia percorre o processo de escrever uma função que pode ingerir telemetria de dispositivo do Hub IoT e enviá-la para uma instância dos Gêmeos Digitais do Azure.

O Azure Digital Twins é conduzido com dados de dispositivos IoT e outras fontes. Uma fonte comum de dados de dispositivo a serem usados nos Gêmeos Digitais do Azure é o Hub IoT.

O processo para ingerir dados nos Gêmeos Digitais do Azure é configurar um recurso de computação externo, como uma função criada usando o Azure Functions. A função recebe os dados e usa as APIs do DigitalTwins para definir propriedades ou disparar eventos de telemetria em gêmeos digitais de acordo.

Este documento de instruções percorre o processo de escrita de uma função que pode ingerir telemetria de dispositivo a partir do Hub IoT.

Pré-requisitos

Antes de continuar com este exemplo, você precisará configurar os seguintes recursos como pré-requisitos:

Um hub IoT. Para obter instruções, consulte a seção Criar um Hub IoT deste início rápido do Hub IoT.
Uma instância do Azure Digital Twins que receberá a telemetria do seu dispositivo. Para obter instruções, consulte Configurar uma instância e autenticação do Azure Digital Twins.

Exemplo de cenário de telemetria

Este tutorial descreve como enviar mensagens do Hub IoT para os Gêmeos Digitais do Azure, usando uma função no Azure. Há muitas configurações possíveis e estratégias de correspondência que você pode usar para enviar mensagens, mas o exemplo para este artigo contém as seguintes partes:

Um dispositivo de termostato no Hub IoT, com um ID de dispositivo conhecido
Um gémeo digital para representar o dispositivo, com um ID correspondente

Nota

Este exemplo usa uma correspondência de ID direta entre o ID do dispositivo e o ID de um gêmeo digital correspondente, mas é possível fornecer mapeamentos mais sofisticados do dispositivo para seu gêmeo (como com uma tabela de mapeamento).

Sempre que um evento de telemetria de temperatura é enviado pelo dispositivo termostato, uma função processa a telemetria e a propriedade do gêmeo Temperature digital deve ser atualizada. Este cenário é descrito em um diagrama abaixo:

Diagram of IoT Hub device sending Temperature telemetry to a function in Azure, which updates a Temperature property on a twin in Azure Digital Twins.

Adicionar um modelo e um duplo digital

Nesta seção, você configurará um gêmeo digital nos Gêmeos Digitais do Azure que representará o dispositivo de termostato e será atualizado com informações do Hub IoT.

Para criar um gêmeo do tipo termostato, primeiro você precisará carregar o modelo de termostato para sua instância, que descreve as propriedades de um termostato e será usado posteriormente para criar o gêmeo.

O modelo tem o seguinte aspeto:

{
    "@id": "dtmi:contosocom:DigitalTwins:Thermostat;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "contents": [
      {
        "@type": "Property",
        "name": "Temperature",
        "schema": "double"
      }
    ]
  }

Para carregar esse modelo em sua instância de gêmeos, execute o seguinte comando da CLI do Azure, que carrega o modelo acima como JSON embutido. Você pode executar o comando no Azure Cloud Shell em seu navegador (use o ambiente Bash) ou em sua máquina se tiver a CLI instalada localmente. Há um espaço reservado para o nome do host da instância (você também pode usar o nome amigável da instância com uma ligeira diminuição no desempenho).

az dt model create --dt-name <instance-hostname-or-name> --models '{  "@id": "dtmi:contosocom:DigitalTwins:Thermostat;1",  "@type": "Interface",  "@context": "dtmi:dtdl:context;2",  "contents": [    {      "@type": "Property",      "name": "Temperature",      "schema": "double"    }  ]}'

Nota

Se você estiver usando algo diferente do Cloud Shell no ambiente Bash, talvez seja necessário escapar de certos caracteres no JSON embutido para que ele seja analisado corretamente. Para obter mais informações, consulte Usar caracteres especiais em shells diferentes.

Em seguida, você precisará criar um gêmeo usando este modelo. Use o comando a seguir para criar um termostato gêmeo chamado termostato67 e defina 0,0 como um valor de temperatura inicial. Há um espaço reservado para o nome do host da instância (você também pode usar o nome amigável da instância com uma ligeira diminuição no desempenho).

az dt twin create  --dt-name <instance-hostname-or-name> --dtmi "dtmi:contosocom:DigitalTwins:Thermostat;1" --twin-id thermostat67 --properties '{"Temperature": 0.0}'

Quando o gêmeo é criado com êxito, a saída da CLI do comando deve ter esta aparência:

{
  "$dtId": "thermostat67",
  "$etag": "W/\"0000000-9735-4f41-98d5-90d68e673e15\"",
  "$metadata": {
    "$model": "dtmi:contosocom:DigitalTwins:Thermostat;1",
    "Temperature": {
      "lastUpdateTime": "2021-09-09T20:32:46.6692326Z"
    }
  },
  "Temperature": 0.0
}

Criar a função do Azure

Nesta seção, você criará uma função do Azure para acessar os Gêmeos Digitais do Azure e atualizar gêmeos com base nos eventos de telemetria do dispositivo IoT que ele recebe. Siga as etapas abaixo para criar e publicar a função.

Primeiro, crie um novo projeto do Azure Functions do tipo gatilho de Grade de Eventos.

Você pode fazer isso usando o Visual Studio (para obter instruções, consulte Desenvolver funções do Azure usando o Visual Studio), o Visual Studio Code (para obter instruções, consulte Criar uma função C# no Azure usando o Visual Studio Code ) ou a CLI do Azure (para obter instruções, consulte Criar uma função C# no Azure a partir da linha de comando).
Adicione os seguintes pacotes ao seu projeto (você pode usar o gerenciador de pacotes NuGet do Visual Studio ou o comando dotnet add package em uma ferramenta de linha de comando).

Crie uma função dentro do projeto chamada IoTHubtoTwins.cs. Cole o seguinte código no arquivo de função:

using System;
using Azure;
using System.Net.Http;
using Azure.Core.Pipeline;
using Azure.DigitalTwins.Core;
using Azure.Identity;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Azure.Messaging.EventGrid;

namespace IotHubtoTwins
{
    public class IoTHubtoTwins
    {
        private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
        private static readonly HttpClient httpClient = new HttpClient();

        [FunctionName("IoTHubtoTwins")]
        // While async void should generally be used with caution, it's not uncommon for Azure function apps, since the function app isn't awaiting the task.
#pragma warning disable AZF0001 // Suppress async void error
        public async void Run([EventGridTrigger] EventGridEvent eventGridEvent, ILogger log)
#pragma warning restore AZF0001 // Suppress async void error
        {
            if (adtInstanceUrl == null) log.LogError("Application setting \"ADT_SERVICE_URL\" not set");

            try
            {
                // Authenticate with Digital Twins
                var cred = new DefaultAzureCredential();
                var client = new DigitalTwinsClient(new Uri(adtInstanceUrl), cred);
                log.LogInformation($"ADT service client connection created.");
            
                if (eventGridEvent != null && eventGridEvent.Data != null)
                {
                    log.LogInformation(eventGridEvent.Data.ToString());

                    // <Find_device_ID_and_temperature>
                    JObject deviceMessage = (JObject)JsonConvert.DeserializeObject(eventGridEvent.Data.ToString());
                    string deviceId = (string)deviceMessage["systemProperties"]["iothub-connection-device-id"];
                    var temperature = deviceMessage["body"]["Temperature"];
                    // </Find_device_ID_and_temperature>

                    log.LogInformation($"Device:{deviceId} Temperature is:{temperature}");

                    // <Update_twin_with_device_temperature>
                    var updateTwinData = new JsonPatchDocument();
                    updateTwinData.AppendReplace("/Temperature", temperature.Value<double>());
                    await client.UpdateDigitalTwinAsync(deviceId, updateTwinData);
                    // </Update_twin_with_device_temperature>
                }
            }
            catch (Exception ex)
            {
                log.LogError($"Error in ingest function: {ex.Message}");
            }
        }
    }
}

Salve seu código de função.

Publique o projeto com a função IoTHubtoTwins.cs em um aplicativo de função no Azure.

Para obter instruções sobre como publicar a função usando o Visual Studio, consulte Desenvolver funções do Azure usando o Visual Studio. Para obter instruções sobre como publicar a função usando o Visual Studio Code, consulte Criar uma função C# no Azure usando o Visual Studio Code. Para obter instruções sobre como publicar a função usando a CLI do Azure, consulte Criar uma função C# no Azure a partir da linha de comando.

Quando o processo de publicação da função for concluído, você poderá usar este comando da CLI do Azure para verificar se a publicação foi bem-sucedida. Há espaços reservados para seu grupo de recursos e o nome do seu aplicativo de função. O comando imprimirá informações sobre a função IoTHubToTwins .

az functionapp function show --resource-group <your-resource-group> --name <your-function-app> --function-name IoTHubToTwins

Configurar a aplicação de funções

Para acessar os Gêmeos Digitais do Azure, seu aplicativo de função precisa de uma identidade gerenciada atribuída pelo sistema com permissões para acessar sua instância dos Gêmeos Digitais do Azure. Você definirá isso nesta seção, atribuindo uma função de acesso para a função e definindo as configurações do aplicativo para que ele possa acessar sua instância do Azure Digital Twins.

Execute os seguintes comandos no Azure Cloud Shell ou em uma CLI do Azure local.

Nota

Esta seção deve ser concluída por um usuário do Azure que tenha permissões para gerenciar o acesso do usuário aos recursos do Azure, incluindo a concessão e delegação de permissões. As funções comuns que atendem a esse requisito são Proprietário, Administrador de conta ou a combinação de Administrador de Acesso de Usuário e Colaborador. Para obter mais informações sobre os requisitos de permissão para funções do Azure Digital Twins, consulte Configurar uma instância e autenticação.

Atribuir uma função de acesso

A função do Azure requer que um token de portador seja passado para ela. Para garantir que o token de portador seja passado, conceda ao aplicativo de função a função Proprietário de Dados de Gêmeos Digitais do Azure para sua instância de Gêmeos Digitais do Azure, que dará permissão ao aplicativo de função para executar atividades de plano de dados na instância.

Use o comando a seguir para criar uma identidade gerenciada pelo sistema para sua função (se a função já tiver uma, esse comando imprimirá seus detalhes). Anote o principalId campo na saída. Você usará essa ID para fazer referência à função para que possa conceder-lhe permissões na próxima etapa.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```
Use o principalId valor no comando a seguir para dar à função a função Proprietário de Dados de Gêmeos Digitais do Azure para sua instância de Gêmeos Digitais do Azure.
```
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
```

Configurar definições da aplicação

Em seguida, torne a URL da sua instância do Azure Digital Twins acessível à sua função definindo uma variável de ambiente para ela.

Gorjeta

A URL da instância do Azure Digital Twins é feita adicionando https:// ao início do nome de host da sua instância. Para ver o nome do host, juntamente com todas as propriedades da sua instância, execute az dt show --dt-name <your-Azure-Digital-Twins-instance>.

O comando a seguir define uma variável de ambiente para a URL da sua instância que sua função usará sempre que precisar acessar a instância.

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

Conectar a função ao Hub IoT

Nesta seção, você configurará sua função como um destino de evento para os dados do dispositivo do hub IoT. Configurar sua função dessa maneira garantirá que os dados do dispositivo termostato no Hub IoT sejam enviados para a função do Azure para processamento.

Use o comando da CLI a seguir para criar uma assinatura de evento que o Hub IoT usará para enviar dados de eventos para a função IoTHubtoTwins . Há um espaço reservado para você inserir um nome para a assinatura do evento e também há espaços reservados para você inserir sua ID de assinatura, grupo de recursos, nome do hub IoT e o nome do seu aplicativo de função.

az eventgrid event-subscription create --name <name-for-hub-event-subscription> --event-delivery-schema eventgridschema --source-resource-id /subscriptions/<your-subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.Devices/IotHubs/<your-IoT-hub> --included-event-types Microsoft.Devices.DeviceTelemetry --endpoint-type azurefunction --endpoint /subscriptions/<your-subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.Web/sites/<your-function-app>/functions/IoTHubtoTwins

A saída mostrará informações sobre a assinatura do evento que foi criada. Você pode confirmar que a operação foi concluída com êxito verificando o provisioningState valor no resultado:

"provisioningState": "Succeeded",

Teste com dados de IoT simulados

Você pode testar sua nova função de entrada usando o simulador de dispositivo de Connect uma solução de ponta a ponta. O projeto DeviceSimulator contém um dispositivo de termostato simulado que envia dados de temperatura de amostra. Para configurar o simulador de dispositivo, siga estes passos:

Navegue até o repositório de projeto de exemplo de ponta a ponta do Azure Digital Twins. Obtenha o projeto de exemplo em sua máquina selecionando o botão Procurar código abaixo do título. Isso levará você ao repositório GitHub para os exemplos, que você pode baixar como um .zip selecionando o botão Código seguido de Baixar ZIP.

Isso fará o download de uma pasta .zip para sua máquina como digital-twins-samples-main.zip. Descompacte a pasta e extraia os arquivos. Você usará a pasta do projeto DeviceSimulator .
Registrar o dispositivo simulado com o Hub IoT
Configurar e executar a simulação

Depois de concluir essas etapas, você deve ter uma janela do console do projeto executando e enviando dados simulados de telemetria do dispositivo para seu hub IoT.

Screenshot of the output from the device simulator project.

Validar resultados

Ao executar o simulador de dispositivo acima, o valor da temperatura do seu termostato gêmeo digital estará mudando. Na CLI do Azure, execute o seguinte comando para ver o valor da temperatura. Há um espaço reservado para o nome do host da instância (você também pode usar o nome amigável da instância com uma ligeira diminuição no desempenho).

az dt twin query --query-command "SELECT * FROM digitaltwins WHERE \$dtId = 'thermostat67'" --dt-name <instance-hostname-or-name>

Nota

Se você estiver usando algo diferente do Cloud Shell no ambiente Bash, talvez seja necessário escapar do $ caractere na consulta de forma diferente para que ele seja analisado corretamente. Para obter mais informações, consulte Usar caracteres especiais em shells diferentes.

Sua saída deve mostrar os detalhes do termostato gêmeo67, incluindo um valor de temperatura, assim:

{
  "result": [
    {
      "$dtId": "thermostat67",
      "$etag": "W/\"dbf2fea8-d3f7-42d0-8037-83730dc2afc5\"",
      "$metadata": {
        "$model": "dtmi:contosocom:DigitalTwins:Thermostat;1",
        "Temperature": {
          "lastUpdateTime": "2021-06-03T17:05:52.0062638Z"
        }
      },
      "Temperature": 70.20518558807913
    }
  ]
}

Para ver a alteração de valor, execute repetidamente o comando de Temperature consulta acima.

Próximos passos

Leia sobre a entrada e saída de dados com os Gêmeos Digitais do Azure:

Entrada e saída de dados

Share via

Ingerir telemetria do Hub IoT em Gêmeos Digitais do Azure

Pré-requisitos

Exemplo de cenário de telemetria

Adicionar um modelo e um duplo digital

Criar a função do Azure

Configurar a aplicação de funções

Atribuir uma função de acesso

Configurar definições da aplicação

Conectar a função ao Hub IoT

Teste com dados de IoT simulados

Validar resultados

Próximos passos

Recursos adicionais