Een Azure Digital Twins-exemplaar en -verificatie (CLI) instellen

In dit artikel worden de stappen beschreven voor het instellen van een nieuw Azure Digital Twins-exemplaar, waaronder het maken van het exemplaar en het instellen van verificatie. Nadat u dit artikel hebt voltooid, hebt u een Azure Digital Twins-exemplaar dat klaar is om te beginnen met programmeren.

Volledige installatie voor een nieuw Azure Digital Twins-exemplaar bestaat uit twee onderdelen:

1. Het exemplaar maken.
2. Machtigingen voor gebruikerstoegang instellen: Azure-gebruikers moeten beschikken over de rol Azure Digital Twins-gegevenseigenaar op het Azure Digital Twins-exemplaar om deze en de bijbehorende gegevens te kunnen beheren. In deze stap wijst u als eigenaar/beheerder van het Azure-abonnement deze rol toe aan de persoon die uw Azure Digital Twins-exemplaar beheert. Deze persoon kan uzelf of iemand anders in uw organisatie zijn.

Vereisten

• Gebruik de Bash-omgeving in Azure Cloud Shell. Zie Aan de slag met Azure Cloud Shell voor meer informatie.

  

• Als u liever CLI-referentieopdrachten lokaal uitvoert, installeert u de Azure CLI. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.

  • Als u een lokale installatie gebruikt, meldt u zich aan bij de Azure CLI met behulp van de opdracht az login . Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Zie Verifiëren bij Azure met behulp van Azure CLI voor andere aanmeldingsopties.

  • Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Zie Extensies gebruiken en beheren met de Azure CLI voor meer informatie over extensies.

  • Voer az version uit om de versie en afhankelijke bibliotheken te vinden die zijn geïnstalleerd. Voer az upgrade uit om een upgrade uit te voeren naar de nieuwste versie.

CLI-sessie instellen

Als u met Azure Digital Twins in de CLI wilt werken, moet u zich eerst aanmelden en de CLI-context instellen op uw abonnement voor deze sessie. Voer deze opdrachten uit in het CLI-venster:

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

Als u dit abonnement voor het eerst met Azure Digital Twins gebruikt, voert u de volgende opdracht uit om u te registreren bij de Azure Digital Twins-naamruimte. (Als u het niet zeker weet, kunt u het opnieuw uitvoeren, zelfs als u het ergens in het verleden hebt uitgevoerd.)

az provider register --namespace 'Microsoft.DigitalTwins'

Vervolgens voegt u de Microsoft Azure IoT-extensie voor Azure CLI toe om opdrachten in te schakelen voor interactie met Azure Digital Twins en andere IoT-services. Voer deze opdracht uit om te controleren of u de nieuwste versie van de extensie hebt:

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

U bent nu klaar om te werken met Azure Digital Twins in de Azure CLI.

U kunt deze status controleren door az dt --help op elk gewenst moment uit te voeren om een lijst van de beschikbare bovenliggende Azure Digital Twins-opdrachten te zien.

Het Azure Digital Twins-exemplaar maken

In deze sectie maakt u een nieuw exemplaar van Azure Digital Twins met behulp van de CLI-opdracht. U moet het volgende opgeven:

• Een resourcegroep waarin de instantie wordt uitgerold. Als u nog geen bestaande resourcegroep in gedachten hebt, kunt u er nu een maken met deze opdracht:

  az group create --location <region> --name <name-for-your-resource-group>
  

• Een regio voor de implementatie. Als u wilt zien welke regio's Ondersteuning bieden voor Azure Digital Twins, gaat u naar Azure-producten die beschikbaar zijn per regio.
• Een naam voor uw instantie. Als uw abonnement een ander Azure Digital Twins-exemplaar heeft in de regio die al de opgegeven naam gebruikt, wordt u gevraagd een andere naam te kiezen.

Gebruik deze waarden in de volgende az dt-opdracht om de instantie te maken:

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

Er zijn verschillende optionele parameters die kunnen worden toegevoegd aan de opdracht om andere dingen over uw resource op te geven tijdens het maken, waaronder het maken van een beheerde identiteit voor het exemplaar of het in- of uitschakelen van openbare netwerktoegang. Zie de referentiedocumentatie az dt create voor een volledige lijst met ondersteunde parameters.

Het exemplaar creëren met een beheerde identiteit

Wanneer u een beheerde identiteit inschakelt op uw Azure Digital Twins-exemplaar, wordt er een identiteit voor gemaakt in Microsoft Entra-id. Deze identiteit kan vervolgens worden gebruikt om te verifiëren bij andere services. U kunt een beheerde identiteit inschakelen voor een Azure Digital Twins-exemplaar terwijl het exemplaar wordt gemaakt of later bij een bestaand exemplaar.

Gebruik de volgende CLI-opdracht voor het gekozen type beheerde identiteit.

Door het systeem toegewezen identiteit opdracht

Als u een Azure Digital Twins-exemplaar wilt maken waarvoor door het systeem toegewezen identiteit is ingeschakeld, kunt u een --mi-system-assigned parameter toevoegen aan de az dt create opdracht die wordt gebruikt om het exemplaar te maken. (Zie de referentiedocumentatie of de algemene instructies voor het instellen van een Azure Digital Twins-exemplaar voor meer informatie over de aanmaakopdracht).

Als u een exemplaar wilt maken met een door het systeem toegewezen identiteit, voegt u de --mi-system-assigned parameter als volgt toe:

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

Door de gebruiker toegewezen identiteit opdracht

Als u een exemplaar wilt maken met een door de gebruiker toegewezen identiteit, geeft u de id op van een bestaande door de gebruiker toegewezen identiteit met behulp van de --mi-user-assigned parameter, zoals deze:

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

Succes controleren en belangrijke waarden verzamelen

Als het exemplaar succesvol is gemaakt, ziet het resultaat in de CLI er ongeveer als volgt uit, met informatie over de resource die u hebt aangemaakt:

Let op de hostNaam, naam en resourceGroup van het Azure Digital Twins-exemplaar in de uitvoer. Deze waarden zijn allemaal belangrijk en u moet deze mogelijk gebruiken wanneer u doorgaat met uw Azure Digital Twins-exemplaar om verificatie en gerelateerde Azure-resources in te stellen. Als andere gebruikers tegen de instantie programmeren, moet u deze waarden met hen delen.

U hebt nu een Azure Digital Twins-exemplaar dat klaar is voor gebruik. Vervolgens geeft u de juiste Azure-gebruikersmachtigingen om deze te beheren.

Machtigingen voor gebruikerstoegang instellen

Azure Digital Twins maakt gebruik van Microsoft Entra ID voor op rollen gebaseerd toegangsbeheer (RBAC). Dit betekent dat voordat een gebruiker datavlak-aanroepen kan maken naar uw Azure Digital Twins-exemplaar, die gebruiker moet worden toegewezen aan een rol met de juiste machtigingen.

Voor Azure Digital Twins is deze rol Azure Digital Twins-gegevenseigenaar. Meer informatie over rollen en beveiliging vindt u in Security for Azure Digital Twins-oplossingen.

In deze sectie wordt beschreven hoe u een roltoewijzing maakt voor een gebruiker in uw Azure Digital Twins-exemplaar, met behulp van de e-mail van die gebruiker in de Microsoft Entra-tenant in uw Azure-abonnement. Afhankelijk van uw rol in uw organisatie kunt u deze machtiging voor uzelf instellen of instellen namens iemand anders die het Azure Digital Twins-exemplaar beheert.

Vereisten: toestemmingsvereisten

Als u alle volgende stappen wilt uitvoeren, moet u een rol hebben in uw abonnement met de volgende machtigingen:

• Azure-resources maken en beheren
• Gebruikerstoegang tot Azure-resources beheren (inclusief het verlenen en delegeren van machtigingen)

Algemene rollen die aan deze vereiste voldoen, zijn Eigenaar, Accountbeheerder of de combinatie van Beheerder voor gebruikerstoegang en Inzender. Voor een volledige uitleg van rollen en machtigingen, waaronder welke machtigingen zijn opgenomen in andere rollen, gaat u naar Azure-rollen, Microsoft Entra-rollen en klassieke abonnementsbeheerdersrollen in de Documentatie van Azure RBAC.

Als u uw rol in uw abonnement wilt weergeven, gaat u naar de pagina Abonnementen in Azure Portal (u kunt deze koppeling gebruiken of zoeken naar abonnementen met de zoekbalk van de portal). Zoek de naam van het abonnement dat u gebruikt en bekijk uw rol hiervoor in de kolom Mijn rol :

Als u merkt dat de waarde Inzender is of een andere rol die niet beschikt over de vereiste machtigingen die eerder zijn beschreven, kunt u contact opnemen met de gebruiker in uw abonnement met deze machtigingen (zoals een abonnementseigenaar of accountbeheerder) en op een van de volgende manieren doorgaan:

• Vraag hen om de stappen voor roltoewijzing namens u te voltooien.
• Vraag of ze uw rol voor het abonnement verhogen, zodat u de bevoegdheden heeft om zelf door te gaan. Of deze aanvraag geschikt is, kan afhankelijk zijn van uw organisatie en uw rol daarin.

De rol toewijzen

Als u een gebruiker toestemming wilt geven om een Azure Digital Twins-exemplaar te beheren, moet u deze de rol Azure Digital Twins-gegevenseigenaar binnen het exemplaar toewijzen.

Gebruik de volgende opdracht om de rol toe te wijzen. Een gebruiker met voldoende machtigingen in het Azure-abonnement moet de opdracht uitvoeren. Voor de opdracht moet u de gebruikersnaam van de belangrijkste gebruiker doorgeven aan het Microsoft Entra-account voor de gebruiker aan wie de rol moet worden toegewezen. In de meeste gevallen komt deze waarde overeen met het e-mailadres van de gebruiker op het Microsoft Entra-account.

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"

Het resultaat van deze opdracht bevat informatie over de roltoewijzing die is gemaakt voor de gebruiker.

Verifieer succes

Een manier om te controleren of u de roltoewijzing hebt ingesteld, is door de roltoewijzingen voor het Azure Digital Twins-exemplaar in Azure Portal weer te geven.

Ga naar uw Azure Digital Twins-exemplaar in Azure Portal. Hiertoe kunt u deze opzoeken op de pagina van Azure Digital Twins-exemplaren of de naam ervan doorzoeken in de zoekbalk van de portal.

Bekijk vervolgens alle toegewezen rollen onder > (IAM). Uw roltoewijzing moet worden weergegeven in de lijst.

U hebt nu een Azure Digital Twins-exemplaar dat klaar is voor gebruik en toegewezen machtigingen om het te beheren.

In-/uitschakelen beheerde identiteit voor de instantie

In deze sectie wordt beschreven hoe u een beheerde identiteit toevoegt aan een Azure Digital Twins-exemplaar dat al bestaat. U kunt ook beheerde identiteit uitschakelen voor een exemplaar dat deze al heeft.

Gebruik de volgende CLI-opdrachten voor het gekozen type beheerde identiteit.

Door het systeem toegewezen identiteitsopdrachten

De opdracht voor het inschakelen van een door het systeem toegewezen identiteit voor een bestaand exemplaar is dezelfde az dt create opdracht die wordt gebruikt voor het maken van een nieuw exemplaar met een door het systeem toegewezen identiteit. In plaats van een nieuwe naam op te geven van een exemplaar dat u wilt maken, kunt u de naam opgeven van een exemplaar dat al bestaat. Zorg er vervolgens voor dat u de --mi-system-assigned parameter toevoegt.

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

Als u door het systeem toegewezen identiteit wilt uitschakelen voor een exemplaar waarop deze momenteel is ingeschakeld, gebruikt u de volgende opdracht om in te stellen --mi-system-assigned op false.

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

Door de gebruiker toegewezen identiteitsopdrachten

Als u een door de gebruiker toegewezen identiteit wilt inschakelen voor een bestaand exemplaar, geeft u de id op van een bestaande door de gebruiker toegewezen identiteit in de volgende opdracht:

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

Als u een door de gebruiker toegewezen identiteit wilt uitschakelen op een exemplaar waarvoor deze momenteel is ingeschakeld, geeft u de id van de identiteit op in de volgende opdracht:

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

Overwegingen voor het uitschakelen van beheerde identiteiten

Het is belangrijk om rekening te houden met de effecten die wijzigingen in de identiteit of de bijbehorende rollen kunnen hebben op de resources die deze gebruiken. Als u beheerde identiteiten gebruikt met uw Azure Digital Twins-eindpunten of voor gegevensgeschiedenis en de identiteit is uitgeschakeld, of een vereiste rol wordt verwijderd, kan het eindpunt of de gegevensgeschiedenisverbinding ontoegankelijk worden en wordt de stroom van gebeurtenissen onderbroken.

Als u een eindpunt wilt blijven gebruiken dat is ingesteld met een beheerde identiteit die nu is uitgeschakeld, moet u het eindpunt verwijderen en opnieuw maken met een ander verificatietype. Het kan een uur duren voordat gebeurtenissen na deze wijziging de levering aan het eindpunt hervatten.

Volgende stappen

Test afzonderlijke REST API-aanroepen op uw exemplaar met behulp van de Azure Digital Twins CLI-opdrachten:

• az dt reference
• Azure Digital Twins CLI-opdrachtenset

U kunt ook zien hoe u een clienttoepassing verbindt met uw exemplaar met verificatiecode:

• Verificatiecode voor client-apps schrijven