Criar uma conexão de histórico de dados para Gêmeos Digitais do Azure

O histórico de dados é um recurso do Azure Digital Twins para historiar automaticamente atualizações de gráficos no Azure Data Explorer. Esses dados podem ser consultados usando o plug-in de consulta do Azure Digital Twins para o Azure Data Explorer para obter informações sobre seu ambiente ao longo do tempo.

Este artigo mostra como configurar uma conexão de histórico de dados de trabalho entre os Gêmeos Digitais do Azure e o Azure Data Explorer. Ele usa a CLI do Azure e o portal do Azure para configurar e conectar os recursos de histórico de dados necessários, incluindo:

• uma instância do Azure Digital Twins
• um namespace de Hubs de Eventos contendo um hub de eventos
• um cluster do Azure Data Explorer contendo um banco de dados

Ele também contém um gráfico gêmeo de exemplo que você pode usar para ver as atualizações de gráfico histórico no Azure Data Explorer.

Pré-requisitos

Prepare o seu ambiente para o CLI do Azure

• Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.

  

• Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

  • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

  • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

  • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

Configurar sessão CLI

Para começar a trabalhar com os Gêmeos Digitais do Azure na CLI, a primeira coisa a fazer é fazer logon e definir o contexto da CLI para sua assinatura para esta sessão. Execute estes comandos na janela da CLI:

az login
az account set --subscription "<your-Azure-subscription-ID>"

Se esta for a primeira vez que você usa essa assinatura com os Gêmeos Digitais do Azure, execute este comando para se registrar com o namespace Gêmeos Digitais do Azure. (Se você não tiver certeza, não há problema em executá-lo novamente, mesmo que você já tenha feito isso em algum momento no passado.)

az provider register --namespace 'Microsoft.DigitalTwins'

Em seguida, você adicionará a Extensão IoT do Microsoft Azure para CLI do Azure para habilitar comandos para interagir com Gêmeos Digitais do Azure e outros serviços de IoT. Execute este comando para se certificar de que tem a versão mais recente da extensão:

az extension add --upgrade --name azure-iot

Agora você está pronto para trabalhar com os Gêmeos Digitais do Azure na CLI do Azure.

Você pode verificar isso executando az dt --help a qualquer momento para ver uma lista dos comandos de nível superior do Azure Digital Twins que estão disponíveis.

Configurar variáveis locais para a sessão da CLI

Este artigo fornece comandos da CLI que você pode usar para criar os recursos do histórico de dados. Para facilitar a cópia e a execução desses comandos mais tarde, você pode configurar variáveis locais em sua sessão da CLI agora e, em seguida, consultar essas variáveis posteriormente nos comandos da CLI ao criar seus recursos. Atualize os espaços reservados (identificados com <...> colchetes) nos comandos abaixo e execute esses comandos para criar as variáveis. Certifique-se de seguir as regras de nomenclatura descritas nos comentários. Esses valores serão usados posteriormente ao criar os novos recursos.

## General Setup
location="<your-resource-region>"
resourcegroup="<your-resource-group-name>"

## Azure Digital Twins Setup
# Instance name can contain letters, numbers, and hyphens. It must start and end with a letter or number, and be between 4 and 62 characters long.
dtname="<name-for-your-digital-twins-instance>"
# Connection name can contain letters, numbers, and hyphens. It must contain at least one letter, and be between 3 and 50 characters long.
connectionname="<name-for-your-data-history-connection>"

## Event Hub Setup
# Namespace can contain letters, numbers, and hyphens. It must start with a letter, end with a letter or number, and be between 6 and 50 characters long.
eventhubnamespace="<name-for-your-event-hub-namespace>"
# Event hub name can contain only letters, numbers, periods, hyphens and underscores. It must start and end with a letter or number.
eventhub="<name-for-your-event-hub>"

## Azure Data Explorer Setup
# Cluster name can contain only lowercase alphanumeric characters. It must start with a letter, and be between 4 and 22 characters long.
clustername="<name-for-your-cluster>"  
# Database name can contain only alphanumeric, spaces, dash and dot characters, and be up to 260 characters in length.
databasename="<name-for-your-database>"

# Enter a name for the table where relationship create and delete events will be stored.
relationshiplifecycletablename="<name-for-your-relationship-lifecycle-events-table>"
# Enter a name for the table where twin create and delete events will be stored.
twinlifecycletablename="<name-for-your-twin-lifecycle-events-table>"
# Optionally, enter a custom name for the table where twin property updates will be stored. If not provided, the table will be named AdtPropertyEvents.
twinpropertytablename="<name-for-your-twin-property-events-table>"

Criar uma instância do Azure Digital Twins com uma identidade gerenciada

Se você já tiver uma instância do Azure Digital Twins, certifique-se de ter habilitado uma identidade gerenciada atribuída ao sistema para ela.

Se você não tiver uma instância do Azure Digital Twins, siga as instruções em Criar a instância com uma identidade gerenciada para criar uma instância do Azure Digital Twins com uma identidade gerenciada atribuída pelo sistema pela primeira vez.

Em seguida, verifique se você tem a função de Proprietário de Dados do Azure Digital Twins na instância. Você pode encontrar instruções em Configurar permissões de acesso do usuário.

Se você quiser adicionar o nome da sua instância às variáveis da CLI local para que ela seja automaticamente conectada a comandos posteriores copiados deste artigo, armazene-a na variável dtname da seguinte forma:

dtname="<name-of-your-instance>"

Criar um namespace e um hub de eventos de Hubs de Eventos

A próxima etapa é criar um namespace de Hubs de Eventos e um hub de eventos. Esse hub receberá notificações de atualização do ciclo de vida do gráfico e da propriedade da instância do Azure Digital Twins e, em seguida, encaminhará as mensagens para o cluster de destino do Azure Data Explorer.

Como parte da configuração de conexão do histórico de dados posteriormente, você concederá à instância do Azure Digital Twins a função de Proprietário de Dados dos Hubs de Eventos do Azure no recurso do hub de eventos.

Para obter mais informações sobre Hubs de Eventos e seus recursos, consulte a documentação de Hubs de Eventos.

az eventhubs namespace create --name $eventhubnamespace --resource-group $resourcegroup --location $location

az eventhubs eventhub create --name $eventhub --resource-group $resourcegroup --namespace-name $eventhubnamespace

Criar um cluster e um banco de dados Kusto (Azure Data Explorer)

Em seguida, crie um cluster e um banco de dados Kusto (Azure Data Explorer) para receber os dados dos Gêmeos Digitais do Azure.

Como parte da configuração da conexão do histórico de dados posteriormente, você concederá à instância dos Gêmeos Digitais do Azure a função de Colaborador pelo menos no banco de dados (ela também pode ter escopo para o cluster) e a função de Administrador no banco de dados.

az extension add --name kusto

az kusto cluster create --cluster-name $clustername --sku name="Dev(No SLA)_Standard_E2a_v4" tier="Basic" --resource-group $resourcegroup --location $location --type SystemAssigned

az kusto database create --cluster-name $clustername --database-name $databasename --resource-group $resourcegroup --read-write-database soft-delete-period=P365D hot-cache-period=P31D location=$location

Configurar a conexão do histórico de dados

Agora que você criou os recursos necessários, use o comando nesta seção para criar uma conexão de histórico de dados entre a instância do Azure Digital Twins, o hub de eventos e o cluster do Azure Data Explorer.

Esse comando também criará três tabelas em seu banco de dados do Azure Data Explorer para armazenar atualizações de propriedade gêmeas, eventos de ciclo de vida gêmeos e eventos de ciclo de vida de relacionamento, respectivamente. Para obter mais informações sobre esses tipos de dados históricos e suas tabelas correspondentes do Azure Data Explorer, consulte Tipos de dados e esquemas.

az dt data-history connection create adx --dt-name $dtname --cn $connectionname --adx-cluster-name $clustername --adx-database-name $databasename --eventhub $eventhub --eventhub-namespace $eventhubnamespace --adx-property-events-table $twinpropertytablename --adx-twin-events-table $twinlifecycletablename --adx-relationship-events-table $relationshiplifecycletablename --adx-record-removals true

Depois de configurar a conexão do histórico de dados, você pode, opcionalmente, remover as funções concedidas à sua instância do Azure Digital Twins para acessar os Hubs de Eventos e os recursos do Azure Data Explorer. Para usar o histórico de dados, a única função que a instância precisa daqui para frente é o Remetente de Dados dos Hubs de Eventos do Azure (ou uma função superior que inclua essas permissões, como Proprietário de Dados dos Hubs de Eventos do Azure) no recurso Hubs de Eventos.

Restringir o acesso à rede aos recursos do histórico de dados

Se quiser restringir o acesso à rede aos recursos envolvidos no histórico de dados (sua instância do Azure Digital Twins, hub de eventos ou cluster do Azure Data Explorer), defina essas restrições depois de configurar a conexão do histórico de dados. Isso inclui desabilitar o acesso local para seus recursos, entre outras medidas para reduzir o acesso à rede.

Para garantir que seus recursos de histórico de dados possam se comunicar entre si, você também deve modificar a conexão de dados para o banco de dados do Azure Data Explorer para usar uma identidade gerenciada atribuída ao sistema.

Siga a ordem das etapas abaixo para garantir que sua conexão de histórico de dados esteja configurada corretamente quando seus recursos precisarem de acesso reduzido à rede.

1. Verifique se a autorização local está habilitada em seus recursos de histórico de dados (sua instância do Azure Digital Twins, hub de eventos e cluster do Azure Data Explorer)
2. Criar a conexão do histórico de dados
3. Atualize a conexão de dados para o banco de dados do Azure Data Explorer para usar uma identidade gerenciada atribuída ao sistema. No portal do Azure, você pode fazer isso navegando até o cluster do Azure Data Explorer e usando Bancos de Dados no menu para navegar até o banco de dados de histórico de dados. No menu do banco de dados, selecione Conexões de dados. Na entrada de tabela para sua conexão de histórico de dados, você verá a opção Atribuir identidade gerenciada, onde você pode escolher Atribuído ao sistema.
4. Agora, você pode desabilitar a autorização local ou definir outras restrições de rede para os recursos desejados, alterando as configurações de acesso em sua instância do Azure Digital Twins, hub de eventos ou cluster do Azure Data Explorer.

Solucionar problemas de configuração de conexão

Aqui estão alguns erros comuns que você pode encontrar ao configurar uma conexão de histórico de dados e como resolvê-los.

• Se você tiver o acesso à rede pública desabilitado para seu cluster do Azure Data Explorer, encontrará um erro informando que o serviço falhou ao criar a conexão do histórico de dados, com a mensagem "O recurso não pôde o ACT devido a um erro interno do servidor". A configuração do histórico de dados falhará se o cluster do Azure Data Explorer tiver o acesso à rede pública desabilitado, já que os Gêmeos Digitais do Azure não poderão configurar as tabelas e outros artefatos necessários.
• (usuários CLI) Se você encontrar o erro "Não foi possível criar a conexão de instância do Azure Digital Twins. Não é possível criar uma regra de tabela e mapeamento na base de dados. Verifique suas permissões para o Gerenciador de Banco de Dados do Azure e execute az login para atualizar suas credenciais", resolva o erro adicionando-se como AllDatabasesAdmin em Permissões em seu cluster do Azure Data Explorer.
• (Usuários do Cloud Shell) Se você estiver usando o Cloud Shell e encontrar o erro "Falha ao se conectar ao MSI. Certifique-se de que o MSI está configurado corretamente", tente executar o comando com uma instalação local da CLI do Azure.

Verificar com um gráfico gêmeo de amostra

Agora que sua conexão de histórico de dados está configurada, você pode testá-la com dados de seus gêmeos digitais.

Se você já tiver gêmeos em sua instância do Azure Digital Twins que estão recebendo ativamente atualizações de gráfico (incluindo atualizações de propriedade gêmea ou atualizações de alterar a estrutura do gráfico criando ou excluindo elementos), você pode ignorar esta seção e visualizar os resultados usando seus próprios recursos.

Caso contrário, continue nesta seção para configurar um gráfico de exemplo que passará por eventos de ciclo de vida de gêmeos e relacionamentos e gerará atualizações de propriedades gêmeas.

Você pode configurar um gráfico de exemplo para esse cenário usando o Simulador de Dados de Gêmeos Digitais do Azure. O Simulador de Dados de Gêmeos Digitais do Azure cria gêmeos e relacionamentos em sua instância de Gêmeos Digitais do Azure e envia continuamente atualizações de propriedade para os gêmeos.

Criar um gráfico de exemplo

Você pode usar o Simulador de Dados de Gêmeos Digitais do Azure para provisionar um gráfico gêmeo de exemplo e enviar atualizações de propriedade por push para ele. O gráfico gêmeo criado aqui modela os processos de pasteurização para uma empresa de laticínios.

Comece abrindo o Azure Digital Twins Data Simulator em seu navegador. Defina estes campos:

• URL da instância: insira o nome do host da sua instância do Azure Digital Twins. O nome do host pode ser encontrado na página do portal da sua instância e tem um formato como <Azure-Digital-Twins-instance-name>.api.<region-code>.digitaltwins.azure.net.
• Tipo de simulação: Selecione Dairy facility no menu suspenso.

Selecione Gerar ambiente.

Você verá mensagens de confirmação na tela à medida que modelos, gêmeos e relacionamentos são criados em seu ambiente. Isso também gerará eventos de criação de gêmeos e relacionamentos, que serão históricos para o Azure Data Explorer como eventos de ciclo de vida de gêmeos e relacionamentos, respectivamente.

Quando a simulação estiver pronta, o botão Iniciar simulação será ativado. Role para baixo e selecione Iniciar simulação para enviar dados simulados por push para sua instância do Azure Digital Twins. Para atualizar continuamente os gêmeos em sua instância do Azure Digital Twins, mantenha essa janela do navegador em primeiro plano na área de trabalho e conclua outras ações do navegador em uma janela separada. Isso gerará continuamente eventos de atualizações de propriedade gêmea que serão históricos no Azure Data Explorer.

Exibir as atualizações históricas no Azure Data Explorer

Esta seção mostrará como exibir todos os três tipos de atualizações historizadas que foram geradas pelo simulador e armazenadas em tabelas do Azure Data Explorer.

Inicie no portal do Azure e navegue até o cluster do Azure Data Explorer criado anteriormente. Escolha o painel Bancos de dados no menu à esquerda para abrir a exibição do banco de dados . Localize o banco de dados que você criou para este artigo e marque a caixa de seleção ao lado dele e, em seguida, selecione Consulta.

Em seguida, expanda o cluster e o banco de dados no painel esquerdo para ver o nome das tabelas de histórico de dados. Deve haver três: um para eventos de ciclo de vida de relacionamento, um para eventos de ciclo de vida gêmeos e um para eventos de atualização de propriedade gêmea. Você usará esses nomes de tabela para executar consultas nas tabelas para verificar e exibir os dados históricos.

Verificar entradas de tabela

Para verificar se os eventos estão sendo históricos no banco de dados, comece copiando o comando a seguir. Ele tem um espaço reservado para o nome da tabela de eventos do ciclo de vida do relacionamento e alterará a ingestão da tabela para o modo em lote, de modo a ingerir dados da simulação ao vivo a cada 10 segundos.

.alter table <relationship-lifecycle-events-table-name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'

Cole o comando na janela de consulta, substituindo o espaço reservado pelo nome da tabela de eventos de relacionamento. Selecione o botão Executar para executar o comando.

Repita o comando mais duas vezes usando o nome da tabela de eventos do ciclo de vida gêmeo e, em seguida, a tabela de atualização de propriedade para atualizar o modo de ingestão das outras tabelas também.

Em seguida, adicione os seguintes comandos à janela de consulta e execute-os. Cada comando contém um espaço reservado para o nome de uma das tabelas, e os comandos produzirão o número de itens nas tabelas.

<relationship-lifecycle-events-table-name>
| count

<twin-lifecycle-events-table-name>
| count

<twin-property-updates-table-name>
| count

Você deve ver nos resultados que a contagem de itens em cada tabela é algo maior que 0, indicando que os eventos de ciclo de vida de relacionamento, ciclo de vida gêmeo e atualização de propriedade estão sendo históricos em suas respetivas tabelas.

Explore a tabela de atualizações de propriedades gêmeas

Nesta seção, você fará mais algumas explorações com os dados de atualização de propriedade gêmea que estão na tabela.

Primeiro, execute o seguinte comando para exibir 100 registros na tabela:

<twin-property-updates-table-name>
| limit 100

Em seguida, execute uma consulta com base nos dados de seus gêmeos para ver os dados contextualizados da série temporal.

Use a consulta abaixo para mapear o fluxo de saída de todos os gêmeos da máquina de sal na fábrica de laticínios de Oslo de amostra. Esta consulta Kusto usa o plug-in Gêmeos Digitais do Azure para selecionar os gêmeos de interesse, une esses gêmeos à série temporal do histórico de dados no Azure Data Explorer e traça os resultados. Certifique-se de substituir o espaço reservado pelo nome do host da instância e o espaço reservado <ADT-instance-host-name> <table-name> pelo nome da tabela de eventos de propriedade gêmea.

let ADTendpoint = "https://<ADT-instance-host-name>";
let ADTquery = ```SELECT SALT_MACHINE.$dtId as tid
FROM DIGITALTWINS FACTORY 
JOIN SALT_MACHINE RELATED FACTORY.contains 
WHERE FACTORY.$dtId = 'OsloFactory'
AND IS_OF_MODEL(SALT_MACHINE , 'dtmi:assetGen:SaltMachine;1')```;
evaluate azure_digital_twins_query_request(ADTendpoint, ADTquery)
| extend Id = tostring(tid)
| join kind=inner (<table-name>) on Id
| extend val_double = todouble(Value)
| where Key == "OutFlow"
| render timechart with (ycolumns = val_double)

Os resultados devem mostrar os números de saída mudando ao longo do tempo.

Resolver ligação

Se você não vir dados no Azure Data Explorer, o fluxo de dados de historização não está funcionando corretamente. Você pode investigar o problema exibindo seu namespace de Hubs de Eventos no portal do Azure, que exibe gráficos mostrando o fluxo de mensagens para dentro e para fora do namespace. Isso permitirá que você verifique o fluxo de mensagens de entrada dos Gêmeos Digitais do Azure e as mensagens de saída para o Azure Data Explorer, para ajudá-lo a identificar qual parte do fluxo não está funcionando.

Próximos passos

Para continuar explorando o cenário de laticínios, você pode visualizar mais consultas de exemplo no GitHub que mostram como você pode monitorar o desempenho da operação de laticínios com base no tipo de máquina, fábrica, técnico de manutenção e várias combinações desses parâmetros.

Para criar painéis do Grafana que visualizam o desempenho da operação de laticínios, leia Criando painéis com o Azure Digital Twins, o Azure Data Explorer e o Grafana.

Para obter mais informações sobre como usar o plug-in de consulta do Azure Digital Twins para o Azure Data Explorer, consulte Consultando com o plug-in do Azure Data Explorer e esta postagem de blog. Você também pode ler mais sobre o plug-in aqui: Consultando com o plug-in do Azure Data Explorer.