Konfigurowanie wystąpienia i uwierzytelniania usługi Azure Digital Twins (interfejs wiersza polecenia)
W tym artykule opisano kroki konfigurowania nowego wystąpienia usługi Azure Digital Twins, w tym tworzenia wystąpienia i konfigurowania uwierzytelniania. Po ukończeniu tego artykułu będziesz mieć wystąpienie usługi Azure Digital Twins gotowe do rozpoczęcia programowania.
Pełna konfiguracja nowego wystąpienia usługi Azure Digital Twins składa się z dwóch części:
- Tworzenie wystąpienia
- Konfigurowanie uprawnień dostępu użytkowników: użytkownicy platformy Azure muszą mieć rolę właściciela danych usługi Azure Digital Twins w wystąpieniu usługi Azure Digital Twins, aby móc zarządzać nim i jego danymi. W tym kroku jako właściciel/administrator subskrypcji platformy Azure przypiszesz tę rolę osobie, która będzie zarządzać wystąpieniem usługi Azure Digital Twins. Może to być ty lub ktoś inny w twojej organizacji.
Ważne
Aby ukończyć ten pełny artykuł i całkowicie skonfigurować wystąpienie do użytku, musisz mieć uprawnienia do zarządzania zarówno zasobami, jak i dostępem użytkowników w subskrypcji platformy Azure. Pierwszym krokiem może być każda osoba, która może tworzyć zasoby w ramach subskrypcji, ale drugi krok wymaga uprawnień do zarządzania dostępem użytkowników (lub współpracy kogoś z tymi uprawnieniami). Więcej informacji na ten temat można uzyskać w sekcji Wymagania wstępne: wymagane uprawnienia dla kroku uprawnień dostępu użytkownika.
Wymagania wstępne
Użyj środowiska powłoki Bash w usłudze Azure Cloud Shell. Aby uzyskać więcej informacji, zobacz Szybki start dotyczący powłoki Bash w usłudze Azure Cloud Shell.
Jeśli wolisz uruchamiać polecenia referencyjne interfejsu wiersza polecenia lokalnie, zainstaluj interfejs wiersza polecenia platformy Azure. Jeśli korzystasz z systemu Windows lub macOS, rozważ uruchomienie interfejsu wiersza polecenia platformy Azure w kontenerze Docker. Aby uzyskać więcej informacji, zobacz Jak uruchomić interfejs wiersza polecenia platformy Azure w kontenerze platformy Docker.
Jeśli korzystasz z instalacji lokalnej, zaloguj się do interfejsu wiersza polecenia platformy Azure za pomocą polecenia az login. Aby ukończyć proces uwierzytelniania, wykonaj kroki wyświetlane w terminalu. Aby uzyskać inne opcje logowania, zobacz Logowanie się przy użyciu interfejsu wiersza polecenia platformy Azure.
Po wyświetleniu monitu zainstaluj rozszerzenie interfejsu wiersza polecenia platformy Azure podczas pierwszego użycia. Aby uzyskać więcej informacji na temat rozszerzeń, zobacz Korzystanie z rozszerzeń w interfejsie wiersza polecenia platformy Azure.
Uruchom polecenie az version, aby znaleźć zainstalowane wersje i biblioteki zależne. Aby uaktualnić do najnowszej wersji, uruchom polecenie az upgrade.
Konfigurowanie sesji interfejsu wiersza polecenia
Aby rozpocząć pracę z usługą Azure Digital Twins w interfejsie wiersza polecenia, najpierw należy się zalogować i ustawić kontekst interfejsu wiersza polecenia na subskrypcję dla tej sesji. Uruchom następujące polecenia w oknie interfejsu wiersza polecenia:
az login
az account set --subscription "<your-Azure-subscription-ID>"
Napiwek
Możesz również użyć nazwy subskrypcji zamiast identyfikatora w powyższym poleceniu.
Jeśli po raz pierwszy użyto tej subskrypcji z usługą Azure Digital Twins, uruchom to polecenie, aby zarejestrować się w przestrzeni nazw usługi Azure Digital Twins. (Jeśli nie masz pewności, możesz uruchomić go ponownie, nawet jeśli zrobiłeś to kiedyś w przeszłości).
az provider register --namespace 'Microsoft.DigitalTwins'
Następnie dodasz rozszerzenie Microsoft Azure IoT dla interfejsu wiersza polecenia platformy Azure, aby umożliwić interakcję z usługą Azure Digital Twins i innymi usługami IoT. Uruchom to polecenie, aby upewnić się, że masz najnowszą wersję rozszerzenia:
az extension add --upgrade --name azure-iot
Teraz możesz przystąpić do pracy z usługą Azure Digital Twins w interfejsie wiersza polecenia platformy Azure.
Możesz to sprawdzić, uruchamiając polecenie az dt --help w dowolnym momencie, aby wyświetlić listę dostępnych poleceń usługi Azure Digital Twins najwyższego poziomu.
Tworzenie wystąpienia usługi Azure Digital Twins
W tej sekcji utworzysz nowe wystąpienie usługi Azure Digital Twins przy użyciu polecenia interfejsu wiersza polecenia. Należy podać następujące elementy:
- Grupa zasobów, w której zostanie wdrożone wystąpienie. Jeśli nie masz jeszcze istniejącej grupy zasobów, możesz teraz utworzyć tę grupę za pomocą tego polecenia:
az group create --location <region> --name <name-for-your-resource-group> - Region wdrożenia. Aby zobaczyć, jakie regiony obsługują usługę Azure Digital Twins, odwiedź stronę Dostępność produktów platformy Azure według regionów.
- Nazwa wystąpienia. Jeśli Twoja subskrypcja ma inne wystąpienie usługi Azure Digital Twins w regionie, w którym jest już używana określona nazwa, zostanie wyświetlony monit o wybranie innej nazwy.
Użyj tych wartości w następującym poleceniu az dt, aby utworzyć wystąpienie:
az dt create --dt-name <name-for-your-Azure-Digital-Twins-instance> --resource-group <your-resource-group> --location <region>
Istnieje kilka opcjonalnych parametrów, które można dodać do polecenia, aby określić dodatkowe elementy dotyczące zasobu podczas tworzenia, w tym tworzenie tożsamości zarządzanej dla wystąpienia lub włączanie/wyłączanie dostępu do sieci publicznej. Aby uzyskać pełną listę obsługiwanych parametrów, zobacz dokumentację az dt create reference.
Tworzenie wystąpienia przy użyciu tożsamości zarządzanej
Po włączeniu tożsamości zarządzanej w wystąpieniu usługi Azure Digital Twins zostanie utworzona tożsamość w usłudze Microsoft Entra ID. Ta tożsamość może być następnie używana do uwierzytelniania w innych usługach. Tożsamość zarządzaną dla wystąpienia usługi Azure Digital Twins można włączyć podczas tworzenia wystąpienia lub nowszego wystąpienia.
Użyj poniższego polecenia interfejsu wiersza polecenia dla wybranego typu tożsamości zarządzanej.
Polecenie tożsamości przypisanej przez system
Aby utworzyć wystąpienie usługi Azure Digital Twins z włączoną tożsamością przypisaną przez system, możesz dodać --mi-system-assigned parametr do az dt create polecenia użytego do utworzenia wystąpienia. (Aby uzyskać więcej informacji na temat polecenia tworzenia, zobacz dokumentację referencyjną lub ogólne instrukcje dotyczące konfigurowania wystąpienia usługi Azure Digital Twins).
Aby utworzyć wystąpienie z tożsamością przypisaną przez system, dodaj parametr podobny do następującego --mi-system-assigned :
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned
Polecenie tożsamości przypisanej przez użytkownika
Aby utworzyć wystąpienie z tożsamością przypisaną przez użytkownika, podaj identyfikator istniejącej tożsamości przypisanej przez użytkownika przy użyciu parametru --mi-user-assigned , w następujący sposób:
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-user-assigned <user-assigned-identity-resource-ID>
Weryfikowanie powodzenia i zbieranie ważnych wartości
Jeśli wystąpienie zostało utworzone pomyślnie, wynik interfejsu wiersza polecenia wygląda mniej więcej tak, wyświetlając informacje o utworzonym zasobie:
Zwróć uwagę na nazwę hosta, nazwę i grupę zasobów wystąpienia usługi Azure Digital Twins z danych wyjściowych. Te wartości są ważne i może być konieczne ich użycie podczas dalszej pracy z wystąpieniem usługi Azure Digital Twins w celu skonfigurowania uwierzytelniania i powiązanych zasobów platformy Azure. Jeśli inni użytkownicy będą programować względem wystąpienia, należy udostępnić im te wartości.
Napiwek
Te właściwości można wyświetlić wraz ze wszystkimi właściwościami wystąpienia w dowolnym momencie, uruchamiając polecenie az dt show --dt-name <your-Azure-Digital-Twins-instance>.
Masz teraz gotowe wystąpienie usługi Azure Digital Twins. Następnie przyznasz odpowiednie uprawnienia użytkownika platformy Azure do zarządzania nim.
Konfigurowanie uprawnień dostępu użytkowników
Usługa Azure Digital Twins używa identyfikatora Entra firmy Microsoft do kontroli dostępu opartej na rolach (RBAC). Oznacza to, że zanim użytkownik będzie mógł wykonywać wywołania płaszczyzny danych do wystąpienia usługi Azure Digital Twins, musi mieć przypisaną rolę z odpowiednimi uprawnieniami.
W przypadku usługi Azure Digital Twins ta rola jest właścicielem danych usługi Azure Digital Twins. Więcej informacji na temat ról i zabezpieczeń można uzyskać w temacie Zabezpieczenia dla rozwiązań usługi Azure Digital Twins.
Uwaga
Ta rola różni się od roli właściciela identyfikatora entra firmy Microsoft, którą można również przypisać w zakresie wystąpienia usługi Azure Digital Twins. Są to dwie odrębne role zarządzania, a właściciel nie udziela dostępu do funkcji płaszczyzny danych, które są przyznawane właścicielowi danych usługi Azure Digital Twins.
W tej sekcji pokazano, jak utworzyć przypisanie roli dla użytkownika w wystąpieniu usługi Azure Digital Twins przy użyciu poczty e-mail tego użytkownika w dzierżawie usługi Microsoft Entra w ramach subskrypcji platformy Azure. W zależności od twojej roli w organizacji możesz skonfigurować to uprawnienie dla siebie lub skonfigurować je w imieniu innej osoby, która będzie zarządzać wystąpieniem usługi Azure Digital Twins.
Wymagania wstępne: wymagania dotyczące uprawnień
Aby móc wykonać wszystkie poniższe kroki, musisz mieć rolę w subskrypcji , która ma następujące uprawnienia:
- Tworzenie zasobów platformy Azure i zarządzanie nimi
- Zarządzanie dostępem użytkowników do zasobów platformy Azure (w tym udzielanie i delegowanie uprawnień)
Typowe role spełniające to wymaganie to właściciel, administrator konta lub kombinacja Administracja istratora dostępu użytkowników i współautora. Aby uzyskać pełne wyjaśnienie ról i uprawnień, w tym uprawnień uwzględnionych w innych rolach, odwiedź stronę Role platformy Azure, Role firmy Microsoft Entra i klasyczne role administratora subskrypcji w dokumentacji RBAC platformy Azure.
Aby wyświetlić swoją rolę w subskrypcji, odwiedź stronę subskrypcji w witrynie Azure Portal (możesz użyć tego linku lub wyszukać subskrypcje z paskiem wyszukiwania portalu). Wyszukaj nazwę używanej subskrypcji i wyświetl swoją rolę w kolumnie Moja rola :
Jeśli okaże się, że wartość to Współautor lub inna rola, która nie ma wymaganych uprawnień opisanych powyżej, możesz skontaktować się z użytkownikiem subskrypcji, który ma te uprawnienia (np. właściciel subskrypcji lub administrator konta) i kontynuować jedną z następujących czynności:
- Poproś o ukończenie kroków przypisywania ról w Twoim imieniu.
- Poproś o podniesienie poziomu roli w subskrypcji, aby mieć uprawnienia do samodzielnego kontynuowania. To, czy jest to odpowiednie, zależy od organizacji i twojej roli w niej.
Przypisywanie roli
Aby udzielić użytkownikowi uprawnień do zarządzania wystąpieniem usługi Azure Digital Twins, musisz przypisać im rolę właściciela danych usługi Azure Digital Twins w ramach wystąpienia.
Użyj następującego polecenia, aby przypisać rolę (musi być uruchamiana przez użytkownika z wystarczającymi uprawnieniami w subskrypcji platformy Azure). To polecenie wymaga przekazania głównej nazwy użytkownika na koncie Microsoft Entra dla użytkownika, który powinien mieć przypisaną rolę. W większości przypadków ta wartość będzie zgodna z adresem e-mail użytkownika na koncie 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"
Wynikiem tego polecenia są dane wyjściowe dotyczące przypisania roli utworzonego dla użytkownika.
Uwaga
Jeśli to polecenie zwróci błąd z informacją, że interfejs wiersza polecenia nie może odnaleźć użytkownika lub jednostki usługi w grafowej bazie danych:
Przypisz rolę przy użyciu identyfikatora obiektu użytkownika. Może się to zdarzyć w przypadku użytkowników na osobistych kontach Microsoft (MSA).
Użyj strony witryny Azure Portal użytkowników firmy Microsoft Entra, aby wybrać konto użytkownika i otworzyć jego szczegóły. Skopiuj identyfikator obiektu użytkownika:
Następnie powtórz polecenie listy przypisań ról przy użyciu identyfikatora obiektu użytkownika dla powyższego parametru assignee .
Weryfikowanie powodzenia
Jednym ze sposobów sprawdzenia, czy przypisanie roli zostało pomyślnie skonfigurowane, jest wyświetlenie przypisań ról dla wystąpienia usługi Azure Digital Twins w witrynie Azure Portal. Przejdź do wystąpienia usługi Azure Digital Twins w witrynie Azure Portal. Aby się tam dostać, możesz wyszukać go na stronie wystąpień usługi Azure Digital Twins lub wyszukać jego nazwę na pasku wyszukiwania portalu.
Następnie wyświetl wszystkie przypisane role w ramach przypisań ról kontroli dostępu (IAM). > Twoje przypisanie roli powinno zostać wyświetlone na liście.
Masz teraz gotowe wystąpienie usługi Azure Digital Twins do użycia i masz przypisane uprawnienia do zarządzania nim.
Włączanie/wyłączanie tożsamości zarządzanej dla wystąpienia
W tej sekcji pokazano, jak dodać tożsamość zarządzaną do wystąpienia usługi Azure Digital Twins, które już istnieje. Możesz również wyłączyć tożsamość zarządzaną w wystąpieniu, które ma już.
Użyj poniższych poleceń interfejsu wiersza polecenia dla wybranego typu tożsamości zarządzanej.
Polecenia tożsamości przypisanej przez system
Polecenie umożliwiające włączenie tożsamości przypisanej przez system dla istniejącego wystąpienia jest tym samym az dt create poleceniem, które służy do tworzenia nowego wystąpienia z tożsamością przypisaną przez system. Zamiast podawać nową nazwę wystąpienia do utworzenia, możesz podać nazwę wystąpienia, które już istnieje. Następnie pamiętaj, aby dodać --mi-system-assigned parametr .
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned
Aby wyłączyć tożsamość przypisaną przez system w wystąpieniu, w którym jest ona obecnie włączona, użyj następującego polecenia, aby ustawić wartość --mi-system-assignedfalse.
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned false
Polecenia tożsamości przypisane przez użytkownika
Aby włączyć tożsamość przypisaną przez użytkownika w istniejącym wystąpieniu, podaj identyfikator istniejącej tożsamości przypisanej przez użytkownika w następującym poleceniu:
az dt identity assign --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
Aby wyłączyć tożsamość przypisaną przez użytkownika w wystąpieniu, w którym jest ona obecnie włączona, podaj identyfikator tożsamości w następującym poleceniu:
az dt identity remove --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
Zagadnienia dotyczące wyłączania tożsamości zarządzanych
Ważne jest, aby wziąć pod uwagę skutki, jakie mogą mieć jakiekolwiek zmiany w tożsamości lub jej rolach w zasobach, które go używają. Jeśli używasz tożsamości zarządzanych z punktami końcowymi usługi Azure Digital Twins lub historii danych , a tożsamość jest wyłączona lub z niej zostanie usunięta niezbędna rola, połączenie punktu końcowego lub historii danych może stać się niedostępne, a przepływ zdarzeń zostanie przerwany.
Aby nadal korzystać z punktu końcowego skonfigurowanego przy użyciu tożsamości zarządzanej, która została teraz wyłączona, musisz usunąć ten punkt końcowy i utworzyć go ponownie przy użyciu innego typu uwierzytelniania. Po tej zmianie może minąć do 1 godziny, zanim nastąpi wznowienie dostarczania zdarzeń do punktu końcowego.
Następne kroki
Przetestuj poszczególne wywołania interfejsu API REST w wystąpieniu przy użyciu poleceń interfejsu wiersza polecenia usługi Azure Digital Twins:
Możesz też zobaczyć, jak połączyć aplikację kliencką z wystąpieniem przy użyciu kodu uwierzytelniania: