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:

1. Skapa instansen.
2. 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 hanterar din Azure Digital Twins-instans. Den här personen kan vara dig själv eller någon annan i din organisation.

Förutsättningar

• Använd Bash-miljön i Azure Cloud Shell. Mer information finns i Komma igång med 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 kommandot az login . Slutför autentiseringsprocessen genom att följa stegen som visas i terminalen. Andra inloggningsalternativ finns i Autentisera till Azure 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 och hantera tillägg med Azure CLI.

  • Kör az version för att hitta den version och beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen, kör 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>"

Om du använder den här prenumerationen med Azure Digital Twins för första gången kör du följande kommando 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 körde den någon gång tidigare.)

az provider register --namespace 'Microsoft.DigitalTwins'

Sedan 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 verifiera den här statusen genom att köra az dt --help när som helst för att se en lista över de Azure Digital Twins-kommandon på toppen 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 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 implementeringen. 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 för 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 andra saker om resursen när du skapar den, inklusive att skapa en hanterad identitet för instansen eller aktivera/inaktivera åtkomst till offentliga nätverk. 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 följande CLI-kommando 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 skapade:

Observera Azure Digital Twins-instansens värdnamn, namn och resursgrupp 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 programmerar mot instansen bör du dela dessa värden med dem.

Nu är en Azure Digital Twins-instans klar. Därefter ger du rätt behörigheter för Azure-användare för att hantera det.

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.

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 hanterar 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 sidan Prenumerationer 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 krävs tidigare 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 har behörighet att fortsätta själv. Om den här begäran är lämplig kan bero 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. En användare med tillräcklig behörighet i Azure-prenumerationen måste köra kommandot. 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 resulterar i information om rolltilldelningen som skapades för användaren.

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 Portal. 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 > 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 tilldelats behörigheter för 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 följande CLI-kommandon 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:

• az dt reference
• Azure Digital Twins CLI-kommandouppsättning

Eller se hur du ansluter ett klientprogram till din instans med autentiseringskod:

• Skriva klientappens autentiseringskod