Partilhar via

Integrar o Azure Digital Twins com Azure Time Series Insights

  • Artigo

Neste artigo, irá aprender a integrar o Azure Digital Twins com Azure Time Series Insights (TSI).

A solução descrita neste artigo utiliza o Time Series Insights para recolher e analisar dados históricos sobre a sua solução de IoT. O Azure Digital Twins é uma boa opção para alimentar dados no Time Series Insights, uma vez que lhe permite correlacionar vários fluxos de dados e uniformizar as suas informações antes de as enviar para o Time Series Insights.

Dica

A forma mais simples de analisar dados duplos históricos ao longo do tempo é utilizar a funcionalidade de histórico de dados para ligar uma instância do Azure Digital Twins a um cluster do Azure Data Explorer, para que as atualizações de grafos sejam automaticamente historizadas no Azure Data Explorer. Em seguida, pode consultar estes dados no Azure Data Explorer com o plug-in de consulta do Azure Digital Twins para o Azure Data Explorer. Se não precisar de utilizar especificamente o Time Series Insights, poderá considerar esta alternativa para uma experiência de integração mais simples.

Pré-requisitos

Antes de poder configurar uma relação com o Time Series Insights, terá de configurar os seguintes recursos:

Dica

Neste artigo, os valores de duplo digital que são visualizados no Time Series Insights são atualizados manualmente para simplificar. No entanto, se quiser concluir este artigo com dados simulados em direto, pode configurar uma função do Azure que atualiza duplos digitais com base em eventos de telemetria IoT a partir de um dispositivo simulado. Para obter instruções, siga Ingestão Hub IoT dados, incluindo os passos finais para executar o simulador do dispositivo e validar que o fluxo de dados funciona.

Mais tarde, procure outra SUGESTÃO para lhe mostrar onde começar a executar o simulador de dispositivos e fazer com que as suas funções do Azure atualizem automaticamente os duplos, em vez de enviarem comandos manuais de atualização de duplos digitais.

Arquitetura de soluções

Vai anexar o Time Series Insights ao Azure Digital Twins através do seguinte caminho.

Diagrama dos serviços do Azure num cenário ponto a ponto, realçando o Time Series Insights.

Criar o espaço de nomes dos Hubs de Eventos

Antes de criar os hubs de eventos, primeiro irá criar um espaço de nomes dos Hubs de Eventos que receberá eventos da sua instância do Azure Digital Twins. Pode utilizar as instruções da CLI do Azure abaixo ou utilizar o portal do Azure ao seguir Criar um hub de eventos com portal do Azure. Para ver que regiões suportam os Hubs de Eventos, visite os produtos do Azure disponíveis por região.

az eventhubs namespace create --name <name-for-your-Event-Hubs-namespace> --resource-group <your-resource-group> --location <region>

Dica

Se receber um erro a indicar BadRequest: The specified service namespace is invalid., certifique-se de que o nome que escolheu para o seu espaço de nomes cumpre os requisitos de nomenclatura descritos neste documento de referência: Criar Espaço de Nomes.

Irá utilizar este espaço de nomes dos Hubs de Eventos para conter os dois hubs de eventos necessários para este artigo:

  1. Hub twins - Hub de eventos para receber eventos de alteração de duplos
  2. Hub de série temporal – Hub de eventos para transmitir eventos para o Time Series Insights

As secções seguintes irão orientá-lo ao longo da criação e configuração destes hubs no espaço de nomes do hub de eventos.

Criar hub duplos

O primeiro hub de eventos que irá criar neste artigo é o hub duplo. Este hub de eventos receberá eventos de alteração de duplos do Azure Digital Twins. Para configurar o hub duplo, irá concluir os seguintes passos nesta secção:

  1. Criar o hub duplo
  2. Criar uma regra de autorização para controlar as permissões para o hub
  3. Criar um ponto final no Azure Digital Twins que utiliza a regra de autorização para aceder ao hub
  4. Criar uma rota no Azure Digital Twins que envia o evento de atualizações de duplos para o ponto final e o hub duplo ligado
  5. Obter a cadeia de ligação do hub duplo

Crie o hub duplo com o seguinte comando da CLI. Especifique um nome para o hub duplo.

az eventhubs eventhub create --name <name-for-your-twins-hub> --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier>

Criar regra de autorização do hub duplo

Crie uma regra de autorização com permissões de envio e receção. Especifique um nome para a regra.

az eventhubs eventhub authorization-rule create --rights Listen Send --name <name-for-your-twins-hub-auth-rule> --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier> --eventhub-name <your-twins-hub-from-earlier>

Criar ponto final do hub duplo

Crie um ponto final do Azure Digital Twins que ligue o seu hub de eventos à sua instância do Azure Digital Twins. Especifique um nome para o ponto final do hub duplo.

az dt endpoint create eventhub --dt-name <your-Azure-Digital-Twins-instance-name> --eventhub-resource-group <your-resource-group> --eventhub-namespace <your-Event-Hubs-namespace-from-earlier> --eventhub <your-twins-hub-name-from-earlier> --eventhub-policy <your-twins-hub-auth-rule-from-earlier> --endpoint-name <name-for-your-twins-hub-endpoint>

Criar rota de eventos do hub duplo

As instâncias do Azure Digital Twins podem emitir eventos de atualização de duplos sempre que o estado de um duplo for atualizado. Nesta secção, irá criar uma rota de eventos do Azure Digital Twins que irá direcionar estes eventos de atualização para o hub twins para processamento adicional.

Crie uma rota no Azure Digital Twins para enviar eventos de atualização de duplos para o ponto final acima. O filtro nesta rota só permitirá que as mensagens de atualização de duplos sejam transmitidas para o ponto final. Especifique um nome para a rota de eventos do hub duplo. Para o marcador de posição do nome da instância do Azure Digital Twins neste comando, pode utilizar o nome amigável ou o nome do anfitrião para aumentar o desempenho.

az dt route create --dt-name <your-Azure-Digital-Twins-instance-hostname-or-name> --endpoint-name <your-twins-hub-endpoint-from-earlier> --route-name <name-for-your-twins-hub-event-route> --filter "type = 'Microsoft.DigitalTwins.Twin.Update'"

Obter a cadeia de ligação do hub duplo

Obtenha a cadeia de ligação do hub de eventos duplos com as regras de autorização que criou acima para o hub duplo.

az eventhubs eventhub authorization-rule keys list --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier> --eventhub-name <your-twins-hub-from-earlier> --name <your-twins-hub-auth-rule-from-earlier>

Tome nota do valor primaryConnectionString do resultado para configurar a definição da aplicação hub duplo mais adiante neste artigo.

Criar um hub de série temporal

O segundo hub de eventos que irá criar neste artigo é o hub de série temporal. Este hub de eventos é aquele que transmitirá os eventos do Azure Digital Twins para o Time Series Insights. Para configurar o hub de série temporal, irá concluir estes passos:

  1. Criar o hub de série temporal
  2. Criar uma regra de autorização para controlar as permissões para o hub
  3. Obter a cadeia de ligação do hub de série temporal

Mais tarde, quando criar a instância do Time Series Insights, irá ligar este hub de série temporal como a origem de eventos da instância do Time Series Insights.

Crie o hub de série temporal com o seguinte comando. Especifique um nome para o hub de série temporal.

 az eventhubs eventhub create --name <name-for-your-time-series-hub> --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier>

Criar regra de autorização do hub de série temporal

Crie uma regra de autorização com permissões de envio e receção. Especifique um nome para a regra de autenticação do hub de série temporal.

az eventhubs eventhub authorization-rule create --rights Listen Send --name <name-for-your-time-series-hub-auth-rule> --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier> --eventhub-name <your-time-series-hub-name-from-earlier>

Obter cadeia de ligação do hub de série temporal

Obtenha a cadeia de ligação do hub de série temporal com as regras de autorização que criou acima para o hub de série temporal:

az eventhubs eventhub authorization-rule keys list --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier> --eventhub-name <your-time-series-hub-name-from-earlier> --name <your-time-series-hub-auth-rule-from-earlier>

Tome nota do valor primaryConnectionString do resultado para configurar a definição da aplicação hub de série temporal mais adiante neste artigo.

Além disso, tome nota dos seguintes valores para os utilizar mais tarde para criar uma instância do Time Series Insights.

  • Espaço de nomes do hub de eventos
  • Nome do hub da série temporal
  • Regra de autenticação do hub de série temporal

Criar uma função

Nesta secção, irá criar uma função do Azure que irá converter eventos de atualização de duplos do formulário original como documentos JSON Patch em objetos JSON que contêm apenas valores atualizados e adicionados dos seus duplos.

  1. Primeiro, crie um novo projeto de aplicação de funções.

    Pode fazê-lo com o Visual Studio (para obter instruções, consulte Desenvolver Funções do Azure com o Visual Studio), Visual Studio Code (para obter instruções, consulte Criar uma função C# no Azure com 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 comandos).

  2. Crie uma nova função do Azure denominada ProcessDTUpdatetoTSI.cs para atualizar eventos de telemetria do dispositivo para o Time Series Insights. O tipo de função será acionador do Hub de Eventos.

    Captura de ecrã do Visual Studio para criar uma nova função do Azure do tipo acionador do hub de eventos.

  3. Adicione os seguintes pacotes ao seu projeto (pode utilizar o gestor de pacotes NuGet do Visual Studio ou o comando dotnet add package numa ferramenta de linha de comandos).

  4. Substitua o código no ficheiro ProcessDTUpdatetoTSI.cs pelo seguinte código:

    using System.Collections.Generic;
using System.Threading.Tasks;
using System.Text;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Azure.Messaging.EventHubs;

namespace UpdateTSI
{
    public static class ProcessDTUpdatetoTSI
    { 
        [FunctionName("ProcessDTUpdatetoTSI")]
        public static async Task Run(
            [EventHubTrigger("twins-event-hub", Connection = "EventHubAppSetting-Twins")]EventData myEventHubMessage,
            [EventHub("tsi-event-hub", Connection = "EventHubAppSetting-TSI")]IAsyncCollector<string> outputEvents,
            ILogger log)
        {
            JObject message = (JObject)JsonConvert.DeserializeObject(Encoding.UTF8.GetString(myEventHubMessage.Body));
            log.LogInformation($"Reading event: {message}");

            // Read values that are replaced or added
            var tsiUpdate = new Dictionary<string, object>();
            foreach (var operation in message["patch"])
            {
                if (operation["op"].ToString() == "replace" || operation["op"].ToString() == "add")
                {
                    //Convert from JSON patch path to a flattened property for TSI
                    //Example input: /Front/Temperature
                    //        output: Front.Temperature
                    string path = operation["path"].ToString().Substring(1);
                    path = path.Replace("/", ".");
                    tsiUpdate.Add(path, operation["value"]);
                }
            }
            // Send an update if updates exist
            if (tsiUpdate.Count > 0)
            {
                tsiUpdate.Add("$dtId", myEventHubMessage.Properties["cloudEvents:subject"]);
                await outputEvents.AddAsync(JsonConvert.SerializeObject(tsiUpdate));
            }
        }
    }
}

    Guarde o código da função.

  5. Publique o projeto com a função ProcessDTUpdatetoTSI.cs numa aplicação de funções no Azure.

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

Guarde o nome da aplicação de funções para utilizar mais tarde para configurar as definições da aplicação para os dois hubs de eventos.

Configurar a aplicação de funções

Em seguida, atribua uma função de acesso para a função e configure as definições da aplicação para que possa aceder aos seus recursos.

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

Nota

Esta secção tem de ser concluída por um utilizador do Azure que tenha permissões para gerir o acesso dos utilizadores aos recursos do Azure, incluindo a concessão e delegação de permissões. As funções comuns que cumprem este requisito são Proprietário, Administrador de conta ou a combinação de Administrador e Contribuidor de Acesso de Utilizador. Para obter mais informações sobre os requisitos de permissão para funções do Azure Digital Twins, veja Configurar uma instância e autenticação.

Atribuir uma função de acesso

A função do Azure requer que lhe seja transmitido um token de portador. Para se certificar de que o token de portador é transmitido, conceda à aplicação de funções a função Proprietário de Dados do Azure Digital Twins para a instância do Azure Digital Twins, o que dará permissão à aplicação de funções para realizar atividades de plano de dados na instância.

  1. Utilize o seguinte comando para criar uma identidade gerida pelo sistema para a sua função (se a função já tiver uma, este comando irá imprimir os respetivos detalhes). Tome nota do principalId campo na saída. Irá utilizar este ID para fazer referência à função para que possa conceder-lhe permissões no passo seguinte.

    az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>

  2. Utilize o principalId valor no seguinte comando para atribuir à função a função Proprietário de Dados do Azure Digital Twins para a sua instância do Azure Digital Twins.

    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 o URL da sua instância do Azure Digital Twins acessível à sua função ao definir uma variável de ambiente para a mesma.

Dica

O URL da instância do Azure Digital Twins é feito ao adicionar https:// ao início do nome do anfitrião da instância. Para ver o nome do anfitrião, juntamente com todas as propriedades da instância, execute az dt show --dt-name <your-Azure-Digital-Twins-instance>.

O comando seguinte define uma variável de ambiente para o URL da instância que a função utilizará sempre que precisar de aceder à 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>"

Em seguida, adicione variáveis de ambiente nas definições da aplicação de funções que lhe permitem aceder ao hub duplo e ao time series hub.

Utilize o valor primaryConnectionString do hub duplo que guardou anteriormente para criar uma definição de aplicação na sua aplicação de funções que contém a cadeia de ligação do hub duplo:

az functionapp config appsettings set --settings "EventHubAppSetting-Twins=<your-twins-hub-primaryConnectionString>" --resource-group <your-resource-group> --name <your-function-app-name>

Utilize o valor primaryConnectionString do hub de série temporal que guardou anteriormente para criar uma definição de aplicação na sua aplicação de funções que contém a cadeia de ligação do hub de série temporal:

az functionapp config appsettings set --settings "EventHubAppSetting-TSI=<your-time-series-hub-primaryConnectionString>" --resource-group <your-resource-group> --name <your-function-app-name>

Criar e ligar uma instância do Time Series Insights

Nesta secção, irá configurar a instância do Time Series Insights para receber dados do seu time series hub. Para obter mais informações sobre este processo, veja Configurar um ambiente PAYG do Azure Time Series Insights Gen2. Siga os passos abaixo para criar um ambiente do Time Series Insights.

  1. Na portal do Azure, procure ambientes do Time Series Insights e selecione o botão Criar. Escolha as seguintes opções para criar o ambiente de série temporal.

    • Subscrição – selecione a sua subscrição.
      • Grupo de recursos – selecione o grupo de recursos.
    • Nome do ambiente – especifique um nome para o seu ambiente de série temporal.
    • Localização – escolha uma localização.
    • Escalão – selecione o escalão de preço Gen2(L1 ).
    • Nome da propriedade – introduza $dtId (Leia mais sobre como selecionar um valor de ID em Melhores práticas para escolher um ID de Série Temporal).
    • Nome da conta de armazenamento – especifique um nome de conta de armazenamento.
    • Ativar arquivo quente - Deixe este campo definido como Sim.

    Pode deixar valores predefinidos para outras propriedades nesta página. Selecione o botão Seguinte: Origem >do Evento.

    Captura de ecrã do portal do Azure a mostrar como criar um ambiente do Time Series Insights (parte 1/3).

    Captura de ecrã do portal do Azure a mostrar como criar um ambiente do Time Series Insights (parte 2/3).

  2. No separador Origem do Evento , selecione os seguintes campos:

    • Criar uma origem de eventos? - Selecione Sim.
    • Tipo de origem – selecione Hub de Eventos.
    • Nome – especifique um nome para a origem do evento.
    • Subscrição – escolha a sua subscrição do Azure.
    • Espaço de nomes do Hub de Eventos – escolha o espaço de nomes que criou anteriormente neste artigo.
    • Nome do Hub de Eventos – escolha o nome do hub de série temporal que criou anteriormente neste artigo.
    • Nome da política de acesso do Hub de Eventos – escolha a regra de autenticação do hub de séries de tempo que criou anteriormente neste artigo.
    • Grupo de consumidores do Hub de Eventos – selecione Novo e especifique um nome para o grupo de consumidores do hub de eventos. Em seguida, selecione Adicionar.
    • Nome da propriedade – deixe este campo em branco.

    Selecione o botão Rever + Criar para rever todos os detalhes. Em seguida, selecione novamente o botão Rever + Criar para criar o ambiente de série temporal.

    Captura de ecrã do portal do Azure a mostrar como criar um ambiente do Time Series Insights (parte 3/3).

Enviar dados de IoT para o Azure Digital Twins

Para começar a enviar dados para o Time Series Insights, terá de começar a atualizar as propriedades dos duplos digitais no Azure Digital Twins com a alteração dos valores de dados.

Utilize o comando az dt twin update CLI para atualizar uma propriedade no duplo duplo que adicionou na secção Pré-requisitos . Se utilizou as instruções de criação de duplos a partir de Ingerir telemetria de Hub IoT), pode utilizar o seguinte comando na CLI local ou no terminal bash Cloud Shell para atualizar a propriedade de temperatura no termóstato67 duplo. Existe um marcador de posição para o nome de anfitrião da instância do Azure Digital Twins (também pode utilizar o nome amigável da instância com uma ligeira diminuição do desempenho).

az dt twin update --dt-name <your-Azure-Digital-Twins-instance-hostname-or-name> --twin-id thermostat67 --json-patch '{"op":"replace", "path":"/Temperature", "value": 20.5}'

Repita o comando pelo menos mais 4 vezes com valores de propriedade diferentes para criar vários pontos de dados que podem ser observados posteriormente no ambiente do Time Series Insights.

Dica

Se quiser concluir este artigo com dados simulados em direto em vez de atualizar manualmente os valores dos duplos digitais, primeiro certifique-se de que concluiu a SUGESTÃO na secção Pré-requisitos para configurar uma função do Azure que atualiza duplos a partir de um dispositivo simulado. Depois disso, pode executar o dispositivo agora para começar a enviar dados simulados e a atualizar o seu duplo digital através desse fluxo de dados.

Visualizar dados no Time Series Insights

Agora, os dados devem estar a fluir para a sua instância do Time Series Insights, pronto para serem analisados. Siga os passos abaixo para explorar os dados que estão a chegar.

  1. Na portal do Azure, procure o nome do ambiente da série temporal que criou anteriormente. Nas opções de menu à esquerda, selecione Descrição geral para ver o URL do Explorador do Time Series Insights. Selecione o URL para ver as alterações de temperatura refletidas no ambiente do Time Series Insights.

    Captura de ecrã do portal do Azure a mostrar o URL do explorador do Time Series Insights no separador descrição geral do ambiente do Time Series Insights.

  2. No explorador, verá os duplos na instância do Azure Digital Twins apresentada à esquerda. Selecione o duplo para o qual editou as propriedades, escolha a propriedade que alterou e selecione Adicionar.

    Captura de ecrã do explorador do Time Series Insights com os passos para selecionar o termóstato67, selecionar a temperatura da propriedade e selecionar adicionar realçado.

  3. Agora, deverá ver as alterações de propriedade que fez refletidas no gráfico, conforme mostrado abaixo.

    Captura de ecrã do explorador do Time Series Insights com os dados de temperatura inicial, com uma linha de valores aleatórios entre 68 e 85.

Se permitir que uma simulação seja executada durante muito mais tempo, a visualização terá um aspeto semelhante ao seguinte:

Captura de ecrã do explorador do Time Series Insights onde os dados de temperatura de cada duplo duplo são grafados em três linhas paralelas de cores diferentes.

Passos seguintes

Depois de estabelecer um pipeline de dados para enviar dados de série temporal do Azure Digital Twins para o Time Series Insights, talvez queira pensar em como traduzir modelos de recursos concebidos para o Azure Digital Twins em modelos de recursos para o Time Series Insights. Para obter um tutorial sobre este próximo passo no processo de integração, veja Sincronização de modelos entre o Azure Digital Twins e o Time Series Insights Gen2.