Configurar uma instância e autenticação (CLI) do Azure Digital Twins

Este artigo aborda as etapas para configurar uma nova instância do Azure Digital Twins, incluindo a criação da instância e a configuração da autenticação. Depois de concluir este artigo, você terá uma instância do Azure Digital Twins pronta para começar a programar.

A configuração completa para uma nova instância do Azure Digital Twins consiste em duas partes:

1. Criação da instância.
2. Configurando permissões de acesso de usuário: os usuários do Azure precisam ter a função de Proprietário de Dados dos Gêmeos Digitais do Azure na instância dos Gêmeos Digitais do Azure para poder gerenciá-la e seus dados. Nesta etapa, você, como proprietário/administrador da assinatura do Azure, atribui essa função à pessoa que gerencia sua instância do Azure Digital Twins. Essa pessoa pode ser você mesmo ou outra pessoa na sua organização.

Pré-requisitos

• Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Introdução ao 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 você estiver usando uma instalação local, entre na CLI do Azure usando 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 az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para atualizar para a versão mais recente, execute az upgrade.

Configurar sessão 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 estiver a utilizar esta subscrição com os Gêmeos Digitais do Azure pela primeira vez, execute o seguinte comando para se registar no espaço de nomes dos Gêmeos Digitais do Azure. (Se você não tiver certeza, não há problema em executá-lo novamente, mesmo que você o tenha executado em algum momento no passado.)

az provider register --namespace 'Microsoft.DigitalTwins'

Em seguida, adicione a Extensão IoT do Microsoft Azure para CLI do Azure para habilitar comandos para interagir com Gêmeos Digitais do Azure e outros serviços de IoT. Execute este comando para se certificar de que tem a versão mais recente 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 de nível superior do Azure Digital Twins que estão disponíveis.

Criar a instância do Azure Digital Twins

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

• Um grupo de recursos onde a instância é 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 a implantação. Para ver que regiões suportam os Gêmeos Digitais do Azure, visite os produtos do Azure disponíveis por região.
• Um nome para a sua instância. Se sua assinatura tiver outra instância do Azure Digital Twins 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/desativação do acesso à rede pública. Para obter uma lista completa dos parâmetros suportados, consulte 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 então ser usada para autenticar em outros serviços. Você pode habilitar uma identidade gerenciada para uma instância do Azure Digital Twins enquanto a instância está sendo criada ou posteriormente em uma instância existente.

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

Comando de identidade atribuído pelo sistema

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

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

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 ao usuário existente usando o --mi-user-assigned parâmetro, da seguinte forma:

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

Verificar o sucesso e coletar valores importantes

Se a instância foi criada com êxito, o resultado na CLI será mais ou menos assim, emitindo informações sobre o recurso que você criou:

Observe hostName, name e resourceGroup da instância do Azure Digital Twins na saída. Esses valores são todos importantes e você pode precisar usá-los enquanto continua trabalhando com sua instância do Azure Digital Twins, para configurar a autenticação e os recursos relacionados do Azure. Se outros usuários estiverem programando em relação à instância, você deverá compartilhar esses valores com eles.

Agora você tem uma instância do Azure Digital Twins pronta para uso. Em seguida, você concede as permissões de usuário apropriadas do Azure para gerenciá-lo.

Configurar permissões de acesso de usuário

O Azure Digital Twins usa o Microsoft Entra ID 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 do Azure Digital Twins, esse usuário precisa receber uma função com as permissões apropriadas para ela.

Para Azure Digital Twins, esta função é o Proprietário de Dados do Azure Digital Twins. Você pode ler mais sobre funções e segurança em Segurança para soluções de Gêmeos Digitais do Azure.

Esta seção mostra como criar uma atribuição de função para um usuário em sua instância do Azure Digital Twins, usando o email desse usuário no locatário do Microsoft Entra em sua assinatura do Azure. Dependendo da sua função na 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 recursos do Azure
• Gerenciar o acesso do usuário aos recursos do Azure (incluindo conceder e delegar permissões)

As funções comuns que atendem a esse requisito são Proprietário, Administrador de conta ou a combinação de Administrador de Acesso de Usuário e Colaborador. Para obter uma explicação completa das funções e permissões, incluindo quais permissões estão incluídas com outras funções, visite Funções do Azure, funções do Microsoft Entra e funções de administrador de assinatura clássicas na documentação do RBAC do Azure.

Para ver a sua função na sua subscrição, visite a página Subscrições no portal do Azure (pode utilizar esta ligação ou procurar Subscrições com a barra de pesquisa do portal). Encontre o nome da subscrição que está a utilizar e verifique o seu papel na coluna A minha função:

Se você achar que o valor é Colaborador ou outra função que não tenha as permissões necessárias descritas anteriormente, entre em contato com o usuário em sua assinatura que tenha essas permissões (como um Proprietário da assinatura ou Administrador da conta) e proceda 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 prosseguir sozinho. Se essa solicitação é apropriada pode depender de sua organização e de sua função dentro dela.

Atribuir a função

Para conceder permissão a um usuário para gerenciar uma instância do Azure Digital Twins, você deve atribuir a ele a função de Proprietário de Dados do Azure Digital Twins 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 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 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 que foi criada para o usuário.

Verificar o sucesso

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.

Vá para sua instância do Azure Digital Twins no portal do Azure. Para chegar lá, você pode procurá-lo na página de instâncias do Azure Digital Twins ou pesquisar seu nome na barra de pesquisa do portal.

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

Agora você tem uma instância do Azure Digital Twins pronta para uso e recebeu permissões para gerenciá-la.

Habilitar/desabilitar a identidade gerenciada para a instância

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

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

Comandos de identidade atribuídos pelo sistema

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

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

Para desabilitar a identidade atribuída ao sistema em uma instância em que ela esteja habilitada no momento, use o seguinte comando 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ídos 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 ao 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 esteja 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 para desabilitar identidades gerenciadas

É importante considerar os efeitos que qualquer alteração na identidade ou em suas funções pode ter sobre os recursos que a utilizam. Se estiver usando identidades geridas com os seus pontos finais do Azure Digital Twins ou para histórico de dados e a identidade estiver desativada, ou uma função necessária for removida, a conexão do ponto final ou o histórico de dados poderão ficar inacessíveis 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ê precisa 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 ao endpoint após esta alteração.

Próximos passos

Teste chamadas individuais da API REST em sua instância usando os comandos da CLI do Azure Digital Twins:

• Referência AZ DT
• Conjunto de comandos da CLI do Azure Digital Twins

Ou, veja como conectar um aplicativo cliente à sua instância com código de autenticação:

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