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:
- Criando a instância
- 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, atribuirá essa função à pessoa que gerenciará sua instância do Azure Digital Twins. Pode ser você mesmo ou outra pessoa na sua organização.
Importante
Para concluir este artigo completo e configurar completamente uma instância utilizável, você precisa de permissões para gerenciar recursos e acesso de 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). Você pode ler 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
Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no 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 Entrar com a CLI do Azure.
Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o 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.
Configurar sessão CLI
Para começar a trabalhar com os Gêmeos Digitais do Azure na CLI, a primeira coisa a fazer é fazer logon 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>"
Gorjeta
Também pode utilizar o nome da sua subscrição em vez do ID no comando acima.
Se esta for a primeira vez que você usa essa assinatura com os Gêmeos Digitais do Azure, execute este comando para se registrar com o namespace Gêmeos Digitais do Azure. (Se você não tiver certeza, não há problema em executá-lo novamente, mesmo que você já tenha feito isso em algum momento no passado.)
az provider register --namespace 'Microsoft.DigitalTwins'
Em seguida, você adicionará 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 isso 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ê criará uma nova instância dos Gêmeos Digitais do Azure usando o comando CLI. Terá de fornecer:
- Um grupo de recursos onde 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 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 coisas adicionais 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 comando CLI abaixo 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.
Gorjeta
Você pode ver essas propriedades, juntamente com todas as propriedades da sua instância, a qualquer momento executando az dt show --dt-name <your-Azure-Digital-Twins-instance>.
Agora você tem uma instância do Azure Digital Twins pronta para uso. Em seguida, você dará as permissões de usuário do Azure apropriadas 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 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 funções e segurança em Segurança para soluções de Gêmeos Digitais do Azure.
Nota
Essa função é diferente da função de Proprietário do ID do Microsoft Entra, que também pode ser atribuída no escopo da instância do Azure Digital Twins. Essas são duas funções de gerenciamento distintas e o Proprietário não concede acesso aos recursos do plano de dados concedidos com o Proprietário de Dados do Azure Digital Twins.
Esta seção mostrará 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 gerenciará 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 de subscrições no portal do Azure (pode utilizar esta ligação ou procurar Subscrições com a barra de pesquisa do portal). Procure o nome da subscrição que está a utilizar e veja a sua função 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 acima, 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. Se isso é apropriado depende da sua organização e do seu papel 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 (deve ser executado 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 é a saída de informações sobre a atribuição de função que foi criada para o usuário.
Nota
Se esse comando retornar um erro dizendo que a CLI não pode encontrar o usuário ou a entidade de serviço no banco de dados do gráfico:
Em vez disso, atribua a função usando a ID de objeto do usuário. Isso pode acontecer para usuários em contas pessoais da Microsoft (MSAs).
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 do objeto do usuário:
Em seguida, repita o comando role assignment list usando a ID de objeto do usuário para o assignee parâmetro acima.
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, exiba todas as funções atribuídas em Atribuições de função de controle de acesso (IAM). > Sua atribuição de função deve aparecer na lista.
Agora você tem uma instância do Azure Digital Twins pronta para uso e atribuiu 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 comandos da CLI abaixo 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 aosistema. 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 você estiver usando identidades gerenciadas com seus pontos de extremidade do Azure Digital Twins ou para o histórico de dados e a identidade estiver desabilitada ou uma função necessária for removida dele, a conexão de ponto de extremidade ou histórico de dados poderá ficar inacessível e o fluxo de eventos será interrompido.
Para continuar a utilizar um ponto final que foi configurado com uma identidade gerida que está, agora, desativada, terá de eliminar o ponto final e recriá-lo com um tipo de autenticação diferente. Os eventos podem demorar até uma hora a retomar a entrega para o ponto final 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:
Ou, veja como conectar um aplicativo cliente à sua instância com código de autenticação: