Criar pontos de extremidade em 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.
Rotear 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 eventos para enviar dados para esses pontos de extremidade. Este artigo aborda a primeira etapa, a configuração de pontos de extremidade que podem receber os eventos. Mais tarde, você pode criar rotas de eventos que especificam quais eventos gerados pelos Gêmeos Digitais do Azure são entregues a quais pontos de extremidade.
Pré-requisitos
Você precisará de uma conta do Azure, que pode ser configurada gratuitamente
Você precisará de uma instância do Azure Digital Twins em sua assinatura do Azure. Se você ainda não tiver uma instância, poderá criar uma usando as etapas em Configurar uma instância e autenticação. Tenha os seguintes valores da configuração à mão para usar mais adiante neste artigo:
- Nome da instância
- Grupo de recursos
Você pode encontrar esses detalhes no portal do Azure depois de configurar sua instância.
Em seguida, siga as instruções abaixo se você pretende usar a CLI do Azure enquanto segue este guia.
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.
Criar os recursos necessários
Esses serviços são os tipos suportados de pontos de extremidade que você pode criar para sua instância:
- Tópico Grade de Eventos
- Para pontos de extremidade de Grade de Eventos, somente tópicos de Grade de Eventos são suportados. Os domínios da Grade de Eventos não são suportados como pontos de extremidade.
- Hub de Hubs de Eventos
- Tópico do Service Bus
Para vincular um ponto de extremidade aos Gêmeos Digitais do Azure, o tópico Grade de Eventos, hub de eventos ou tópico do Service Bus que você está usando para o ponto de extremidade já precisa existir.
Use o gráfico a seguir para ver quais recursos devem ser configurados antes de criar seu ponto de extremidade.
| Tipo de ponto final | Recursos necessários (vinculados às instruções de criação) |
|---|---|
| Ponto de extremidade da Grade de Eventos | Tópico Grade de Eventos *o esquema de eventos deve ser Event Grid Schema ou Cloud Event Schema v1.0 |
| Ponto de extremidade dos Hubs de Eventos | Namespace de Hubs de Eventos Hub de eventos (Opcional) Regra de autorização para autenticação baseada em chave |
| Ponto de extremidade do Service Bus | Namespace do Service Bus Tópico do Service Bus (Opcional) Regra de autorização para autenticação baseada em chave |
Criar o ponto de extremidade
Depois de criar os recursos de ponto de extremidade, você pode usá-los para um ponto de extremidade do Azure Digital Twins.
Para criar um novo ponto de extremidade, vá para a página da sua instância no portal do Azure (você pode encontrar a instância inserindo seu nome na barra de pesquisa do portal).
No menu de instância, selecione Pontos de extremidade. Em seguida, na página Pontos de extremidade a seguir, selecione + Criar um ponto de extremidade. Isso abrirá a página Criar um ponto final , onde você preencherá os campos nas etapas a seguir.
Insira um Nome para seu ponto de extremidade e escolha o tipo de ponto de extremidade.
Preencha os outros detalhes necessários para seu tipo de ponto de extremidade, incluindo sua assinatura e os recursos de ponto de extremidade descritos anteriormente.
- Somente para Hubs de Eventos e pontos de extremidade do Service Bus, você deve selecionar um tipo de Autenticação. Você pode usar a autenticação baseada em chave com uma regra de autorização pré-criada ou uma identidade gerenciada atribuída pelo sistema ou pelo usuário. Para obter mais informações sobre como usar as opções de autenticação de identidade, consulte Opções de ponto de extremidade: autenticação baseada em identidade.
Conclua a criação do seu ponto de extremidade selecionando Salvar.
Depois de criar seu ponto de extremidade, você pode verificar se o ponto de extremidade foi criado com êxito verificando o ícone de notificação na barra superior do portal do Azure:
Se a criação do ponto de extremidade falhar, observe a mensagem de erro e tente novamente após alguns minutos.
Você também pode exibir o ponto de extremidade que foi criado novamente na página Pontos de extremidade para sua instância do Azure Digital Twins.
Agora, o tópico Grade de Eventos, hub de eventos ou tópico do Service Bus está disponível como um ponto de extremidade nos Gêmeos Digitais do Azure, sob 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 do Azure Digital Twins ao encaminhar eventos para destinos de roteamento com suporte. A configuração de uma identidade gerenciada não é necessária para roteamento, mas pode ajudar a instância a acessar facilmente outros recursos protegidos pelo Microsoft Entra, como Hubs de Eventos, destinos do Barramento de Serviço e Contêiner de Armazenamento do Azure. As identidades gerenciadas podem ser atribuídas ao sistema ou ao usuário.
O restante desta seção percorre três etapas para configurar um ponto de extremidade com uma identidade gerenciada.
1. Habilite a identidade gerenciada para a instância
Use as guias abaixo para obter instruções que correspondam à sua experiência preferida.
Primeiro, certifique-se de que ativou uma identidade gerida para a sua instância dos Gêmeos Digitais do Azure.
Além disso, 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.
2. Atribuir funções do Azure à identidade
Depois que uma identidade gerenciada for criada para sua instância do Azure Digital Twins, você precisará atribuir a ela funções apropriadas para autenticar com diferentes tipos de pontos de extremidade para rotear eventos para destinos com suporte. Esta seção descreve as opções de função e como atribuí-las à identidade gerenciada.
Importante
Certifique-se de concluir esta etapa. Sem ele, a identidade não poderá acessar seus endpoints e os eventos não serão entregues.
Aqui estão as funções mínimas que sua 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 |
| Azure Service Bus | Remetente de Dados do Azure Service Bus |
| Contêiner de armazenamento do Azure | Contribuidor de Dados de Blobs 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 Service Bus ou contêiner de armazenamento) pesquisando seu nome na barra de pesquisa do portal.
Selecione Controlo de acesso (IAM) .
Selecione Adicionar>Adicionar atribuição de funções para abrir o painel Adicionar atribuição de funções.
Atribua a função desejada à identidade gerenciada de sua instância do Azure Digital Twins, usando as informações abaixo. Para obter os passos detalhados, veja o artigo Atribuir funções do Azure com o portal do Azure.
Definição Value Role Selecione a função desejada entre as opções. Atribuir acesso a Identidade gerida Membros Selecione a identidade gerenciada atribuída pelo usuário ou pelo sistema da sua instância do Azure Digital Twins que está sendo atribuída à função. Uma identidade atribuída pelo usuário terá o nome que você escolheu quando criou a identidade, e uma identidade atribuída ao sistema terá um nome que corresponde ao nome da sua instância do Azure Digital Twins. 
3. Crie o ponto de extremidade com autenticação baseada em identidade
Depois de configurar uma identidade gerenciada para sua instância do Azure Digital Twins e atribuir-lhe a(s) função(ões) apropriada(s), você pode criar os pontos de extremidade que usam a identidade para autenticação. Essa opção só está disponível para Hubs de Eventos e pontos de extremidade do tipo Service Bus (não há suporte para Grade de Eventos).
Nota
Não é possível editar um ponto de extremidade que já tenha sido criado com identidade baseada em chave para alterar para autenticação baseada em identidade. Você deve escolher o tipo de autenticação quando o ponto de extremidade for criado pela primeira vez.
Use as guias abaixo para criar o ponto de extremidade usando sua experiência preferida.
Comece a seguir as instruções gerais para criar um ponto de extremidade do Azure Digital Twins.
Quando chegar à etapa de preenchimento dos detalhes necessários para o tipo de ponto final, selecione Atribuído pelo sistema ou Atribuído pelo usuário (visualização) para o tipo de autenticação.
Conclua a configuração do seu endpoint e selecione Guardar.
Considerações para desabilitar identidades gerenciadas
Como uma identidade é gerenciada separadamente dos pontos de extremidade que a usam, é importante considerar os efeitos que quaisquer alterações na identidade ou em suas funções podem ter nos pontos de extremidade em sua instância do Azure Digital Twins. Se a identidade for desabilitada ou uma função necessária para um ponto de extremidade for removida dela, o ponto de extremidade poderá ficar inacessível e o fluxo de eventos será interrompido.
Para continuar a utilizar um ponto final que foi configurado com uma identidade gerida que está, agora, desativada, terá de eliminar o ponto final e recriá-lo com um tipo de autenticação diferente. Os eventos podem demorar até uma hora a retomar a entrega para o ponto final após esta alteração.
Opções de ponto final: Dead-lettering
Quando um ponto de extremidade não consegue entregar um evento dentro de um determinado período de tempo ou depois de tentar entregar o evento um determinado número de vezes, ele pode enviar o evento não entregue para uma conta de armazenamento. Este processo é conhecido como dead-lettering.
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 letras mortas habilitadas, você precisará usar a CLI do Azure Digital Twins ou APIs de plano de controle.
Para saber mais sobre letras mortas, consulte Pontos de extremidade e rotas de eventos. Para obter instruções sobre como configurar um ponto de extremidade com letras mortas, continue pelo restante desta seção.
Configurar recursos de armazenamento
Antes de definir o local de letra morta, você deve ter uma conta de armazenamento com um contêiner configurado em sua conta do Azure.
Você fornecerá o URI para esse contêiner ao criar o ponto de extremidade posteriormente. O local de letra morta será fornecido ao ponto de extremidade como um URI de contêiner com um token SAS. Esse token precisa de write permissão para o contêiner de destino dentro da conta de armazenamento. A letra morta SAS URI totalmente formada será 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 em sua conta do Azure, para 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 em sua assinatura do Azure. Anote o nome da conta de armazenamento para usá-lo mais tarde.
- Siga as etapas em Criar um contêiner para criar um contêiner dentro da nova conta de armazenamento. Anote o nome do contêiner para usá-lo mais tarde.
Criar um token SAS
Em seguida, crie um token SAS para sua conta de armazenamento que o ponto de extremidade possa usar para acessá-la.
Comece navegando até sua conta de armazenamento no portal do Azure (você pode encontrá-la pelo nome na 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 as configurações desejadas. 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 os 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.
Isso gerará vários valores de SAS e cadeia de conexão na parte inferior da mesma página, abaixo das 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 usar mais tarde.
Criar o ponto de extremidade de letra morta
Para criar um ponto de extremidade com letras mortas habilitado, você deve usar os comandos da CLI ou APIs do plano de controle para criar seu ponto de extremidade, em vez do portal do Azure.
Para obter instruções sobre como criar esse tipo de ponto de extremidade com a CLI do Azure, alterne para a guia CLI desta seção.
Esquema de armazenamento de mensagens
Assim que o ponto de extremidade com letras mortas estiver configurado, as mensagens com letras mortas serão armazenadas no seguinte formato na sua conta de armazenamento:
<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json
As mensagens com letras mortas corresponderão ao esquema do evento original que deveria ser entregue ao seu ponto de extremidade original.
Aqui está um exemplo de uma mensagem de letra morta para uma notificação de criação gêmea:
{
"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óximos passos
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 em todo o sistema e aos serviços downstream. Uma única rota pode permitir a seleção de várias notificações e tipos de eventos. Continue a criar uma rota de evento para seu ponto de extremidade em Criar rotas e filtros.