Nastavení instance a ověřování Služby Azure Digital Twins (CLI)
Tento článek popisuje postup nastavení nové instance služby Azure Digital Twins, včetně vytvoření instance a nastavení ověřování. Po dokončení tohoto článku budete mít instanci Azure Digital Twins připravenou začít s programováním.
Úplné nastavení nové instance služby Azure Digital Twins se skládá ze dvou částí:
- Vytvoření instance
- Nastavení oprávnění pro přístup uživatelů: Uživatelé Azure musí mít roli Vlastník dat Služby Azure Digital Twins v instanci Služby Azure Digital Twins, aby je mohli spravovat a její data. V tomto kroku přiřadíte tuto roli uživateli, který bude spravovat vaši instanci Azure Digital Twins, jako vlastník nebo správce předplatného Azure. Může to být sami nebo někdo jiný ve vaší organizaci.
Důležité
K dokončení tohoto úplného článku a úplnému nastavení použitelné instance potřebujete oprávnění ke správě prostředků i přístupu uživatelů k předplatnému Azure. První krok může dokončit každý, kdo může vytvářet prostředky v předplatném, ale druhý krok vyžaduje oprávnění ke správě přístupu uživatelů (nebo spolupráci někoho s těmito oprávněními). Další informace najdete v části Požadavky: Požadovaná oprávnění pro krok oprávnění uživatele.
Předpoklady
Použijte prostředí Bash v Azure Cloud Shellu. Další informace najdete v tématu Rychlý start pro Bash v Azure Cloud Shellu.
Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, nainstalujte Azure CLI. Pokud používáte Windows nebo macOS, zvažte spuštění Azure CLI v kontejneru Docker. Další informace najdete v tématu Jak spustit Azure CLI v kontejneru Dockeru.
Pokud používáte místní instalaci, přihlaste se k Azure CLI pomocí příkazu az login. Pokud chcete dokončit proces ověřování, postupujte podle kroků zobrazených na terminálu. Další možnosti přihlášení najdete v tématu Přihlášení pomocí Azure CLI.
Po zobrazení výzvy nainstalujte rozšíření Azure CLI při prvním použití. Další informace o rozšířeních najdete v tématu Využití rozšíření v Azure CLI.
Spuštěním příkazu az version zjistěte verzi a závislé knihovny, které jsou nainstalované. Pokud chcete upgradovat na nejnovější verzi, spusťte az upgrade.
Nastavení relace rozhraní příkazového řádku
Pokud chcete začít pracovat s Azure Digital Twins v rozhraní příkazového řádku, je první věc, kterou je potřeba udělat, přihlásit se a nastavit kontext rozhraní příkazového řádku pro vaše předplatné pro tuto relaci. V okně rozhraní příkazového řádku spusťte tyto příkazy:
az login
az account set --subscription "<your-Azure-subscription-ID>"
Tip
Název předplatného můžete použít také místo ID v příkazu výše.
Pokud jste toto předplatné použili s Azure Digital Twins poprvé, spusťte tento příkaz a zaregistrujte se v oboru názvů Azure Digital Twins. (Pokud si nejste jistí, můžete ho znovu spustit, i když jste to někdy udělali v minulosti.)
az provider register --namespace 'Microsoft.DigitalTwins'
Dále přidáte rozšíření Microsoft Azure IoT pro Azure CLI, které povolí příkazy pro interakci se službou Azure Digital Twins a dalšími službami IoT. Spuštěním tohoto příkazu se ujistěte, že máte nejnovější verzi rozšíření:
az extension add --upgrade --name azure-iot
Teď jste připraveni pracovat s Azure Digital Twins v Azure CLI.
Můžete to ověřit spuštěním az dt --help kdykoli a zobrazit seznam příkazů Azure Digital Twins nejvyšší úrovně, které jsou k dispozici.
Vytvoření instance Azure Digital Twins
V této části vytvoříte novou instanci služby Azure Digital Twins pomocí příkazu rozhraní příkazového řádku. Budete muset zadat:
- Skupina prostředků, ve které se instance nasadí. Pokud ještě nemáte existující skupinu prostředků, můžete ji vytvořit pomocí tohoto příkazu:
az group create --location <region> --name <name-for-your-resource-group> - Oblast pro nasazení. Pokud chcete zjistit, které oblasti podporují Azure Digital Twins, navštivte produkty Azure dostupné v jednotlivých oblastech.
- Název vaší instance. Pokud má vaše předplatné jinou instanci služby Azure Digital Twins v oblasti, která už používá zadaný název, zobrazí se výzva k výběru jiného názvu.
K vytvoření instance použijte tyto hodnoty v následujícím příkazu az dt:
az dt create --dt-name <name-for-your-Azure-Digital-Twins-instance> --resource-group <your-resource-group> --location <region>
Do příkazu je možné přidat několik volitelných parametrů, které určují další informace o vašem prostředku během vytváření, včetně vytvoření spravované identity pro instanci nebo povolení nebo zakázání přístupu k veřejné síti. Úplný seznam podporovaných parametrů najdete v referenční dokumentaci az dt create .
Vytvoření instance se spravovanou identitou
Když ve své instanci Azure Digital Twins povolíte spravovanou identitu , vytvoří se pro ni identita v Microsoft Entra ID. Tuto identitu pak můžete použít k ověření v jiných službách. Spravovanou identitu můžete povolit pro instanci služby Azure Digital Twins, když se instance vytváří, nebo později ve stávající instanci.
Pro zvolený typ spravované identity použijte následující příkaz rozhraní příkazového řádku.
Příkaz identity přiřazené systémem
Pokud chcete vytvořit instanci Azure Digital Twins s povolenou identitou přiřazenou systémem, můžete do az dt create příkazu, který se používá k vytvoření instance, přidat --mi-system-assigned parametr. (Další informace o příkazu pro vytvoření najdete v referenční dokumentaci nebo obecných pokynech k nastavení instance služby Azure Digital Twins).
Pokud chcete vytvořit instanci s identitou přiřazenou systémem, přidejte --mi-system-assigned parametr takto:
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned
Příkaz identity přiřazené uživatelem
Pokud chcete vytvořit instanci s identitou přiřazenou uživatelem, zadejte ID existující identity přiřazené uživatelem pomocí parametru--mi-user-assigned, například takto:
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-user-assigned <user-assigned-identity-resource-ID>
Ověření úspěchu a shromáždění důležitých hodnot
Pokud se instance úspěšně vytvořila, výsledek v rozhraní příkazového řádku vypadá přibližně takto:
Všimněte si názvu hostitele, názvu a skupiny prostředků instance Azure Digital Twins z výstupu. Tyto hodnoty jsou všechny důležité a při práci s instancí Azure Digital Twins je možná budete muset použít, abyste mohli nastavit ověřování a související prostředky Azure. Pokud budou ostatní uživatelé programovat na instanci, měli byste tyto hodnoty sdílet s nimi.
Tip
Tyto vlastnosti můžete kdykoli zobrazit spolu se všemi vlastnostmi vaší instance spuštěním az dt show --dt-name <your-Azure-Digital-Twins-instance>.
Teď máte připravenou instanci Azure Digital Twins. V dalším kroku udělíte příslušná uživatelská oprávnění Azure ke správě.
Nastavení uživatelských přístupových oprávnění
Azure Digital Twins používá Id Microsoft Entra pro řízení přístupu na základě role (RBAC). To znamená, že aby uživatel mohl volat rovinu dat do vaší instance služby Azure Digital Twins, musí být danému uživateli přiřazena role s odpovídajícími oprávněními.
Pro Azure Digital Twins je tato role vlastníkem dat Azure Digital Twins. Další informace o rolích a zabezpečení najdete v tématu Zabezpečení pro řešení Azure Digital Twins.
Poznámka:
Tato role se liší od role vlastníka ID Microsoft Entra, kterou je možné přiřadit také v oboru instance služby Azure Digital Twins. Jedná se o dvě odlišné role správy a vlastník neuděluje přístup k funkcím roviny dat uděleným u vlastníka dat Azure Digital Twins.
V této části se dozvíte, jak vytvořit přiřazení role pro uživatele v instanci služby Azure Digital Twins pomocí e-mailu daného uživatele v tenantovi Microsoft Entra ve vašem předplatném Azure. V závislosti na vaší roli ve vaší organizaci můžete toto oprávnění nastavit sami pro sebe nebo ho nastavit jménem někoho jiného, kdo bude spravovat instanci služby Azure Digital Twins.
Požadavky: Požadavky na oprávnění
Abyste mohli provést všechny následující kroky, musíte mít ve svém předplatném roli s následujícími oprávněními:
- Vytváření a správa prostředků Azure
- Správa přístupu uživatelů k prostředkům Azure (včetně udělení a delegování oprávnění)
Mezi běžné role, které splňují tento požadavek, patří vlastník, správce účtu nebo kombinace uživatelských přístupů Správa istrator a přispěvatel. Úplné vysvětlení rolí a oprávnění, včetně toho, která oprávnění jsou součástí jiných rolí, najdete v dokumentaci k Azure RBAC, rolím Azure, rolím Microsoft Entra a klasickým rolím správce předplatného.
Pokud chcete zobrazit svou roli ve svém předplatném, navštivte stránku předplatných na webu Azure Portal (můžete použít tento odkaz nebo vyhledat předplatná pomocí panelu hledání na portálu). Vyhledejte název předplatného, které používáte, a zobrazte ho ve sloupci Moje role :
Pokud zjistíte, že hodnota je Přispěvatel nebo jiná role, která nemá požadovaná oprávnění popsaná výše, můžete kontaktovat uživatele ve vašem předplatném, který má tato oprávnění (například vlastník předplatného nebo správce účtu), a pokračovat jedním z následujících způsobů:
- Požádejte je, aby vaším jménem dokončili kroky přiřazení role.
- Požádejte, aby zvýšili vaši roli v předplatném, abyste měli oprávnění k tomu, abyste mohli pokračovat sami. To, jestli je to vhodné, závisí na vaší organizaci a vaší roli v ní.
Přiřazení role
Pokud chcete uživateli udělit oprávnění ke správě instance Azure Digital Twins, musíte mu přiřadit roli Vlastník dat služby Azure Digital Twins v instanci.
Pomocí následujícího příkazu přiřaďte roli (musí ji spustit uživatel s dostatečnými oprávněními v předplatném Azure). Tento příkaz vyžaduje předání hlavního názvu uživatele v účtu Microsoft Entra pro uživatele, kterému má být přiřazena role. Ve většině případů bude tato hodnota odpovídat e-mailu uživatele na účtu 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"
Výsledkem tohoto příkazu jsou informace o přiřazení role vytvořené pro uživatele.
Poznámka:
Pokud tento příkaz vrátí chybu s informací, že rozhraní příkazového řádku nemůže najít uživatele nebo instanční objekt v grafové databázi:
Místo toho přiřaďte roli pomocí ID objektu uživatele. K tomu může dojít u uživatelů na osobních účtech Microsoft (MSA).
Na stránce webu Azure Portal uživatelů Microsoft Entra vyberte uživatelský účet a otevřete jeho podrobnosti. Zkopírujte ID objektu uživatele:
Potom opakujte příkaz seznamu přiřazení rolí pomocí ID objektu uživatele pro assignee výše uvedený parametr.
Ověření úspěchu
Jedním ze způsobů, jak zkontrolovat, jestli jste přiřazení role úspěšně nastavili, je zobrazit přiřazení rolí pro instanci služby Azure Digital Twins na webu Azure Portal. Na webu Azure Portal přejděte k vaší instanci Služby Azure Digital Twins. Abyste se tam dostali, můžete ho vyhledat na stránce instancí služby Azure Digital Twins nebo vyhledat jeho název na panelu hledání na portálu.
Pak si prohlédněte všechny jeho přiřazené role v části Přiřazení rolí řízení přístupu (IAM>). Vaše přiřazení role by se mělo zobrazit v seznamu.
Teď máte připravenou instanci Azure Digital Twins a máte přiřazená oprávnění ke správě.
Povolení nebo zakázání spravované identity pro instanci
V této části se dozvíte, jak přidat spravovanou identitu do instance Služby Azure Digital Twins, která už existuje. Spravovanou identitu můžete také zakázat v instanci, která ji už má.
Pro zvolený typ spravované identity použijte následující příkazy rozhraní příkazového řádku.
Příkazy identit přiřazené systémem
Příkaz k povolení identity přiřazené systémem pro existující instanci je stejný az dt create příkaz, který slouží k vytvoření nové instance s identitou přiřazenou systémem. Místo zadání nového názvu instance, kterou chcete vytvořit, můžete zadat název instance, která již existuje. Pak nezapomeňte přidat --mi-system-assigned parametr.
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned
Chcete-li zakázat identitu přiřazenou systémem v instanci, ve které je aktuálně povolená, použijte následující příkaz k nastavení --mi-system-assignedfalse.
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned false
Příkazy identity přiřazené uživatelem
Pokud chcete u existující instance povolit identitu přiřazenou uživatelem, zadejte ID existující identity přiřazené uživatelem v následujícím příkazu:
az dt identity assign --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
Pokud chcete zakázat identitu přiřazenou uživatelem v instanci, kde je aktuálně povolená, zadejte ID identity v následujícím příkazu:
az dt identity remove --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
Důležité informace o zákazu spravovaných identit
Je důležité vzít v úvahu účinky, které můžou mít všechny změny identity nebo jejích rolí na prostředky, které ji používají. Pokud používáte spravované identity s koncovými body služby Azure Digital Twins nebo pro historii dat a identita je zakázaná nebo se z ní odebere nezbytná role, může se koncový bod nebo připojení historie dat stát nedostupným a tok událostí se přeruší.
Pokud chcete dál používat koncový bod, který se nastavil se spravovanou identitou, která je teď zakázaná, musíte koncový bod odstranit a vytvořit ho znovu s jiným typem ověřování. Obnovení doručování událostí do koncového bodu po této změně může trvat až 1 hodinu.
Další kroky
Otestujte jednotlivá volání rozhraní REST API ve vaší instanci pomocí příkazů azure Digital Twins CLI:
Nebo se podívejte, jak připojit klientskou aplikaci k instanci pomocí ověřovacího kódu: