Criar pontos de extremidade nos Gêmeos Digitais do Azure
Este artigo explica como criar um ponto de extremidade para eventos do Gêmeo Digital do Azure usando o portal do Azure ou a CLI do Azure. Você também pode gerenciar pontos de extremidade com as APIs do plano de controle DigitalTwinsEndpoint.
Encaminhar as notificações de eventos dos Gêmeos Digitais do Azure para serviços downstream ou recursos de computação conectados é um processo de duas etapas: criar pontos de extremidade e, em seguida, criar rotas de evento para enviar dados para esses pontos de extremidade. Este artigo aborda a primeira etapa, configurando pontos de extremidade que podem receber os eventos. Depois, você pode criar rotas de evento que especificam quais eventos gerados pelos Gêmeos Digitais do Azure são entregues a quais pontos de extremidade.
Pré-requisitos
Você precisará ter uma conta do Azure, que pode ser configurada gratuitamente
Você precisará de uma instância dos Gêmeos Digitais do Azure na assinatura do Azure. Se você ainda não tiver uma instância, crie uma seguindo as etapas em Configurar uma instância e uma autenticação. Faça com que os seguintes valores da configuração sejam úteis para uso posterior neste artigo:
- Nome da instância
- Grupo de recursos
Você pode encontrar esses detalhes no portal do Azure depois de configurar a sua instância.
Então, siga as instruções abaixo se você deseja usar a CLI do Azure com este guia.
Preparar o ambiente para a CLI do Azure
Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.
Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.
Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.
Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.
Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.
Criar recursos necessários
Estes serviços são os tipos compatíveis de pontos de extremidade que você pode criar para sua instância:
- Tópico da Grade de Eventos
- Para pontos de extremidade da Grade de Eventos, há suporte apenas para tópicos da grade de eventos. Não há suporte para os domínios de Grade de Eventos como pontos de extremidade.
- Hub do Hubs de Eventos
- Tópico do Barramento de Serviço
Para vincular um ponto de extremidade aos Gêmeos Digitais do Azure, o tópico da Grade de Eventos, o Hub de Eventos ou o tópico do Barramento de Serviço que você está usando para o ponto de extremidade precisa já existir.
Use o gráfico a seguir para ver quais recursos devem ser configurados antes de criar seu ponto de extremidade.
| Tipo de ponto de extremidade | Recursos necessários (vinculados às instruções de criação) |
|---|---|
| Ponto de extremidade da Grade de Eventos | Grade de Eventos *O esquema de evento deve ser o Esquema da Grade de Eventos ou o Esquema de Eventos na Nuvem v1.0 |
| Ponto de extremidade do Hubs de Eventos | Namespace do Hubs de Eventos hub de evento (Adicional) regra de autorização para autenticação baseada em chave |
| Ponto de extremidade do Barramento de Serviço | Namespace do Barramento de Serviço Tópico do Barramento de Serviço (Adicional) regra de autorização para autenticação baseada em chave |
Criar o ponto de extremidade
Depois de criar os recursos do ponto de extremidade, você poderá usá-los para um ponto de extremidade dos Gêmeos Digitais do Azure.
Para criar um ponto de extremidade, acesse a página da sua instância no portal do Azure (você pode encontrar a instância inserindo o nome dela na barra de pesquisa do portal).
No menu da instância, escolha Pontos de extremidade. Então, na próxima página Pontos de extremidade, escolha + Criar um ponto de extremidade. Ao fazer isso, abrirá a página Criar um ponto de extremidade, onde você preencherá os campos nas etapas a seguir.
Insira um nome para o ponto de extremidade e escolha o Tipo de ponto de extremidade.
Preencha os outros detalhes necessários para o tipo de ponto de extremidade, incluindo a sua assinatura e os recursos de ponto de extremidade descritos anteriormente.
- Somente para os pontos de extremidade do Hubs de Eventos e Barramento de Serviço, você deve escolher um Tipo de autenticação. Use a autenticação baseada em chave com uma regra de autorização pré-criada ou uma identidade gerenciada atribuída pelo sistema ou atribuída pelo usuário. Para obter mais informações sobre como usar as opções de autenticação de identidade, confira Opções de ponto de extremidade: autenticação baseada em identidade.
Conclua a criação do ponto de extremidade escolhendo a opção Salvar.
Depois de criar o ponto de extremidade, você pode verificar se ele foi criado com sucesso conferindo o ícone de notificação na barra superior do portal do Azure:
Se houver falha na criação do ponto de extremidade, observe a mensagem de erro e tente novamente depois de alguns minutos.
Você também pode exibir o ponto de extremidade que foi criado na página Pontos de extremidade da sua instância dos Gêmeos Digitais do Azure.
Agora, o tópico de Barramento de Serviço, Grade de Eventos ou hub de eventos está disponível como um ponto de extremidade nos Gêmeos Digitais do Azure, com o nome que você escolheu para o ponto de extremidade. Normalmente, você usará esse nome como destino de uma rota de evento, que pode ser criada em Criar rotas e filtros.
Opções de ponto de extremidade: autenticação baseada em identidade
Esta seção descreve como usar uma identidade gerenciada para uma instância dos Gêmeos Digitais do Azure ao encaminhar eventos para destinos de roteamento com suporte. A configuração de uma identidade gerenciada não é necessária para o roteamento, mas pode ajudar a instância a acessar facilmente outros recursos protegidos pelo Microsoft Entra, como os Hubs de Eventos, destinos do Barramento de Serviço e o Contêiner de Armazenamento do Azure. As identidades gerenciadas podem ser atribuídas pelo sistema ou pelo usuário.
O restante desta seção explica três etapas para configurar um ponto de extremidade com uma identidade gerenciada.
1. Habilitar uma identidade gerenciada para a instância
Use as guias abaixo para obter instruções que correspondam à sua experiência preferida.
Primeiro, verifique se você habilitou uma identidade gerenciada para sua instância dos Gêmeos Digitais do Azure.
Além disso, verifique se você tem a função de Proprietário de Dados dos Gêmeos Digitais do Azure na instância. Você pode encontrar instruções em Configurar permissões de acesso do usuário.
2. Atribuir funções do Azure à identidade
Depois que uma identidade gerenciada for criada para a sua instância dos Gêmeos Digitais do Azure, você precisará atribuir a ela as funções apropriadas para autenticar com diferentes tipos de pontos de extremidade a fim de encaminhar eventos para destinos com suporte. Esta seção descreve as opções de função e como atribuí-las à identidade gerenciada.
Importante
Conclua esta etapa. Sem ela, a identidade não será capaz de acessar seus pontos de extremidade e os eventos não serão entregues.
Aqui estão as funções mínimas que a identidade de Gêmeos Digitais do Azure precisa para acessar um ponto de extremidade, dependendo do tipo de destino. Funções com permissões mais altas (como funções de proprietário de dados) também funcionarão.
| Destino | Função do Azure |
|---|---|
| Hubs de eventos do Azure | Remetente de dados dos Hubs de Eventos do Azure |
| Barramento de Serviço do Azure | Remetente de dados do Barramento de Serviço do Azure |
| Contêiner de armazenamento do Azure | Colaborador de dados de blob de armazenamento |
Use as guias abaixo para atribuir a função usando sua experiência preferida.
Para atribuir uma função à identidade, comece abrindo o portal do Azure em um navegador.
Navegue até o recurso de ponto de extremidade (seu hub de eventos, tópico do Barramento de Serviço ou contêiner de armazenamento) pesquisando seu nome na barra de pesquisa do portal.
Selecione IAM (Controle de acesso) .
Selecione Adicionar>Adicionar atribuição de função para abrir a página Adicionar atribuição de função.
Atribua a função desejada à identidade gerenciada da instância dos Gêmeos Digitais do Azure usando as informações abaixo. Para ver as etapas detalhadas, confira Atribuir funções do Azure usando o portal do Azure.
Configuração Valor Função Escolha a função desejada nas opções. Atribuir acesso a Identidade gerenciada Membros Escolha a identidade gerenciada atribuída pelo usuário ou atribuída pelo sistema da instância dos Gêmeos Digitais do Azure que está sendo atribuída à função. Uma identidade atribuída pelo usuário terá o nome escolhido ao criar a identidade e uma identidade atribuída pelo sistema terá um nome que corresponda ao nome da instância dos Gêmeos Digitais do Azure. 
3. Criar o ponto de extremidade com autenticação baseada em identidade
Depois de configurar uma identidade gerenciada para sua instância dos Gêmeos Digitais do Azure e atribuir a ela as funções apropriadas, crie os pontos de extremidade que usam a identidade para autenticação. Essa opção está disponível apenas para os pontos de extremidade do Hub de Eventos e do tipo de Barramento de Serviço (não tem suporte pela Grade de Eventos).
Observação
Você não pode editar um ponto de extremidade que já foi criado com a identidade baseada em chave para mudar para a autenticação baseada em identidade. Você deve escolher o tipo de autenticação quando o ponto de extremidade é criado pela primeira vez.
Use as guias abaixo para criar o ponto de extremidade usando sua experiência preferida.
Comece seguindo as instruções gerais para criar um ponto de extremidade dos Gêmeos Digitais do Azure.
Quando chegar à etapa de concluir os detalhes necessários para o seu tipo de ponto de extremidade, selecione Atribuído pelo sistema ou Atribuído pelo usuário (versão prévia) para o tipo de Autenticação.
Conclua a configuração de seu ponto de extremidade e selecione Salvar.
Considerações sobre a desabilitação de identidades gerenciadas
Como uma identidade é gerenciada separadamente dos pontos de extremidade que a usam, é importante considerar os efeitos que qualquer alteração na identidade ou em suas funções podem ter sobre os pontos de extremidade da instância dos Gêmeos Digitais do Azure. Se a identidade estiver desabilitada ou se uma função necessária para um ponto de extremidade for removida dele, o ponto de extremidade poderá ficar inacessível, interrompendo o fluxo de eventos.
Para continuar usando um ponto de extremidade que foi configurado com uma identidade gerenciada que agora foi desabilitada, você precisará excluir o ponto de extremidade e recriá-lo com um tipo de autenticação diferente. Pode levar até uma hora para que os eventos retomem a entrega para o ponto de extremidade após essa alteração.
Opções de ponto de extremidade: mensagens mortas
Quando um ponto de extremidade não puder entregar um evento dentro de um determinado período ou depois de tentar entregar o evento um determinado número de vezes, ela poderá enviar o evento não entregue a uma conta de armazenamento. Esse processo é conhecido como armazenamento de mensagens mortas.
Você pode configurar os recursos de armazenamento necessários usando o portal do Azure ou a CLI dos Gêmeos Digitais do Azure. No entanto, para criar um ponto de extremidade com mensagens mortas habilitadas, será preciso usar a CLI dos Gêmeos Digitais do Azure ou as APIs do painel de controle.
Para saber mais sobre mensagens mortas, confira Pontos de extremidade e rotas de eventos. Para obter instruções sobre como configurar um ponto de extremidade com mensagens mortas, continue no restante desta seção.
Configurar os recursos de armazenamento
Antes de configurar o local de mensagens mortas, você deve ter uma conta de armazenamento com um contêiner configurado na conta do Azure.
Você fornecerá o URI para esse contêiner ao criar o ponto de extremidade posteriormente. O local de mensagens mortas será fornecido ao ponto de extremidade como um URI de contêiner com um token SAS. Esse token precisa de permissão write para o contêiner de destino dentro da conta de armazenamento. O URI de SAS de mensagens mortas totalmente formado estará no formato de: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.
Siga as etapas abaixo para configurar esses recursos de armazenamento na conta do Azure, a fim de se preparar para configurar a conexão de ponto de extremidade na próxima seção.
- Siga as etapas em Criar uma conta de armazenamento para criar uma conta de armazenamento na assinatura do Azure. Anote o nome da conta de armazenamento para uso posterior.
- Siga as etapas em Criar um contêiner para criar um contêiner dentro da nova conta de armazenamento. Anote o nome da conta do contêiner para uso posterior.
Criar um token SAS
Em seguida, crie um token SAS para a conta de armazenamento que pode ser usada pelo ponto de extremidade para acessá-la.
Comece navegando até a conta de armazenamento no portal do Azure (você pode encontrá-la por nome com a barra de pesquisa do portal).
Na página da conta de armazenamento, escolha o link Assinatura de acesso compartilhado na barra de navegação à esquerda para iniciar a configuração do token SAS.
Na página Assinatura de Acesso Compartilhado, em Serviços permitidos e Tipos de recursos permitidos, selecione todas as configurações que desejar. Você precisará selecionar pelo menos uma caixa em cada categoria. Em Permissões permitidas, escolha Gravar (você também pode selecionar outras permissões, se desejar).
Defina quaisquer valores desejados para as configurações restantes.
Quando terminar, selecione o botão Gerar SAS e cadeia de conexão para gerar o token SAS.
Ao fazer isso, gerará vários valores de cadeia de conexão e de SAS na parte inferior da mesma página, sob as seleções de configuração. Role para baixo para exibir os valores e use o ícone Copiar para área de transferência para copiar o valor do token SAS. Salve-o para uso posterior.
Criar o ponto de extremidade de mensagens mortas
Para criar um ponto de extremidade com mensagens mortas habilitadas, você deve usar os comandos da CLI ou as APIs do painel de controle, em vez do portal do Azure.
Para obter instruções sobre como criar esse tipo de ponto de extremidade com a CLI do Azure, mude para a guia CLI desta seção.
Esquema de armazenamento de mensagens
Depois que o ponto de extremidade com mensagens mortas estiver configurado, as mensagens mortas serão armazenadas no seguinte formato na conta de armazenamento:
<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json
As mensagens mortas corresponderão ao esquema do evento original que deveria ser entregue ao ponto de extremidade original.
Aqui está um exemplo de uma mensagem morta para uma notificação de criação de gêmeo:
{
"specversion": "1.0",
"id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
"type": "Microsoft.DigitalTwins.Twin.Create",
"source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
"data": {
"$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
"$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
"TwinData": "some sample",
"$metadata": {
"$model": "dtmi:test:deadlettermodel;1",
"room": {
"lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
}
}
},
"subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
"time": "2020-10-14T01:11:49.3667224Z",
"datacontenttype": "application/json",
"traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}
Próximas etapas
Para realmente enviar dados dos Gêmeos Digitais do Azure para um ponto de extremidade, você precisará definir uma rota de evento. Essas rotas permitem que os desenvolvedores conectem o fluxo de eventos de todo o sistema e aos serviços downstream. Uma só rota pode permitir a escolha de várias notificações e tipos de eventos. Continue a criar uma rota de evento para o ponto de extremidade em Criar rotas e filtros.