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

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. Criando 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, você como proprietário/administrador da assinatura do Azure atribui essa função à pessoa que gerencia sua instância dos Gêmeos Digitais do Azure. Essa pessoa pode ser você ou outra pessoa em sua organização.

Pré-requisitos

• 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.

Configurar sessão da CLI

Para começar a trabalhar com os Gêmeos Digitais do Azure na CLI, a primeira coisa a fazer é entrar e definir o contexto da CLI para sua assinatura para esta sessão. Execute estes comandos na janela da CLI:

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

Se você estiver usando essa assinatura com os Gêmeos Digitais do Azure pela primeira vez, execute o comando a seguir para se registrar no namespace dos Gêmeos Digitais do Azure. (Se você não tiver certeza, não há problema em executá-lo novamente, mesmo que você já o tenha executado em algum momento do passado.)

az provider register --namespace 'Microsoft.DigitalTwins'

Em seguida, adicione 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 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.

Você pode verificar esse status executando az dt --help a qualquer momento para ver uma lista dos comandos dos Gêmeos Digitais do Azure de nível superior disponíveis.

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

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

• Um grupo de recursos onde a instância está 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. Se sua assinatura tiver outra instância dos Gêmeos Digitais do Azure na região que já está usando o nome especificado, você será solicitado a 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 outras coisas sobre seu 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 dos Gêmeos Digitais do Azure, 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 a seguir 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

Se a instância tiver sido criada com êxito, o resultado na CLI será semelhante a este, gerando informações sobre o recurso que você criou:

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 todos importantes e talvez seja necessário usá-los à medida que você continua trabalhando com sua instância dos Gêmeos Digitais do Azure, para configurar a autenticação e os recursos relacionados do Azure. Se outros usuários estiverem programando contra a instância, você deverá compartilhar esses valores com eles.

Agora você tem uma instância dos Gêmeos Digitais do Azure pronta para uso. Em seguida, você fornece as permissões de usuário apropriadas do Azure para gerenciá-lo.

Configurar as permissões de acesso do usuário

O serviço de Gêmeos Digitais do Azure usa o Microsoft Entra ID para RBAC (controle de acesso baseado em função). 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.

Esta seção mostra como criar uma atribuição de função para um usuário na sua instância de Gêmeos Digitais do Azure, usando o email desse usuário no locatário do Microsoft Entra na sua assinatura do Azure. Dependendo de sua função em sua organização, você pode configurar essa permissão para si mesmo ou configurá-la em nome de outra pessoa que gerencia a instância dos 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 ver sua função na assinatura, acesse a página Assinaturas no portal do Azure (use este link ou procure Assinaturas na barra de pesquisa do portal). Procure o nome da assinatura que você está usando e veja a função dele na coluna Minha função:

Se o valor for Colaborador ou outra função que não tenha as permissões necessárias descritas anteriormente, entre em contato com o usuário na assinatura que tem essas permissões (como um Proprietário da assinatura ou um Administrador da conta) e realize uma das seguintes ações:

• Solicite que eles concluam as etapas de atribuição de função em seu nome.
• Solicite que as permissões na sua função na assinatura sejam elevadas para que você tenha as permissões necessárias para continuar por conta própria. Essa solicitação pode não ser adequada dependendo da organização e da sua função nela.

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. Um usuário com permissões suficientes na assinatura do Azure deve executar o comando. O comando exige que você passe o nome UPN na conta do Microsoft Entra para o usuário que deve receber a função. Na maioria dos casos, esse valor corresponde 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 são informações geradas sobre a atribuição de função criada para o usuário.

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 isso, pesquise-a na página de instâncias dos Gêmeos Digitais do Azure ou pesquise o nome dela 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.

Agora você tem uma instância dos Gêmeos Digitais do Azure pronta para uso. Além disso, você 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 a seguir 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ê está usando identidades gerenciadas com os pontos de extremidade dos Gêmeos Digitais do Azure ou para o histórico de dados e a identidade está desabilitada ou uma função necessária foi removida dela, a conexão do ponto de extremidade ou do histórico de dados pode se tornar inacessível e o fluxo de eventos pode ser interrompido.

Para continuar usando um ponto de extremidade que foi configurado com uma identidade gerenciada que agora foi desabilitada, você precisa excluir o ponto de extremidade e criá-lo novamente 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.

Próximas etapas

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

• az dt reference
• Conjunto de 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:

• Escrever código de autenticação de aplicativo cliente