Azure Digital Twins 인스턴스 및 인증 설정(CLI)
이 문서에서는 인스턴스를 만들고 인증을 설정하는 등 새 Azure Digital Twins 인스턴스를 설정하는 단계에 대해 설명합니다. 이 문서를 완료한 후에는 Azure Digital Twins 인스턴스에 대한 프로그래밍을 시작할 수 있습니다.
새 Azure Digital Twins 인스턴스에 대한 전체 설치는 다음 두 부분으로 구성됩니다.
- 인스턴스 만들기
- 사용자 액세스 권한 설정: Azure 사용자는 Azure Digital Twins 인스턴스에서 Azure Digital Twins 데이터 소유자 역할을 가지고 있어야 해당 인스턴스와 데이터를 관리할 수 있습니다. 이 단계에서는 Azure 구독의 소유자/관리자로서, Azure Digital Twins 인스턴스를 관리하는 사용자에게 이 역할을 할당합니다. 사용자 자신일 수도 있고 조직의 다른 사람일 수도 있습니다.
Important
이 전체 문서를 완료하고 사용 가능한 인스턴스를 완전히 설정하려면 Azure 구독에서 리소스와 사용자 액세스를 모두 관리할 수 있는 권한이 필요합니다. 첫 번째 단계는 구독에서 리소스를 만들 수 있는 사용자면 누구나 완료할 수 있지만 두 번째 단계에는 사용자 액세스 관리 권한(또는 이러한 권한이 있는 사람의 협력)이 필요합니다. 이에 대한 자세한 내용은 사용자 액세스 권한 단계의 필수 조건: 필수 권한 섹션을 참조하세요.
필수 조건
Azure Cloud Shell에서 Bash 환경을 사용합니다. 자세한 내용은 Azure Cloud Shell의 Bash에 대한 빠른 시작을 참조하세요.
CLI 참조 명령을 로컬에서 실행하려면 Azure CLI를 설치합니다. Windows 또는 macOS에서 실행 중인 경우 Docker 컨테이너에서 Azure CLI를 실행하는 것이 좋습니다. 자세한 내용은 Docker 컨테이너에서 Azure CLI를 실행하는 방법을 참조하세요.
로컬 설치를 사용하는 경우 az login 명령을 사용하여 Azure CLI에 로그인합니다. 인증 프로세스를 완료하려면 터미널에 표시되는 단계를 수행합니다. 다른 로그인 옵션은 Azure CLI를 사용하여 로그인을 참조하세요.
메시지가 표시되면 처음 사용할 때 Azure CLI 확장을 설치합니다. 확장에 대한 자세한 내용은 Azure CLI에서 확장 사용을 참조하세요.
az version을 실행하여 설치된 버전과 종속 라이브러리를 찾습니다. 최신 버전으로 업그레이드하려면 az upgrade를 실행합니다.
CLI 세션 설정
CLI에서 Azure Digital Twins 작업을 시작하려면 가장 먼저 로그인하여 CLI 컨텍스트를 이 세션의 구독으로 설정해야 합니다. CLI 창에서 다음 명령을 실행합니다.
az login
az account set --subscription "<your-Azure-subscription-ID>"
팁
위의 명령에서 ID 대신 제품 이름을 사용할 수도 있습니다.
Azure Digital Twins에서 이 구독을 처음 사용하는 경우 이 명령을 실행하여 Azure Digital Twins 네임스페이스에 등록합니다. (확실하지 않으면 이전에 수행한 적이 있더라도 다시 실행해도 됩니다.)
az provider register --namespace 'Microsoft.DigitalTwins'
다음으로 Azure CLI용 Microsoft Azure IoT 확장을 추가하여 Azure Digital Twins 및 기타 IoT 서비스와 상호 작용하기 위한 명령을 사용하도록 설정합니다. 다음 명령을 실행하여 최신 버전의 확장이 있는지 확인합니다.
az extension add --upgrade --name azure-iot
이제 Azure CLI에서 Azure Digital Twins를 사용할 준비가 되었습니다.
사용 가능한 최상위 Azure Digital Twins 명령 목록을 보려면 언제든지 az dt --help를 실행하여 이를 확인할 수 있습니다.
Azure Digital Twins 인스턴스 만들기
이 섹션에서는 CLI 명령을 사용하여 Azure Digital Twins의 새 인스턴스를 만듭니다. 다음을 제공해야 합니다.
- 인스턴스가 배포될 리소스 그룹. 고려 중인 기존 리소스 그룹이 아직 없는 경우 다음 명령을 사용하여 지금 만들 수 있습니다.
az group create --location <region> --name <name-for-your-resource-group> - 배포 지역. Azure Digital Twins를 지원하는 지역을 확인하려면 지역별 사용 가능한 Azure 제품을 참조하세요.
- 인스턴스의 이름. 구독에 지정된 이름을 이미 사용 중인 지역의 다른 Azure Digital Twins 인스턴스가 있는 경우 다른 이름을 선택하라는 메시지가 표시됩니다.
다음 az dt 명령에서 이러한 값을 사용하여 인스턴스를 만듭니다.
az dt create --dt-name <name-for-your-Azure-Digital-Twins-instance> --resource-group <your-resource-group> --location <region>
인스턴스에 대한 관리 ID를 만들거나 공용 네트워크 액세스를 사용/사용 안 함으로 설정하는 것을 포함하여 생성 중에 리소스에 대한 추가 항목을 지정하기 위해 명령에 추가할 수 있는 몇 가지 선택적 매개 변수가 있습니다. 지원되는 매개 변수의 전체 목록은 az dt create 참조 설명서를 참조하세요.
관리 ID를 사용하여 인스턴스 만들기
Azure Digital Twins 인스턴스에 관리 ID를 사용하도록 설정하면 Microsoft Entra ID에서 이에 대한 ID가 자동으로 만들어집니다. 그런 다음, 해당 ID를 사용하여 다른 서비스에서 인증을 받을 수 있습니다. 인스턴스를 만드는 동안 또는 나중에 기존 인스턴스에서 Azure Digital Twins 인스턴스에 대해 관리 ID를 사용하도록 설정할 수 있습니다.
선택한 유형의 관리 ID에 대해 아래 CLI 명령을 사용합니다.
시스템 할당 ID 명령
시스템 할당 ID가 사용하도록 설정된 Azure Digital Twins 인스턴스를 만들려면 인스턴스를 만드는 데 사용되는 az dt create 명령에 --mi-system-assigned 매개 변수를 추가할 수 있습니다. (이 만들기 명령에 대한 자세한 내용은 해당 참조 설명서 또는 Azure Digital Twins 인스턴스를 설정하기 위한 일반 지침을 참조하세요.)
시스템 할당 ID를 사용하여 인스턴스를 만들려면 다음과 같이 --mi-system-assigned 매개 변수를 추가합니다.
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned
사용자 할당 ID 명령
사용자 할당 ID를 사용하여 인스턴스를 만들려면 다음과 같이 --mi-user-assigned 매개 변수를 사용하여 기존 사용자 할당 ID를 제공합니다.
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-user-assigned <user-assigned-identity-resource-ID>
성공 확인 및 중요한 값 수집
인스턴스가 성공적으로 만들어지면 CLI에 다음과 같이 결과가 표시되어 사용자가 만든 리소스에 대한 정보를 출력합니다.
출력에서 Azure Digital Twins 인스턴스의 hostName, name 및 resourceGroup을 확인합니다. 이러한 값은 모두 중요하며 인증 및 관련 Azure 리소스를 설정하기 위해 Azure Digital Twins 인스턴스 작업을 계속할 때 사용해야 할 수 있습니다. 다른 사용자가 인스턴스에 대한 프로그래밍을 수행하는 경우 다른 사용자와 이 값을 공유해야 합니다.
팁
az dt show --dt-name <your-Azure-Digital-Twins-instance>를 실행하여 언제든지 인스턴스의 모든 속성과 함께 이러한 속성을 볼 수 있습니다.
이제 Azure Digital Twins 인스턴스를 사용할 준비가 되었습니다. 다음으로 이를 관리할 적절한 Azure 사용자 권한을 부여합니다.
사용자 액세스 권한 설정
Azure Digital Twins는 RBAC(역할 기반 액세스 제어)에 Microsoft Entra ID를 사용합니다. 즉, 사용자가 Azure Digital Twins 인스턴스에 대한 데이터 평면 호출을 수행하려면 먼저 해당 사용자에게 적절한 권한이 있는 역할을 할당해야 합니다.
Azure Digital Twins의 경우 이 역할은 Azure Digital Twins 데이터 소유자입니다. Azure Digital Twins 솔루션을 위한 보안에서 역할 및 보안에 대해 자세히 알아볼 수 있습니다.
참고 항목
이 역할은 Azure Digital Twins 인스턴스의 범위에서도 할당될 수 있는 Microsoft Entra ID 소유자 역할과 다릅니다. 이는 두 가지 고유한 관리 역할이며 소유자에게는 Azure Digital Twins 데이터 소유자에게 부여된 데이터 평면 기능에 대한 액세스 권한을 부여하지 않습니다.
이 섹션에서는 Azure 구독의 Microsoft Entra 테넌트에서 해당 사용자의 이메일을 사용하여 Azure Digital Twins 인스턴스의 사용자에 대한 역할 할당을 만드는 방법을 보여줍니다. 조직의 역할에 따라 이 권한을 직접 설정하거나 Azure Digital Twins 인스턴스를 관리할 다른 사용자를 대신하여 설정할 수 있습니다.
필수 조건: 권한 요구 사항
다음의 모든 단계를 완료하려면 구독에 다음 권한이 있는 역할이 있어야 합니다.
- Azure 리소스 만들기 및 관리
- Azure 리소스에 대한 사용자 액세스 관리(권한 부여 및 위임 포함)
이 요구 사항을 충족하는 일반적인 역할은 소유자, 계정 관리자 또는 사용자 액세스 관리자와 기여자의 조합입니다. 다른 역할에 포함된 권한을 포함하여 역할 및 권한에 대한 자세한 설명은 Azure RBAC 설명서에서 Azure 역할, Microsoft Entra 역할 및 클래식 구독 관리자 역할을 참조하세요.
구독에서 역할을 보려면 Azure Portal의 구독 페이지를 방문하세요. 이 링크를 사용하거나 포털 검색 창에서 구독을 찾을 수 있습니다. 사용 중인 구독의 이름을 찾고 내 역할 열에서 해당 구독에 대한 사용자 역할을 확인합니다.
값이 기여자 또는 위에 설명된 필수 권한이 없는 다른 역할인 경우 이러한 권한이 있는 구독의 사용자(예: 구독 소유자 또는 계정 관리자)에게 연락하여 다음 방법 중 하나로 진행할 수 있습니다.
- 사용자 대신 역할 할당 단계를 완료하도록 요청합니다.
- 사용자가 직접 진행할 수 있는 권한을 갖게 구독에 대한 역할을 승격 하도록 요청합니다. 이것이 적절한지 여부는 조직과 조직 내의 사용자 역할에 따라 다릅니다.
역할 할당
사용자에게 Azure Digital Twins 인스턴스를 관리할 수 있는 권한을 부여하려면 인스턴스 내에서 Azure Digital Twins 데이터 소유자 역할을 할당해야 합니다.
다음 명령을 사용하여 역할을 할당합니다(Azure 구독에 충분한 권한이 있는 사용자가 실행해야 함). 이 명령을 사용하려면 역할을 할당해야 하는 사용자에 대한 Microsoft Entra 계정의 사용자 주체 이름을 전달해야 합니다. 대부분의 경우 이 값은 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"
이 명령을 실행하면 사용자에 대해 만들어진 역할 할당에 대한 정보가 출력됩니다.
참고 항목
이 명령을 실행할 때 CLI가 그래프 데이터베이스에서 사용자 또는 서비스 주체를 찾을 수 없다는 오류를 반환하는 경우:
대신 사용자의 개체 ID를 사용하여 역할을 할당합니다. 이는 개인 MSA(Microsoft 계정)의 사용자에게 발생할 수 있습니다.
AMicrosoft Entra 사용자의 Azure Portal 페이지를 사용하여 사용자 계정을 선택하고 세부 정보를 엽니다. 사용자의 개체 ID를 복사합니다.
그런 다음. 위의 assignee 매개 변수에 대한 사용자의 개체 ID를 사용하여 역할 할당 목록 명령을 반복합니다.
성공 확인
역할 할당을 성공적으로 설정했는지 확인하는 한 가지 방법은 Azure Portal에서 Azure Digital Twins 인스턴스에 대한 역할 할당을 확인하는 것입니다. Azure Portal에서 Azure Digital Twins 인스턴스로 이동합니다. 여기로 이동하려면 Azure Digital Twins 인스턴스 페이지에서 조회하거나 포털 검색 창에서 해당 이름을 검색할 수 있습니다.
그런 다음, 액세스 제어(IAM) > 역할 할당에서 할당된 모든 역할을 확인합니다. 역할 할당이 목록에 나타나야 합니다.
이제 Azure Digital Twins 인스턴스를 사용할 준비가 되고 관리 권한이 할당되었습니다.
인스턴스에 관리 ID 사용/사용 안 함
이 섹션에서는 기존의 Azure Digital Twins 인스턴스에 관리 ID를 추가하는 방법을 보여 줍니다. 이미 있는 인스턴스에서 관리 ID를 사용하지 않도록 설정할 수도 있습니다.
선택한 유형의 관리 ID에 대해 아래 CLI 명령을 사용합니다.
시스템 할당 ID 명령
기존 인스턴스에 대해 ‘시스템 할당’ ID를 사용하도록 설정하는 명령은 시스템 할당 ID를 사용하여 새 인스턴스를 만드는 데 사용되는 것과 동일한 az dt create 명령입니다. 만들 인스턴스의 새 이름을 입력하는 대신 이미 존재하는 인스턴스의 이름을 입력할 수 있습니다. 그런 다음, --mi-system-assigned 매개 변수를 추가해야 합니다.
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned
현재 사용하도록 설정된 인스턴스에서 시스템 할당 ID를 사용하지 않도록 설정하려면 다음과 유사한 명령을 사용하여 --mi-system-assigned를 false로 설정합니다.
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned false
사용자 할당 ID 명령
기존 인스턴스에 ‘사용자 할당’ ID를 사용하도록 설정하려면 다음 명령에서 기존 사용자 할당 ID를 제공합니다.
az dt identity assign --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
인스턴스에서 현재 사용하도록 설정된 사용자 할당 ID를 사용하지 않도록 설정하려면 다음 명령에서 해당 ID를 제공합니다.
az dt identity remove --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
관리 ID를 사용하지 않도록 설정할 때 고려 사항
ID 또는 해당 역할에 대한 변경 내용이 ID를 사용하는 리소스에 미칠 수 있는 영향을 고려하는 것이 중요합니다. Azure Digital Twins 엔드포인트에서 관리 ID를 사용하거나 데이터 기록에 대해 관리 ID를 사용하고 ID가 사용하지 않도록 설정되거나 필요한 역할이 제거되면 엔드포인트 또는 데이터 기록 연결에 액세스할 수 없게 되고 이벤트 흐름이 중단될 수 있습니다.
이제 사용하지 않도록 설정된 관리 ID로 설정된 엔드포인트를 계속 사용하려면 엔드포인트를 삭제하고 다른 인증 유형을 사용해서 다시 만들어야 합니다. 이렇게 변경한 후 엔드포인트에 대해 이벤트 전달이 재개되려면 최대 1시간까지 걸릴 수 있습니다.
다음 단계
Azure Digital Twins CLI 명령을 사용하여 인스턴스에서 개별 REST API 호출을 테스트합니다.
또는 인증 코드를 사용하여 인스턴스에 클라이언트 애플리케이션을 연결하는 방법을 참조하세요.