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:
- Het exemplaar maken
- 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 gaat beheren. Dit kan uzelf of iemand anders in uw organisatie zijn.
Belangrijk
Als u dit volledige artikel wilt voltooien en een bruikbaar exemplaar wilt instellen, hebt u machtigingen nodig om zowel resources als gebruikerstoegang in het Azure-abonnement te beheren. De eerste stap kan worden voltooid door iedereen die resources in het abonnement kan maken, maar de tweede stap vereist machtigingen voor gebruikerstoegangsbeheer (of de samenwerking van iemand met deze machtigingen). Meer informatie hierover vindt u in de sectie Vereisten: Vereiste machtigingen voor de machtigingsstap voor gebruikerstoegang.
Vereisten
Gebruik de Bash-omgeving in Azure Cloud Shell. Zie quickstart voor Bash in Azure Cloud Shell voor meer informatie.
Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. 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 Azure CLI met behulp van de opdracht az login. Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Raadpleeg Aanmelden bij Azure CLI voor aanvullende aanmeldingsopties.
Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor meer informatie over extensies.
Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om te upgraden 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>"
Fooi
U kunt ook de naam van uw abonnement in plaats van de ID gebruiken in de bovenstaande opdracht.
Als dit de eerste keer is dat u dit abonnement met Azure Digital Twins gebruikt, voert u deze opdracht uit om u te registreren bij de naamruimte van Azure Digital Twins. (Als u het niet zeker weet, kunt u de opdracht opnieuw uitvoeren, zelfs als u dit in het verleden een keer hebt gedaan.)
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 dit controleren door az dt --help op elk gewenst moment uit te voeren om een lijst weer te geven van de Azure Digital Twins-opdrachten op het hoogste niveau die beschikbaar zijn.
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 het exemplaar wordt geïmplementeerd. 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 exemplaar. Als uw abonnement een ander Azure Digital Twins-exemplaar heeft in de regio die al gebruikmaakt van de opgegeven naam, wordt u gevraagd een andere naam te kiezen.
Gebruik deze waarden in de volgende az dt-opdracht om het exemplaar 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 tijdens het maken extra dingen over uw resource op te geven, 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 maken 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 hoger op een bestaand exemplaar.
Gebruik de onderstaande 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 opdracht voor maken).
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 is gemaakt, ziet het resultaat in de CLI er ongeveer als volgt uit, waarbij informatie wordt uitgevoerd over de resource die u hebt gemaakt:
Noteer de hostNaam, naam en resourceGroup van het Azure Digital Twins-exemplaar uit de uitvoer. Deze waarden zijn allemaal belangrijk en u moet deze mogelijk gebruiken wanneer u met uw Azure Digital Twins-exemplaar blijft werken om verificatie en gerelateerde Azure-resources in te stellen. Als andere gebruikers met het exemplaar gaan programmeren, moet u deze waarden met hen delen.
Fooi
U kunt deze eigenschappen zien, samen met alle eigenschappen van uw exemplaar, op elk gewenst moment door deze uit te voeren az dt show --dt-name <your-Azure-Digital-Twins-instance>.
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 gegevensvlakaanroepen naar uw Azure Digital Twins-exemplaar kan aanroepen, die gebruiker een rol met de juiste machtigingen moet toewijzen.
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.
Notitie
Deze rol verschilt van de rol Eigenaar van Microsoft Entra-id, die ook kan worden toegewezen aan het bereik van het Azure Digital Twins-exemplaar. Dit zijn twee verschillende beheerrollen en eigenaar verleent geen toegang tot gegevensvlakfuncties die worden verleend met Azure Digital Twins-gegevenseigenaar.
In deze sectie ziet u hoe u een roltoewijzing maakt voor een gebruiker in uw Azure Digital Twins-exemplaar, met behulp van het e-mailadres 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 gaat beheren.
Vereisten: machtigingsvereisten
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 Gebruikerstoegang Beheer istrator 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 hierboven 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 om namens u de stappen voor roltoewijzing te voltooien.
- Vraag of ze uw rol voor het abonnement verhogen, zodat u over de machtigingen beschikt om uzelf voort te zetten. Of dit geschikt is, is afhankelijk van uw organisatie en uw rol hierin.
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 (moet worden uitgevoerd door een gebruiker met voldoende machtigingen in het Azure-abonnement). Voor de opdracht moet u de principal-naam van de gebruiker doorgeven aan het Microsoft Entra-account voor de gebruiker waaraan de rol moet worden toegewezen. In de meeste gevallen komt deze waarde overeen met het e-mailadres van de gebruiker in 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.
Notitie
Als met deze opdracht een fout wordt geretourneerd waarin wordt aangegeven dat de CLI geen gebruiker of service-principal kan vinden in de grafiekdatabase:
Wijs de rol toe met behulp van de object-id van de gebruiker. Dit kan gebeuren voor gebruikers met persoonlijke Microsoft-accounts (MSA's).
Gebruik de Azure Portal-pagina van Microsoft Entra-gebruikers om het gebruikersaccount te selecteren en de details ervan te openen. Kopieer de object-id van de gebruiker:
Herhaal vervolgens de opdracht lijst met roltoewijzingen met behulp van de object-id van de gebruiker voor de assignee bovenstaande parameter.
Controleren geslaagd
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. U kunt 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 Roltoewijzingen voor Toegangsbeheer (IAM>). Uw roltoewijzing moet worden weergegeven in de lijst.
U hebt nu een Azure Digital Twins-exemplaar dat klaar is voor gebruik en u hebt machtigingen toegewezen om het te beheren.
Beheerde identiteit voor het exemplaar in-/uitschakelen
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 ONDERSTAANDe 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 als er een benodigde 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 tot een uur duren voordat de levering van gebeurtenissen aan het eindpunt na deze wijziging wordt hervat.
Volgende stappen
Test afzonderlijke REST API-aanroepen op uw exemplaar met behulp van de Azure Digital Twins CLI-opdrachten:
U kunt ook zien hoe u een clienttoepassing verbindt met uw exemplaar met verificatiecode: