Konfigurera en Azure Digital Twins-instans och autentisering (CLI)
Den här artikeln beskriver stegen för att konfigurera en ny Azure Digital Twins-instans, inklusive att skapa instansen och konfigurera autentisering. När du har slutfört den här artikeln har du en Azure Digital Twins-instans redo att börja programmera mot.
Fullständig installation för en ny Azure Digital Twins-instans består av två delar:
- Skapa instansen
- Konfigurera behörigheter för användaråtkomst: Azure-användare måste ha rollen Azure Digital Twins-dataägare på Azure Digital Twins-instansen för att kunna hantera den och dess data. I det här steget tilldelar du som ägare/administratör för Azure-prenumerationen den här rollen till den person som ska hantera din Azure Digital Twins-instans. Detta kan vara dig själv eller någon annan i din organisation.
Viktigt!
För att slutföra den här fullständiga artikeln och helt konfigurera en användbar instans behöver du behörighet att hantera både resurser och användaråtkomst i Azure-prenumerationen. Det första steget kan slutföras av alla som kan skapa resurser i prenumerationen, men det andra steget kräver behörigheter för användaråtkomsthantering (eller samarbete mellan någon med dessa behörigheter). Du kan läsa mer om detta i avsnittet Krav: Nödvändiga behörigheter för användaråtkomstbehörighetssteget.
Förutsättningar
Använd Bash-miljön i Azure Cloud Shell. Mer information finns i Snabbstart för Bash i Azure Cloud Shell.
Om du föredrar att köra CLI-referenskommandon lokalt installerar du Azure CLI. Om du kör i Windows eller macOS kan du köra Azure CLI i en Docker-container. Mer information finns i Så här kör du Azure CLI i en Docker-container.
Om du använder en lokal installation loggar du in på Azure CLI med hjälp av kommandot az login. Slutför autentiseringsprocessen genom att följa stegen som visas i terminalen. Andra inloggningsalternativ finns i Logga in med Azure CLI.
När du uppmanas att installera Azure CLI-tillägget vid första användningen. Mer information om tillägg finns i Använda tillägg med Azure CLI.
Kör az version om du vill hitta versionen och de beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen kör du az upgrade.
Konfigurera CLI-session
För att börja arbeta med Azure Digital Twins i CLI är det första du behöver göra att logga in och ange CLI-kontexten till din prenumeration för den här sessionen. Kör följande kommandon i CLI-fönstret:
az login
az account set --subscription "<your-Azure-subscription-ID>"
Dricks
Du kan också använda ditt prenumerationsnamn i stället för ID:t i kommandot ovan.
Om det är första gången du använder den här prenumerationen med Azure Digital Twins kör du det här kommandot för att registrera dig med Azure Digital Twins-namnområdet. (Om du inte är säker är det ok att köra den igen även om du har gjort det någon gång tidigare.)
az provider register --namespace 'Microsoft.DigitalTwins'
Därefter lägger du till Microsoft Azure IoT-tillägget för Azure CLI för att aktivera kommandon för att interagera med Azure Digital Twins och andra IoT-tjänster. Kör det här kommandot för att kontrollera att du har den senaste versionen av tillägget:
az extension add --upgrade --name azure-iot
Nu är du redo att arbeta med Azure Digital Twins i Azure CLI.
Du kan kontrollera detta genom att köra az dt --help när som helst för att se en lista över de högsta Azure Digital Twins-kommandona som är tillgängliga.
Skapa Azure Digital Twins-instansen
I det här avsnittet skapar du en ny instans av Azure Digital Twins med hjälp av CLI-kommandot. Du måste ange:
- En resursgrupp där instansen ska distribueras. Om du inte redan har en befintlig resursgrupp i åtanke kan du skapa en nu med det här kommandot:
az group create --location <region> --name <name-for-your-resource-group> - En region för distributionen. Om du vill se vilka regioner som stöder Azure Digital Twins kan du besöka Azure-produkter som är tillgängliga per region.
- Ett namn på din instans. Om din prenumeration har en annan Azure Digital Twins-instans i regionen som redan använder det angivna namnet uppmanas du att välja ett annat namn.
Använd dessa värden i följande az dt-kommando för att skapa instansen:
az dt create --dt-name <name-for-your-Azure-Digital-Twins-instance> --resource-group <your-resource-group> --location <region>
Det finns flera valfria parametrar som kan läggas till i kommandot för att ange ytterligare saker om resursen när du skapar den, inklusive att skapa en hanterad identitet för instansen eller aktivera/inaktivera åtkomst till det offentliga nätverket. En fullständig lista över parametrar som stöds finns i referensdokumentationen az dt create .
Skapa instansen med en hanterad identitet
När du aktiverar en hanterad identitet på din Azure Digital Twins-instans skapas en identitet för den i Microsoft Entra-ID. Den identiteten kan sedan användas för att autentisera till andra tjänster. Du kan aktivera en hanterad identitet för en Azure Digital Twins-instans medan instansen skapas eller senare på en befintlig instans.
Använd CLI-kommandot nedan för din valda typ av hanterad identitet.
Systemtilldelad identitetskommando
Om du vill skapa en Azure Digital Twins-instans med systemtilldelad identitet aktiverad kan du lägga till en --mi-system-assigned parameter i az dt create kommandot som används för att skapa instansen. (Mer information om kommandot för att skapa finns i referensdokumentationen eller de allmänna instruktionerna för att konfigurera en Azure Digital Twins-instans).
Om du vill skapa en instans med en systemtilldelad identitet lägger du till parametern --mi-system-assigned så här:
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned
Användartilldelad identitetskommando
Om du vill skapa en instans med en användartilldelad identitet anger du ID:t för en befintlig användartilldelad identitet med hjälp av parametern --mi-user-assigned , så här:
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-user-assigned <user-assigned-identity-resource-ID>
Kontrollera att det lyckades och samla in viktiga värden
Om instansen har skapats ser resultatet i CLI ut ungefär så här och matar ut information om den resurs som du har skapat:
Observera Azure Digital Twins-instansens värdnamn, namn och resourceGroup från utdata. Dessa värden är alla viktiga och du kan behöva använda dem när du fortsätter att arbeta med din Azure Digital Twins-instans för att konfigurera autentisering och relaterade Azure-resurser. Om andra användare kommer att programmera mot instansen bör du dela dessa värden med dem.
Dricks
Du kan se dessa egenskaper, tillsammans med alla egenskaper för din instans, när som helst genom att köra az dt show --dt-name <your-Azure-Digital-Twins-instance>.
Nu är en Azure Digital Twins-instans klar. Därefter ger du rätt Azure-användarbehörighet för att hantera den.
Konfigurera behörigheter för användaråtkomst
Azure Digital Twins använder Microsoft Entra-ID för rollbaserad åtkomstkontroll (RBAC). Det innebär att innan en användare kan göra dataplansanrop till din Azure Digital Twins-instans måste användaren tilldelas en roll med lämpliga behörigheter för den.
För Azure Digital Twins är den här rollen Azure Digital Twins-dataägare. Du kan läsa mer om roller och säkerhet i Security for Azure Digital Twins-lösningar.
Kommentar
Den här rollen skiljer sig från rollen Ägare av Microsoft Entra-ID, som också kan tilldelas i omfånget för Azure Digital Twins-instansen. Det här är två distinkta hanteringsroller och ägaren beviljar inte åtkomst till dataplansfunktioner som beviljas med Azure Digital Twins Data Owner.
Det här avsnittet visar hur du skapar en rolltilldelning för en användare i din Azure Digital Twins-instans med hjälp av användarens e-post i Microsoft Entra-klientorganisationen i din Azure-prenumeration. Beroende på din roll i din organisation kan du konfigurera den här behörigheten själv eller konfigurera den åt någon annan som ska hantera Azure Digital Twins-instansen.
Krav: Behörighetskrav
För att kunna slutföra alla följande steg måste du ha en roll i din prenumeration som har följande behörigheter:
- Skapa och hantera Azure-resurser
- Hantera användaråtkomst till Azure-resurser (inklusive beviljande och delegering av behörigheter)
Vanliga roller som uppfyller detta krav är ägare, kontoadministratör eller kombinationen av administratör och deltagare för användaråtkomst. En fullständig förklaring av roller och behörigheter, inklusive vilka behörigheter som ingår i andra roller, finns i Azure-roller, Microsoft Entra-roller och klassiska prenumerationsadministratörsroller i Azure RBAC-dokumentationen.
Om du vill visa din roll i din prenumeration går du till prenumerationssidan i Azure-portalen (du kan använda den här länken eller leta efter prenumerationer med portalsökningsfältet ). Leta efter namnet på den prenumeration du använder och visa din roll för den i kolumnen Min roll :
Om du upptäcker att värdet är Deltagare, eller en annan roll som inte har de behörigheter som beskrivs ovan, kan du kontakta användaren i din prenumeration som har dessa behörigheter (till exempel en prenumerationsägare eller kontoadministratör) och fortsätta på något av följande sätt:
- Begär att de slutför rolltilldelningsstegen åt dig.
- Begär att de höjer din roll i prenumerationen så att du får behörighet att fortsätta själv. Om detta är lämpligt beror på din organisation och din roll i den.
Tilldela rollen
Om du vill ge en användare behörighet att hantera en Azure Digital Twins-instans måste du tilldela dem rollen Azure Digital Twins-dataägare i instansen.
Använd följande kommando för att tilldela rollen (måste köras av en användare med tillräcklig behörighet i Azure-prenumerationen). Kommandot kräver att du skickar in användarens huvudnamn på Microsoft Entra-kontot för den användare som ska tilldelas rollen. I de flesta fall matchar det här värdet användarens e-post på Microsoft Entra-kontot.
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"
Resultatet av det här kommandot matas ut information om rolltilldelningen som har skapats för användaren.
Kommentar
Om det här kommandot returnerar ett fel som säger att CLI inte kan hitta användaren eller tjänstens huvudnamn i grafdatabasen:
Tilldela rollen med hjälp av användarens objekt-ID i stället. Detta kan inträffa för användare på personliga Microsoft-konton (MSA).
Använd Sidan i Azure-portalen för Microsoft Entra-användare för att välja användarkontot och öppna dess information. Kopiera användarens objekt-ID:
Upprepa sedan kommandot för rolltilldelningslistan med hjälp av användarens objekt-ID för parametern assignee ovan.
Kontrollera att det har lyckats
Ett sätt att kontrollera att du har konfigurerat rolltilldelningen är att visa rolltilldelningarna för Azure Digital Twins-instansen i Azure-portalen. Gå till din Azure Digital Twins-instans i Azure-portalen. För att komma dit kan du leta upp den på sidan för Azure Digital Twins-instanser eller söka efter dess namn i portalens sökfält).
Visa sedan alla dess tilldelade roller under Rolltilldelningar för åtkomstkontroll (IAM). > Rolltilldelningen bör visas i listan.
Nu har du en Azure Digital Twins-instans som är redo att köras och har tilldelats behörighet att hantera den.
Aktivera/inaktivera hanterad identitet för instansen
Det här avsnittet visar hur du lägger till en hanterad identitet i en Azure Digital Twins-instans som redan finns. Du kan också inaktivera hanterad identitet på en instans som redan har den.
Använd CLI-kommandona nedan för din valda typ av hanterad identitet.
Systemtilldelade identitetskommandon
Kommandot för att aktivera en systemtilldelad identitet för en befintlig instans är samma az dt create kommando som används för att skapa en ny instans med en systemtilldelad identitet. I stället för att ange ett nytt namn på en instans som ska skapas kan du ange namnet på en instans som redan finns. Lägg sedan till parametern --mi-system-assigned .
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned
Om du vill inaktivera systemtilldelad identitet på en instans där den är aktiverad använder du följande kommando för att ange --mi-system-assigned till false.
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned false
Användartilldelade identitetskommandon
Om du vill aktivera en användartilldelad identitet på en befintlig instans anger du ID:t för en befintlig användartilldelad identitet i följande kommando:
az dt identity assign --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
Om du vill inaktivera en användartilldelad identitet på en instans där den för närvarande är aktiverad anger du identitetens ID i följande kommando:
az dt identity remove --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
Överväganden för att inaktivera hanterade identiteter
Det är viktigt att tänka på vilka effekter eventuella ändringar i identiteten eller dess roller kan ha på de resurser som använder den. Om du använder hanterade identiteter med dina Azure Digital Twins-slutpunkter eller för datahistorik och identiteten är inaktiverad, eller om en nödvändig roll tas bort från den, kan anslutningen till slutpunkten eller datahistoriken bli otillgänglig och händelseflödet avbryts.
Om du vill fortsätta använda en slutpunkt som har konfigurerats med en hanterad identitet som nu har inaktiverats måste du ta bort slutpunkten och återskapa den med en annan autentiseringstyp. Det kan ta upp till en timme innan händelser återupptar leveransen till slutpunkten efter den här ändringen.
Nästa steg
Testa enskilda REST API-anrop på din instans med hjälp av Azure Digital Twins CLI-kommandona:
Eller se hur du ansluter ett klientprogram till din instans med autentiseringskod: