Criar pontos de extremidade nos Gêmeos Digitais do Azure

Este artigo explica como criar um ponto de extremidade para os eventos do Gêmeo Digital do Azure usando o portal do Azure ou a CLI do Azure. Você também pode gerenciar endpoints com as APIs do plano de gerenciamento DigitalTwinsEndpoint.

Encaminhar as notificações de eventos dos Gêmeos Digitais do Azure para os 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 que enviam dados para esses pontos de extremidade. Este artigo aborda a primeira etapa: a configuração de endpoints capazes de receber eventos. Posteriormente, você pode criar rotas de evento que especificam quais eventos gerados pelos Gêmeos Digitais do Azure são entregues aos quais pontos de extremidade.

Pré-requisitos

Uma conta do Azure, que você pode configurar gratuitamente.
Uma instância de Azure Digital Twins em sua assinatura 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 configuraçã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 a sua instância.

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

Preparar o ambiente para a CLI do Azure

Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Introdução ao 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 obter outras opções de entrada, consulte Autenticar no Azure usando 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 e gerenciar 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 com suporte pelos pontos de extremidade que você pode criar para sua instância:

Tópico do Event Grid
- 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 os pontos de extremidade.
Hub do Hubs de Eventos
Tópico do Barramento de Serviço

Antes de vincular um ponto de extremidade aos Gêmeos Digitais do Azure, você precisa criar 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.

Use o gráfico a seguir para ver quais recursos você deve configurar 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	Tópico da Grade de Eventos (O esquema de eventos deve ser Esquema de Grade de Eventos ou Esquema de Eventos na Nuvem v1.0)
Ponto de extremidade dos Hubs de Eventos	Namespace do Hubs de Eventos hub de evento (Opcional) 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 (Opcional) 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ê pode criar o ponto de extremidade dos Gêmeos Digitais do Azure. Use as guias a seguir para selecionar sua experiência preferida.

Portal
CLI

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

No menu da instância, selecione Conectar saídas > Pontos de extremidade. Em seguida, na página Pontos de Extremidade , selecione + Criar um ponto de extremidade. Essa ação abre a página Criar um ponto de extremidade .
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.
1. Somente para os pontos de extremidade dos Hubs de Eventos e Barramento de Serviço, 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 atribuída pelo usuário. A identidade atribuída pelo sistema só estará disponível se você tiver habilitado uma identidade atribuída pelo 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 posteriormente neste artigo.
Conclua a criação do ponto de extremidade escolhendo a opção Salvar.

Depois de criar o ponto de extremidade, você poderá conferir se ele foi criado com sucesso verificando o ícone de notificação na barra superior do portal do Azure:

Captura de tela da notificação para verificar a criação de um endpoint no 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 visualizar o ponto de extremidade que criou na página Pontos de Extremidade da sua instância dos Gêmeos Digitais do Azure.

Agora, o tópico da Grade de Eventos, o hub de eventos ou o tópico do Barramento de Serviço está disponível como um ponto de extremidade nos Gêmeos Digitais do Azure, sob o nome escolhido para o ponto de extremidade. Normalmente, você usa esse nome como 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 dos Gêmeos Digitais do Azure. Substitua os espaços reservados nos comandos pelas informações de seus recursos.

Para criar um tópico 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 endpoint dos 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 Barramento de Serviço (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 do Event Grid, o hub de eventos ou o tópico do Service Bus estão disponíveis como um endpoint nos Azure Digital Twins. O ponto de extremidade tem o nome fornecido com o argumento --endpoint-name. Normalmente, você usa 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 guia você por três etapas para configurar um endpoint com uma identidade gerenciada.

1. Habilitar uma identidade gerenciada para a instância

Use as guias a seguir para obter instruções que correspondam à sua experiência preferida.

Portal
CLI

Primeiro, habilite 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 de criar uma identidade gerenciada para sua instância do Azure Digital Twins, atribua permissões adequadas para autenticar em 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

Conclua esta etapa. Sem ele, a identidade não pode acessar seus pontos de extremidade e os eventos não são entregues.

Aqui estão os perfis mínimos que sua identidade do Azure Digital Twins precisa para acessar um endpoint, 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
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 no Blobs de Armazenamento

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

Portal
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 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. 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 tem o nome escolhido quando você criou a identidade e uma identidade atribuída pelo sistema tem um nome que corresponde ao nome da instância dos Gêmeos Digitais do Azure.

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

Este exemplo cria uma instância com uma identidade gerenciada atribuída pelo sistema e atribui essa identidade a 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 esse comando, confira a Documentação de referência de 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. Criar o ponto de extremidade com autenticação baseada em identidade

Após estabelecer uma identidade gerenciada para sua instância de Azure Digital Twins e atribuir as permissões adequadas, crie os endereços finais que utilizam 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 há suporte para a Grade de Eventos).

Observação

Você não pode editar um ponto de extremidade criado com identidade baseada em chave para alterar para a autenticação baseada em 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 endpoint usando sua experiência de preferência.

Portal
CLI

Comece seguindo as instruções gerais para criar um endpoint 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.

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

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

Comando de identidade atribuída pelo sistema

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

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 a ID do recurso de identidade atribuída pelo usuário com o parâmetro --user. O exemplo a seguir ilustra essa funcionalidade para um endpoint do Event Hubs.

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 sobre a desabilitação de identidades gerenciadas

Uma identidade é gerenciada separadamente dos pontos de extremidade que a usam, portanto, é importante considerar como qualquer alteração na identidade ou em suas funções pode afetar os pontos de extremidade em sua instância dos Gêmeos Digitais do Azure. Se você desabilitar a identidade ou remover uma função necessária para um ponto de extremidade, o ponto de extremidade ficará inacessível e o fluxo de eventos será 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 destino após essa alteração.

Opções de ponto de extremidade: mensagens mortas

Quando um ponto de extremidade não pode 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. 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, é preciso usar a CLI dos Gêmeos Digitais do Azure ou as APIs do painel de controle.

Para saber mais sobre mensagens mortas, veja 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 na sua conta do Azure.

Ao criar o ponto de extremidade, você fornece o URI desse contêiner. O local de mensagens mortas é 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 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, você pode configurar a conexão ao 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 que você possa 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 que você possa usá-lo mais tarde.

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.

Portal
CLI

Navegue até sua conta de armazenamento no portal do Azure (você pode encontrá-la pelo nome com a 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 começar a configurar o 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.
Ao concluir esse processo, vários valores de SAS e cadeia de conexão são gerados 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 uso posterior.

Recupere as chaves de sua conta de armazenamento usando o seguinte comando e copie o valor de uma delas:
```
az storage account keys list --account-name <storage-account-name>
```
Selecione uma data de validade e gere o token SAS para sua conta de armazenamento com 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 do comando é o token SAS. Copie o valor do token SAS para usar mais tarde.

Observação

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

Para saber mais sobre o comando az storage account generate-sas e os parâmetros dele, veja a Referência da CLI do Azure.

Criar o ponto de extremidade de mensagens mortas

Portal
CLI

Para criar um ponto de extremidade com mensagens mortas habilitadas, use os comandos da CLI ou as APIs do painel de controle para criar seu ponto de extremidade. Você não pode criar esse 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, mude para a guia CLI desta seção.

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

O valor para o parâmetro é o URI de SAS de mensagens mortas, composto pelo nome da conta de armazenamento, do nome do contêiner e do token SAS que você reuniu na seção anterior. Esse parâmetro cria o ponto de extremidade com autenticação baseada em chave. Veja a aparência do parâmetro:

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

Dica

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

Você também pode criar pontos de extremidade de mensagens mortas usando as APIs do painel de controle dos Gêmeos Digitais do Azure em vez da CLI. Para fazer isso, exiba a documentação do DigitalTwinsEndpoint para ver como estruturar a solicitação e adicionar os parâmetros de mensagens mortas.

Esquema de armazenamento de mensagens

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

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

As mensagens enviadas para a fila de mensagens mortas correspondem ao esquema do evento original que seu ponto de extremidade original deveria entregar.

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

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

Comentários

Esta página foi útil?

Last updated on 2025-06-19