Configurar o gerenciamento de eventos de um gêmeo para o outro

  • Artigo

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

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

Pré-requisitos

Para configurar a manipulação de um gêmeo para o outro, você precisará de uma instância Gêmeos Digitais do Azure para trabalhar. Para obter instruções sobre como criar um instância, consulte Configurar uma autenticação e instância de Gêmeos Digitais do Azure. A instância deve conter pelo menos dois gêmeos entre os que você deseja enviar dados.

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

Enviar eventos gêmeos para um ponto de extremidade

Para configurar o tratamento de eventos de um gêmeo para o outro, comece criando um ponto de extremidade no 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 (em que a Grade de Eventos pode pegá-los mais tarde e passá-los para uma função do Azure para processamento).

Criar o tópico da Grade de Eventos

A Grade de Eventos é um serviço do Azure que ajuda você a encaminhar e entregar eventos dos serviços do Azure para outros locais no Azure. Você pode criar um tópico da Grade de Eventos para coletar determinados eventos de uma fonte e, então, os assinantes podem escutar o tópico para receber os eventos à medida que eles chegam.

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

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

A saída desse comando são informações sobre o tópico da Grade de Eventos que você criou. Salve o nome que você deu ao tópico da Grade de Eventos, para usá-lo mais tarde.

Criar o ponto de extremidade

Em seguida, crie um ponto de extremidade da Grade de Eventos nos Gêmeos Digitais do Azure, que conectará sua instância ao tópico da 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 o 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 desse comando são informações sobre o ponto de extremidade que você criou.

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

Screenshot of the result of the endpoint query in the Cloud Shell of the Azure portal, showing the endpoint with a provisioningState of Succeeded.

Ele também pode indicar "provisionamento", o que significa que o ponto de extremidade ainda está sendo criado. Se for, aguarde alguns segundos e execute o comando a seguir para verificar o status do ponto de extremidade. Repita-o até que provisioningState mostre "Êxito".

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

Salve o nome do ponto de extremidade, para usá-lo mais tarde.

Criar a rota

Em seguida, crie uma rota dos Gêmeos Digitais do Azure que envia eventos para o ponto de extremidade criado da Grade de Eventos.

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

Dica

Você pode limitar os eventos apenas a alguns específicos se quiser 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 desse comando são algumas informações sobre a rota que você criou.

Observação

Os pontos de extremidade (da etapa anterior) devem ter o provisionamento concluído para configurar uma rota de eventos que os utilize. 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 enviados 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.

  1. Primeiro, criar um projeto do Azure Functions.

    Você pode fazer isso usando o Visual Studio (para obter instruções, confira Desenvolver Azure Functions usando o Visual Studio), Visual Studio Code (para obter instruções, confira Criar uma função C# no Azure usando o Visual Studio Code), ou a CLI do Azure (para obter instruções, confira Criar uma função C# no Azure por meio da linha de comando).

  2. Adicione os pacotes a seguir ao seu projeto (você pode usar gerenciador de pacotes NuGet do Visual Studio ou o comando dotnet add package em uma ferramenta de linha de comando).

  3. Preencha a lógica de 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.

  4. Publique a função no Azure usando seu método preferencial.

    Para obter instruções sobre como publicar uma função usando o Visual Studio, confira Desenvolver Azure Functions com o Visual Studio. Para obter instruções sobre como publicar a função usando o Visual Studio Code, confira 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, confira Criar uma função C# no Azure da linha de comando.

Depois que 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 o grupo de recursos, o nome do aplicativo de funções e o nome da função específica. O comando imprimirá informações sobre sua função.

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

Configurar o aplicativo de funções

Antes que sua função possa acessar o 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ê irá atribuir uma função de acesso para a função e definir as configurações do aplicativo para que ele possa encontrar e acessar a instância.

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

Observação

Esta seção precisa 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 concessão e delegação de permissões. Funções comuns que atendem a esse requisito são Proprietário, Administrador da conta ou a combinação de Colaborador e Administrador de Acesso do Usuário. Para obter mais informações sobre os requisitos de permissão para funções dos Gêmeos Digitais do Azure, confira Configurar uma instância e a autenticação.

Atribuir uma função de acesso

A função do Azure exige o recebimento de um token de portador. Para garantir que o token de portador seja recebido, conceda ao aplicativo de funções a função Proprietário de Dados dos Gêmeos Digitais do Azure à instância dos Gêmeos Digitais do Azure, que dará ao aplicativo de funções a permissão para executar atividades do plano de dados na instância.

  1. 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á os respectivos detalhes). Anote o principalId campo na saída. Você usará essa ID para se referir à função a fim de conceder a ela as permissões na próxima etapa.

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

  2. Use o valor de principalId no comando a seguir para atribuir a função Proprietário de Dados dos Gêmeos Digitais do Azure à instância dos 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"

Definir as configurações do aplicativo

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

Dica

A URL da instância dos Gêmeos Digitais do Azure é criada adicionando https:// ao início do nome do host da instância do Azure. Para ver o nome do host, juntamente com todas as propriedades da 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 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>"

Conexão a função para o ponto de extremidade

Em seguida, assine sua função do Azure ao tópico da grade de eventos que você criou anteriormente. Ao fazer isso, garantirá que os dados possam fluir de um gêmeo atualizado por meio do tópico Grade de Eventos para a função, que pode usar as informações de evento para atualizar outros gêmeos conforme necessário.

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

Use o seguinte comando da CLI, preenchendo os espaço reservados para sua ID de assinatura, grupo de recursos, aplicativo de funções 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, sua função pode receber eventos por meio do tópico da Grade de Eventos. A configuração do fluxo de dados foi concluída.

Testar e verificar os 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 começar o processo, atualize o gêmeo que é a origem do fluxo de eventos. Você pode usar a CLI do Azure, a SDK do Gêmeos Digitais do Azure ou as APIs REST do Gêmeos Digitais do Azure para fazer a atualização.

Em seguida, consulte o Gêmeos Digitais do Azure para o gêmeo relacionado. Você pode usar a CLI do Azure ou as APIs REST e o SDK do Gêmeos Digitais do Azure. Verifique se o gêmeo recebeu os dados e atualizou conforme esperado.

Próximas etapas

Neste artigo, você configura o tratamento de eventos de um gêmeo para o outro no Gêmeos Digitais do Azure. 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.