Configurar uma instância e uma autenticação (CLI) dos Gêmeos Digitais do Azure

  • Artigo

Este artigo abordará etapas para configurar uma nova instância dos Gêmeos Digitais do Azure, incluindo a criação da instância e a configuração da autenticação. Após concluir este artigo, uma instância dos Gêmeos Digitais do Azure estará pronta para você começar a programar nela.

A configuração completa para uma nova instância dos Gêmeos Digitais do Azure consiste em duas partes:

  1. Criar a instância
  2. Configurar permissões de acesso do usuário: os usuários do Azure precisam ter a função Proprietário de dados dos Gêmeos Digitais do Azure na instância dos Gêmeos Digitais do Azure para poder gerenciá-la, bem como os respectivos dados. Nesta etapa, como proprietário/administrador da assinatura do Azure você atribuirá essa função à pessoa que gerenciará sua instância dos Gêmeos Digitais do Azure. Pode ser você mesmo ou outra pessoa da sua organização.

Importante

Para realizar este artigo em sua totalidade e configurar completamente uma instância usável, você precisa de permissões para gerenciar os recursos e o acesso do usuário na assinatura do Azure. A primeira etapa pode ser concluída por qualquer pessoa que possa criar recursos na assinatura, mas a segunda etapa requer permissões de gerenciamento de acesso do usuário (ou a cooperação de alguém com essas permissões). Leia mais sobre isso na seção Pré-requisitos: permissões necessárias para a etapa de permissão de acesso do usuário.

Pré-requisitos

Configurar sessão da CLI

Para começar a trabalhar com os Gêmeos Digitais do Azure na CLI, faça logon e defina o contexto da CLI da sua assinatura para esta sessão. Execute estes comandos na janela da CLI:

az login
az account set --subscription "<your-Azure-subscription-ID>"

Dica

Você também pode usar o nome da sua assinatura em vez da ID no comando acima.

Se esta é a primeira vez que você usa essa assinatura com os Gêmeos Digitais do Azure, execute este comando para se registrar no namespace dos Gêmeos Digitais do Azure. (Se você não tiver certeza disso, não haverá problemas em executá-lo novamente mesmo que já tenha feito isso no passado.)

az provider register --namespace 'Microsoft.DigitalTwins'

Em seguida, você adicionará a Extensão de IoT do Microsoft Azure para a CLI do Azure para habilitar comandos para interagir com os Gêmeos Digitais do Azure e com outros serviços de IoT. Execute este comando para verificar se você tem a última versão da extensão:

az extension add --upgrade --name azure-iot

Agora você está pronto para trabalhar com os Gêmeos Digitais do Azure na CLI do Azure.

É possível verificar isso executando az dt --help a qualquer momento para ver uma lista dos comandos dos Gêmeos Digitais do Azure de nível superior que estão disponíveis.

Criar a instância dos Gêmeos Digitais do Azure

Nesta seção, você criará uma instância dos Gêmeos Digitais do Azure usando o comando da CLI. Você precisará fornecer:

  • O grupo de recursos em que a instância será implantada. Se você ainda não tiver um grupo de recursos existente em mente, poderá criar um agora com este comando: 
    az group create --location <region> --name <name-for-your-resource-group>
  • Uma região para executar a implantação. Para conferir quais regiões são compatíveis com os Gêmeos Digitais do Azure, acesse a página de produtos do Azure disponíveis por região.
  • Um nome para a instância. Caso sua assinatura tenha outra instância dos Gêmeos Digitais do Azure na região que já está usando o nome especificado, você receberá uma solicitação para escolher um nome diferente.

Use esses valores no seguinte comando az dt para criar a instância:

az dt create --dt-name <name-for-your-Azure-Digital-Twins-instance> --resource-group <your-resource-group> --location <region>

Há vários parâmetros opcionais que podem ser adicionados ao comando para especificar itens adicionais sobre o recurso durante a criação, incluindo a criação de uma identidade gerenciada para a instância ou a habilitação/desabilitação do acesso à rede pública. Para obter uma lista completa de parâmetros compatíveis, confira a documentação de referência az dt create.

Criar a instância com uma identidade gerenciada

Quando você habilita uma identidade gerenciada em sua instância do Azure Digital Twins, uma identidade é criada para ela na ID do Microsoft Entra. Essa identidade pode ser usada para autenticar em outros serviços. Você pode habilitar uma identidade gerenciada para uma instância dos Gêmeos Digitais do Azure enquanto a instância está sendo criada ou posteriormente em uma instância existente.

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

Comando de identidade atribuída pelo sistema

Para criar uma instância dos Gêmeos Digitais do Azure com a identidade atribuída pelo sistema habilitada, você pode adicionar um parâmetro --mi-system-assigned ao comando az dt create usado para criar a instância. (Para obter mais informações sobre o comando de criação, confira a documentação de referência ou as instruções gerais para configurar uma instância dos Gêmeos Digitais do Azure).

Para criar uma instância com uma identidade atribuída pelo sistema, adicione o parâmetro --mi-system-assigned da seguinte maneira:

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned

Comando de identidade atribuída pelo usuário

Para criar uma instância com uma identidade atribuída pelo usuário, forneça a ID de uma identidade atribuída pelo usuário existente usando o parâmetro --mi-user-assigned, desta forma:

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-user-assigned <user-assigned-identity-resource-ID>

Verificar êxito e coletar valores importantes

Caso a instância tenha sido criada com êxito, gerando informações sobre o recurso criado, o resultado será semelhante a este na CLI:

Screenshot of the Cloud Shell window with successful creation of a resource group and Azure Digital Twins instance in the Azure portal.

Anote o hostName da instância dos Gêmeos Digitais do Azure, bem como o name e o resourceGroup da saída. Esses valores são importantes, e talvez você precise usá-los ao continuar trabalhando com sua instância dos Gêmeos Digitais do Azure para configurar uma autenticação e os recursos do Azure relacionados. Caso outros usuários estejam executando uma programação na instância, esses valores deverão ser compartilhados com eles.

Dica

É possível conferir essas propriedades, juntamente com todas as propriedades de sua instância, a qualquer momento executando az dt show --dt-name <your-Azure-Digital-Twins-instance>.

Agora você tem uma instância dos Gêmeos Digitais do Azure pronta para uso. Depois, você concederá permissões adequadas ao usuário do Azure para gerenciar a instância.

Configurar as permissões de acesso do usuário

Os Gêmeos Digitais do Azure usam a ID do Microsoft Entra para controle de acesso baseado em função (RBAC). Isso significa que, antes que um usuário possa fazer chamadas de plano de dados para sua instância de Gêmeos Digitais do Azure, esse usuário precisa ser atribuído a uma função com as devidas permissões.

Para os Gêmeos Digitais do Azure, essa função é o Proprietário de dados dos Gêmeos Digitais do Azure. Você pode ler mais sobre atribuições de função e segurança em Segurança para soluções dos Gêmeos Digitais do Azure.

Observação

Essa função é diferente da função Proprietário da ID do Microsoft Entra, que também pode ser atribuída no escopo da instância do Gêmeos Digitais do Azure. Essas são duas funções de gerenciamento distintas, em que a função Proprietário não permite acesso aos recursos do plano de dados que são concedidos com a função Proprietário de Dados dos Gêmeos Digitais do Azure.

Esta seção mostrará como criar uma atribuição de função para um usuário em sua instância do Gêmeos Digitais do Azure, usando o email desse usuário no locatário do Microsoft Entra em sua assinatura do Azure. Dependendo da sua função na organização, você pode configurar essa permissão por conta própria ou defini-la em nome de outra pessoa que gerenciará a instância de Gêmeos Digitais do Azure.

Pré-requisitos: requisitos de permissão

Para poder concluir todas as etapas a seguir, você precisa ter uma função em sua assinatura que tenha as seguintes permissões:

  • Criar e gerenciar os recursos do Azure
  • 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 uma explicação completa das funções e permissões, incluindo quais permissões estão incluídas em outras funções, visite Funções do Azure, funções do Microsoft Entra e funções clássicas de administrador de assinatura na documentação do RBAC do Azure.

Para exibir sua função em sua assinatura, visite a página de assinaturas no portal do Azure (você pode usar este link ou procurar Assinaturas na barra de pesquisa do Portal). Procure o nome da assinatura que você está usando e exiba sua função na coluna Minha função:

Screenshot of the Subscriptions page in the Azure portal, showing user as an owner.

Se você descobrir que o valor é Colaborador ou outra função que não tenha as permissões necessárias descritas acima, você pode entrar em contato com o usuário em sua assinatura que tenha essas permissões (como um Proprietário de assinatura ou Administrador de conta) e proceder de uma das seguintes maneiras:

  • Solicite que eles concluam as etapas de atribuição de função em seu nome.
  • Solicite que eles elevem sua função na assinatura para que você tenha as permissões para continuar. Se isso é apropriado depende de sua organização e sua função dentro dela.

Atribuir a função

Para conceder a um usuário permissão para gerenciar uma instância dos Gêmeos Digitais do Azure, você deve atribuí-las à função de Proprietário de dados dos Gêmeos Digitais do Azure dentro da instância.

Use o comando a seguir para atribuir a função (ela deverá ser executada por um usuário com permissões suficientes na assinatura do Azure). O comando requer que você passe o nome principal do usuário na conta do Microsoft Entra para o usuário ao qual a função deve ser atribuída. Na maioria dos casos, esse valor corresponderá ao email do usuário na conta do Microsoft Entra.

az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<Azure-AD-user-principal-name-of-user-to-assign>" --role "Azure Digital Twins Data Owner"

O resultado desse comando mostrará informações geradas sobre uma atribuição de função criada para o usuário.

Observação

Caso esse comando retorne um erro indicando que a CLI não pode localizar o usuário nem a entidade de serviço no banco de dados de grafo:

Atribua a função usando a ID de objeto do usuário como alternativa. Isso poderá ocorrer no caso de usuários com MSAs (contas Microsoft pessoais).

Use a página do portal do Azure dos usuários do Microsoft Entra para selecionar a conta de usuário e abrir seus detalhes. Copie a ID de objeto do usuário:

Screenshot of the user page in Azure portal highlighting the GUID in the 'Object ID' field.

Depois, repita o comando da lista de atribuição de função usando a ID de objeto do usuário para o parâmetro assignee mostrado acima.

Verificar êxito

Uma maneira de verificar se você configurou com êxito a atribuição de função é exibir as atribuições de função para a instância dos Gêmeos Digitais do Azure no portal do Azure. Acesse seu Gêmeos Digitais do Azure de dados no portal do Azure. Para chegar lá, você pode pesquisá-lo na página de instâncias do Gêmeos Digitais do Azure ou pesquisar seu nome na barra de pesquisa do portal).

Em seguida, visualize todas as funções atribuídas em Controle de acesso (IAM) > Atribuições de funções. Sua atribuição de função deve aparecer na lista.

Screenshot of the role assignments for an Azure Digital Twins instance in the Azure portal.

Agora você tem uma instância dos Gêmeos Digitais do Azure pronta para uso, bem como atribuiu permissões para gerenciá-la.

Habilitar/desabilitar uma identidade gerenciada para a instância

Esta seção mostra como adicionar uma identidade gerenciada a uma instância dos Gêmeos Digitais do Azure que já existe. Você também pode desabilitar a identidade gerenciada em uma instância que já a tenha.

Use os comandos da CLI abaixo para o tipo de identidade gerenciada escolhido.

Comandos de identidade atribuída pelo sistema

O comando para habilitar a identidade atribuída pelo sistema para uma instância existente é o mesmo comando az dt create que é usado para criar uma nova instância com uma identidade atribuída pelo sistema. Em vez de fornecer um novo nome de uma instância para criar, você pode fornecer o nome de uma instância que já existe. Em seguida, adicione o parâmetro --mi-system-assigned.

az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned

Para desabilitar a identidade atribuída pelo sistema em uma instância em que ela está habilitada no momento, use o comando a seguir para definir --mi-system-assigned como false.

az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned false

Comandos de identidade atribuída pelo usuário

Para habilitar uma identidade atribuída pelo usuário em uma instância existente, forneça a ID de uma identidade atribuída pelo usuário existente no seguinte comando:

az dt identity assign --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>

Para desabilitar uma identidade atribuída pelo usuário em uma instância em que ela está habilitada no momento, forneça a ID da identidade no seguinte comando:

az dt identity remove --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>

Considerações sobre a desabilitação de identidades gerenciadas

É importante considerar os efeitos que quaisquer alterações na identidade ou nas respectivas funções podem ter nos recursos que a usam. Se você estiver usando identidades gerenciadas com seus pontos de extremidade dos Gêmeos Digitais do Azure ou para o histórico de dados e a identidade estiver desabilitada ou uma função necessária for removida dela, a conexão de ponto de extremidade ou histórico de dados poderá se tornar inacessível e o fluxo de eventos será interrompido.

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.

Próximas etapas

Teste chamadas individuais à API REST em sua instância usando comandos da CLI dos Gêmeos Digitais do Azure:

Como alternativa, confira de que modo conectar um aplicativo cliente à sua instância usando o código de autenticação: