Criar pontos de extremidade em Gêmeos Digitais do Azure

2025-06-19

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 que enviem 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

Uma conta do Azure, que você pode configurar gratuitamente.
Uma instância do Azure Digital Twins na sua subscrição do Azure. Se você não tiver uma instância, crie uma seguindo as etapas em Configurar uma instância e autenticação. Tenha os seguintes valores da instalação disponíveis para uso posterior neste artigo:
- Nome da instância
- Grupo de recursos
Você pode encontrar esses detalhes no portal do Azure depois de configurar sua instância.

Se você pretende usar a CLI do Azure enquanto segue este guia, siga as instruções na próxima seção.

Prepare o seu ambiente para o CLI do Azure

Use o ambiente Bash no Azure Cloud Shell. Para mais informações, veja Get started with 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 Autenticar no Azure usando a CLI do Azure.
- Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre extensões, consulte Usar e gerenciar extensões com a 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

Antes de vincular um ponto de extremidade ao Azure Digital Twins, precisa criar o Event Grid topic, o hub de eventos ou o tópico do Service Bus que está a utilizar para o ponto de extremidade.

Use o gráfico a seguir para ver quais recursos você deve configurar 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 criar o ponto de extremidade do Azure Digital Twins. Use as guias a seguir para selecionar sua experiência preferida.

Portais
CLI

Para criar um novo ponto final, vá para a página da instância no Portal do Azure. Você pode encontrar a instância digitando seu nome na barra de pesquisa do portal.

No menu de instâncias, selecione Connect outputs > Endpoints. Em seguida, na página Pontos de extremidade , selecione + Criar um ponto de extremidade. Esta ação abre a página Criar um endpoint.
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.
1. Apenas para Hubs de Eventos e endpoints do Service Bus, selecione 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. A identidade atribuída ao sistema só estará disponível se você tiver habilitado uma identidade atribuída ao sistema para a instância. 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 mais adiante neste artigo.
Conclua a criação do seu ponto de extremidade selecionando Salvar.

Depois de criar seu ponto de extremidade, você pode verificar se ele foi criado com êxito verificando o ícone de notificação na barra superior do portal do Azure:

Captura de ecrã da notificação para verificar a criação de um ponto de extremidade no 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 criou 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ê usa esse nome como o destino de uma rota de evento, que pode ser criada em Criar rotas e filtros.

Os exemplos a seguir mostram como criar pontos de extremidade usando o comando az dt endpoint create para a CLI do Azure Digital Twins. Substitua os espaços reservados nos comandos pelos detalhes dos seus próprios recursos.

Para criar um ponto de extremidade da Grade de Eventos:

az dt endpoint create eventgrid --endpoint-name <Event-Grid-endpoint-name> --eventgrid-resource-group <Event-Grid-resource-group-name> --eventgrid-topic <your-Event-Grid-topic-name> --dt-name <your-Azure-Digital-Twins-instance-name>

Para criar um ponto de extremidade de Hubs de Eventos (autenticação baseada em chave):

az dt endpoint create eventhub --endpoint-name <Event-Hub-endpoint-name> --eventhub-resource-group <Event-Hub-resource-group> --eventhub-namespace <Event-Hub-namespace> --eventhub <Event-Hub-name> --eventhub-policy <Event-Hub-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

Para criar um ponto de extremidade de tópico do Service Bus (autenticação baseada em chave):

az dt endpoint create servicebus --endpoint-name <Service-Bus-endpoint-name> --servicebus-resource-group <Service-Bus-resource-group-name> --servicebus-namespace <Service-Bus-namespace> --servicebus-topic <Service-Bus-topic-name> --servicebus-policy <Service-Bus-topic-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

Depois de executar esses comandos, o tópico Event Grid, hub de eventos ou tópico do Service Bus estará disponível como um ponto de extremidade no Azure Digital Twins. O ponto de extremidade tem o nome que forneceu com o --endpoint-name argumento. Normalmente, você usa esse nome como o 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 a seguir para obter instruções que correspondam à sua experiência preferida.

Portais
CLI

Primeiro, certifique-se de habilitar uma identidade gerenciada para sua instância do Azure Digital Twins.

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 de criar uma identidade gerenciada para sua instância do Azure Digital Twins, atribua-lhe 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 pode acessar seus endpoints e os eventos não sã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 funcionam.

Destino	Função do Azure
Hubs de Eventos do Azure	Remetente de Dados dos Hubs de Eventos do Azure
Azure Service Bus (uma solução de mensageria na nuvem da Microsoft)	Remetente de Dados do Azure Service Bus
Contêiner de armazenamento do Azure	Contribuidor de Dados de Blobs de Armazenamento

Use as guias a seguir para atribuir a função usando sua experiência preferida.

Portais
CLI

Para atribuir uma função à identidade, abra 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. Para obter os passos detalhados, veja o artigo Atribuir funções do Azure com o portal do Azure.

Definição	Valor
Funções	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 tem o nome que você escolheu quando criou a identidade, e uma identidade atribuída ao sistema tem um nome que corresponde ao nome da sua instância do Azure Digital Twins.

Você pode adicionar o --scopes parâmetro ao az dt create comando para atribuir a identidade a um ou mais escopos com uma função especificada. Use esse comando ao criar a instância pela primeira vez ou depois passando o nome de uma instância existente.

Veja um exemplo que cria uma instância com uma identidade gerenciada atribuída ao sistema e atribui a essa identidade uma função personalizada chamada MyCustomRole em um hub de eventos.

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned --scopes "/subscriptions/<subscription ID>/resourceGroups/<resource-group>/providers/Microsoft.EventHub/namespaces/<Event-Hubs-namespace>/eventhubs/<event-hub-name>" --role MyCustomRole

Para obter mais exemplos de atribuições de função com este comando, consulte a documentação de referência az dt create.

Você também pode usar o grupo de comandos az role assignment para criar e gerenciar funções. Use este comando para dar suporte a outros cenários em que você não deseja agrupar a atribuição de função com o comando create.

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 as funções apropriadas, crie 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 criado com uma identidade baseada em chave para mudar para autenticação por identidade. Você deve escolher o tipo de autenticação ao criar o ponto de extremidade pela primeira vez.

Use as seções a seguir para criar o ponto de extremidade usando sua experiência preferida.

Portais
CLI

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.

Adicione identidades gerenciadas a um ponto de extremidade adicionando parâmetros ao az dt endpoint create comando. Para obter mais informações sobre esse comando, consulte sua documentação de referência ou as instruções gerais para criar um ponto de extremidade do Azure Digital Twins.

Use o seguinte comando da CLI para o tipo de identidade gerenciada escolhido.

Comando de identidade atribuído pelo sistema

Para criar um ponto de extremidade que usa autenticação atribuída pelo sistema, especifique o IdentityBased tipo de autenticação com o --auth-type parâmetro. O exemplo a seguir ilustra esta funcionalidade para um ponto de extremidade do Hub de Eventos.

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --auth-type IdentityBased

Comando de identidade atribuída pelo usuário

Para criar um ponto de extremidade que usa a autenticação de identidade atribuída pelo usuário, especifique o ID do recurso de identidade atribuído ao usuário com o --user parâmetro. O exemplo a seguir ilustra esta funcionalidade para um ponto de extremidade do Hub de Eventos.

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --user <user-assigned-identity-resource-ID>

Considerações para desabilitar identidades gerenciadas

Uma identidade é gerenciada separadamente dos pontos de extremidade que a usam, por isso é importante considerar como qualquer alteração na identidade ou em suas funções pode afetar os pontos de extremidade em sua instância do Azure Digital Twins. Se desativar a identidade ou remover uma função necessária para um endpoint, o endpoint ficará inacessível e o fluxo de eventos ficará interrompido.

Para continuar usando um ponto de extremidade que foi configurado com uma identidade gerenciada que você desabilitou, exclua o ponto de extremidade e recrie-o com um tipo de autenticação diferente. Pode levar até uma hora para que os eventos retomem a entrega ao endpoint 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 número de tentativas, 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ê precisa 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 em sua conta do Azure.

Ao criar o ponto de extremidade, você fornece o URI desse contêiner. O local de letra morta é 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 está no formato de: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.

Para configurar esses recursos de armazenamento em sua conta do Azure, siga as etapas na seção a seguir. Depois de configurar os recursos de armazenamento, pode configurar a ligação do ponto de extremidade (endpoint).

Para criar uma conta de armazenamento em sua assinatura do Azure, siga as etapas em Criar uma conta de armazenamento. Anote o nome da conta de armazenamento para poder usá-lo mais tarde.
Para criar um contêiner dentro da nova conta de armazenamento, siga as etapas em Criar um contêiner. Anote o nome do contêiner para poder 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.

Portais
CLI

Navegue 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 Segurança + rede > 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ê precisa selecionar pelo menos uma caixa em cada categoria. Em Permissões permitidas, escolha Gravar. Você também pode selecionar outras permissões.
Defina os valores desejados para as configurações restantes.
Quando terminar, selecione Gerar SAS e cadeia de conexão para gerar o token SAS.
A conclusão desse processo gera 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.

Recupere as chaves da conta de armazenamento usando o seguinte comando e copie o valor de qualquer uma das chaves:
```
az storage account keys list --account-name <storage-account-name>
```
Selecione uma data de expiração e gere o token SAS para sua conta de armazenamento usando o seguinte comando:
```
az storage account generate-sas --account-name <storage-account-name> --account-key <storage-account-key> --expiry <expiration-date> --services bfqt --resource-types o --permissions w
```
A saída deste comando é o token SAS. Copie o valor do token SAS para usar mais tarde.

Nota

O conjunto de exemplos de parâmetros no comando anterior inclui serviços "blob", "file", "queue" e "table" (--services bfqt), um tipo de recurso "object" (--resource-types o) e permissões "write" (--permissions w).

Para obter mais informações sobre o az storage account generate-sas comando e seus parâmetros, consulte a referência da CLI do Azure.

Criar o ponto de extremidade de letra morta

Portais
CLI

Para criar um ponto de extremidade com letras mortas habilitadas, use os comandos da CLI ou as APIs do plano de controle para criar seu ponto de extremidade. Não é possível criar este tipo de ponto de extremidade no 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.

Para criar um ponto de extremidade com letras mortas habilitado, adicione o --deadletter-sas-uri parâmetro ao comando az dt endpoint create que cria um ponto de extremidade.

O valor do parâmetro é o URI SAS de letra morta composto pelo nome da conta de armazenamento, nome do contêiner e token SAS que você reuniu na seção anterior. Este parâmetro cria o ponto de extremidade com autenticação baseada em chave. Veja como é o parâmetro:

--deadletter-sas-uri https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>

Gorjeta

Para criar um ponto de extremidade de letra morta com autenticação baseada em identidade, adicione o parâmetro de letra morta desta seção e o parâmetro de identidade gerenciada apropriado ao mesmo comando.

Você também pode criar pontos de extremidade de letra morta usando as APIs do plano de controle do Azure Digital Twins em vez da CLI. Para fazer isso, consulte a documentação do DigitalTwinsEndpoint para ver como estruturar a solicitação e adicionar os parâmetros de letra morta.

Esquema de armazenamento de mensagens

Depois de configurar o ponto de extremidade com letras mortas, as mensagens com letras mortas são armazenadas em sua conta de armazenamento no seguinte formato:

<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json

As mensagens com letras mortas correspondem ao esquema do evento original que o ponto de extremidade original pretendia entregar.

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

Depois de criar um ponto de extremidade, defina uma rota de evento para enviar dados para o ponto de extremidade. As rotas de eventos permitem configurar o fluxo de eventos em todo o sistema e para serviços downstream. Uma única rota pode permitir várias notificações e tipos de eventos. Crie uma rota de evento para o ponto de extremidade seguindo as instruções em Criar rotas e filtros.

Comentários

Esta página foi útil?