Configurar a manipulação de eventos de dois para dois

Artigo
01/04/2024

Este artigo mostra como enviar eventos de gêmeo para gêmeo, de modo que, quando um gêmeo digital no gráfico é atualizado, gêmeos relacionados no gráfico que são afetados por essas informações também podem ser atualizados. Essa manipulação de eventos ajudará você a criar um gráfico de Gêmeos Digitais do Azure totalmente conectado, onde os dados que chegam aos Gêmeos Digitais do Azure de fontes externas, como o Hub IoT, são propagados por todo o gráfico.

Para configurar essa manipulação de eventos de gêmeo para gêmeo, você criará uma função do Azure que observa eventos de ciclo de vida gêmeos. A função reconhece quais eventos devem afetar outros gêmeos no gráfico e usa os dados do evento para atualizar os gêmeos afetados de acordo.

Pré-requisitos

Para configurar o tratamento de gêmeos para gêmeos, você precisará de uma instância do Azure Digital Twins para trabalhar. Para obter instruções sobre como criar uma instância, consulte Configurar uma instância e autenticação do Azure Digital Twins. A instância deve conter pelo menos dois gêmeos entre os quais você deseja enviar dados.

Opcionalmente, você pode configurar a ingestão automática de telemetria por meio do Hub IoT também para seus gêmeos. Este processo não é necessário para enviar dados de gêmeo para gêmeo, mas é uma peça importante de uma solução completa onde o gráfico gêmeo é acionado por telemetria de dispositivo ao vivo.

Enviar eventos gêmeos para um ponto de extremidade

Para configurar a manipulação de eventos de gêmeo para gêmeo, comece criando um ponto de extremidade nos Gêmeos Digitais do Azure e uma rota para esse ponto de extremidade. Os gêmeos que passam por uma atualização usarão a rota para enviar informações sobre seus eventos de atualização para o ponto de extremidade (onde a Grade de Eventos pode pegá-los mais tarde e passá-los para uma função do Azure para processamento).

Criar o tópico Grade de Eventos

A Grade de Eventos é um serviço do Azure que ajuda a rotear e entregar eventos dos serviços do Azure para outros locais no Azure. Você pode criar um tópico de Grade de Eventos para coletar determinados eventos de uma fonte e, em seguida, os assinantes podem ouvir o tópico para receber os eventos à medida que eles aparecem.

Na CLI do Azure, execute o seguinte comando para criar um tópico de Grade de Eventos:

az eventgrid topic create --resource-group <your-resource-group> --name <name-for-your-event-grid-topic> --location <region>

A saída deste comando é informações sobre o tópico Grade de Eventos que você criou. Salve o nome que você deu ao seu tópico Grade de Eventos, porque você o usará mais tarde.

Criar o ponto de extremidade

Em seguida, crie um ponto de extremidade de Grade de Eventos no Azure Digital Twins, que conectará sua instância ao tópico Grade de Eventos. Use o comando abaixo, preenchendo o nome do tópico da Grade de Eventos da etapa anterior e os outros campos de espaço reservado, conforme necessário.

az dt endpoint create eventgrid --dt-name <Azure-Digital-Twins-instance> --eventgrid-resource-group <your-resource-group> --eventgrid-topic <your-event-grid-topic> --endpoint-name <name-for-your-Azure-Digital-Twins-endpoint>

A saída deste comando é informações sobre o ponto de extremidade que você criou.

Procure o provisioningState campo na saída e verifique se o valor é "Êxito".

Ele também pode dizer "Provisionamento", o que significa que o ponto de extremidade ainda está sendo criado. Em caso afirmativo, aguarde alguns segundos e execute o seguinte comando para verificar o status do ponto de extremidade. Repita até que os provisioningState shows "Succeeded".

az dt endpoint show --dt-name <your-Azure-Digital-Twins-instance> --endpoint-name <your-Azure-Digital-Twins-endpoint>

Salve o nome do seu ponto de extremidade, porque você o usará mais tarde.

Criar a rota

Em seguida, crie uma rota de Gêmeos Digitais do Azure que envie eventos para o ponto de extremidade da Grade de Eventos que você criou.

Use o seguinte comando da CLI, preenchendo o nome do seu ponto de extremidade da etapa anterior e os outros campos de espaço reservado conforme necessário. Este comando encaminha todos os eventos que ocorrem no gráfico gêmeo.

Gorjeta

Você pode limitar os eventos a apenas eventos específicos, se desejar, usando filtros.

az dt route create --dt-name <your-Azure-Digital-Twins-instance> --endpoint-name <your-Azure-Digital-Twins-endpoint> --route-name <name-for-your-Azure-Digital-Twins-route>

A saída deste comando é algumas informações sobre a rota que você criou.

Nota

Os pontos de extremidade (da etapa anterior) devem ser concluídos antes que você possa configurar uma rota de evento que os use. Se a criação da rota falhar porque os pontos de extremidade não estão prontos, aguarde alguns minutos e tente novamente.

Criar função do Azure para atualizar gêmeos

Em seguida, crie uma função do Azure que escutará no ponto de extremidade e receberá eventos gêmeos que são enviados para lá por meio da rota. A lógica da função deve usar as informações nos eventos para determinar quais outros gêmeos precisam ser atualizados e, em seguida, executar as atualizações.

Primeiro, crie um novo projeto do Azure Functions.

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).
Preencha a lógica da sua função. Você pode exibir o código de função de exemplo para vários cenários no repositório azure-digital-twins-getting-started para ajudá-lo a começar.
Publique a função no Azure, usando seu método preferido.

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. Existem espaços reservados para o seu grupo de recursos, o nome da sua aplicação de função e o nome da sua função específica. O comando imprimirá informações sobre a sua função.

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

Configurar a aplicação de funções

Antes que sua função possa acessar os Gêmeos Digitais do Azure, ela precisa de algumas informações sobre a instância e a permissão para acessá-la. Nesta seção, você atribuirá uma função de acesso para a função e definirá as configurações do aplicativo para que ele possa localizar e acessar a instância.

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>"

Conecte a função ao ponto de extremidade

Em seguida, inscreva sua função do Azure no ponto de extremidade da Grade de Eventos criado anteriormente. Isso garantirá que os dados possam fluir de um gêmeo atualizado através do tópico Grade de Eventos para a função, que pode usar as informações do evento para atualizar outros gêmeos conforme necessário.

Para inscrever sua função do Azure, você criará uma assinatura de Grade de Eventos que envia dados do tópico Grade de Eventos que você criou anteriormente para sua função do Azure.

Use o seguinte comando da CLI, preenchendo espaços reservados para sua ID de assinatura, grupo de recursos, aplicativo de função e nome da função.

az eventgrid event-subscription create --name <name-for-your-event-subscription> --source-resource-id /subscriptions/<subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.EventGrid/topics/<your-event-grid-topic> --endpoint-type azurefunction --endpoint /subscriptions/<subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.Web/sites/<your-function-app-name>/functions/<function-name>

Agora, a sua função pode receber eventos através do tópico Grelha de Eventos. A configuração do fluxo de dados está concluída.

Testar e verificar resultados

A última etapa é verificar se o fluxo está funcionando, atualizando um gêmeo e verificando se os gêmeos relacionados são atualizados de acordo com a lógica em sua função do Azure.

Para iniciar o processo, atualize o gêmeo que é a fonte do fluxo de eventos. Você pode usar a CLI do Azure, o SDK do Azure Digital Twins ou as APIs REST do Azure Digital Twins para fazer a atualização.

Em seguida, consulte sua instância do Azure Digital Twins para o gêmeo relacionado. Você pode usar a CLI do Azure ou as APIs REST e o SDK do Azure Digital Twins. Verifique se o gêmeo recebeu os dados e atualizou conforme o esperado.

Próximos passos

Neste artigo, você configura a manipulação de eventos de gêmeo para gêmeo no Azure Digital Twins. Em seguida, configure uma função do Azure para disparar esse fluxo automaticamente com base na telemetria de entrada de dispositivos do Hub IoT: Ingerir telemetria do Hub IoT.