다음을 통해 공유

자습서: 샘플 클라이언트 앱을 사용하여 Azure Digital Twins 그래프 만들기

  • 아티클

이 자습서에서는 모델, 트윈 및 관계를 사용하여 Azure Digital Twins에서 그래프를 작성합니다. 이 자습서의 도구는 Azure Digital Twins 인스턴스와 상호 작용하기 위한 샘플 명령줄 클라이언트 애플리케이션입니다. 클라이언트 앱은 클라이언트 앱 코딩에서 작성한 것과 비슷합니다.

이 샘플을 사용하여 모델 업로드, 트윈 생성 및 수정, 관계 생성과 같은 필수 Azure Digital Twins 작업을 수행할 수 있습니다. 또한 샘플 코드를 보고 Azure Digital Twins API에 대해 배우고 원하는 대로 샘플 프로젝트를 수정하여 명령을 직접 구현해 볼 수 있습니다.

이 자습서에서는 다음을 수행합니다.

  • 환경 모델링
  • 디지털 트윈 만들기
  • 관계를 추가하여 그래프 형성
  • 그래프를 쿼리하여 질문에 답변

필수 조건

이 자습서를 시작하기 전에 다음 필수 구성 요소를 시작합니다.

  • Azure 구독이 없는 경우 시작하기 전에 체험 계정을 만듭니다.
  • 이 자습서에서는 .NET을 사용합니다. .NET 다운로드에서 여러 플랫폼용 .NET SDK의 최신 버전을 다운로드할 수 있습니다.

그런 다음, 이 섹션의 나머지 부분을 계속 진행하여 나머지 필수 구성 요소를 설정합니다.

샘플 리소스 가져오기

자습서는 C#으로 작성된 Azure Digital Twins 엔드투엔드 샘플 프로젝트를 기반으로 합니다. 샘플 링크로 이동하여 제목 아래에서 코드 찾아보기 단추를 선택하여 컴퓨터에서 샘플 프로젝트를 가져옵니다.

그러면 코드 단추를 선택한 다음, ZIP 다운로드를 선택하여 .zip으로 다운로드할 수 있는 샘플용 GitHub 리포지토리로 이동합니다.

Screenshot of the digital-twins-samples repo on GitHub, highlighting the steps to download it as a zip.

그러면 .zip 폴더가 digital-twins-samples-master.zip으로 컴퓨터에 다운로드됩니다. 폴더의 압축을 풀고 파일을 추출합니다.

Azure Digital Twins 인스턴스 준비하기

이 문서에서 Azure Digital Twins로 작업하려면 Azure Digital Twins 인스턴스와 이를 사용하는 데 필요한 권한이 필요합니다. 이미 Azure Digital Twins 인스턴스를 설정한 경우 해당 인스턴스를 사용하고 다음 섹션으로 건너뛸 수 있습니다. 그렇지 않으면 인스턴스 및 인증 설정의 지침을 따릅니다. 지침에는 각 단계를 성공적으로 완료했는지 확인하는 데 도움이 되는 정보가 포함되어 있습니다.

인스턴스가 설정되면 인스턴스의 호스트 이름을 적어 둡니다. Azure Portal에서 호스트 이름을 찾을 수 있습니다.

샘플 프로젝트 구성

다음으로, Azure Digital Twins 인스턴스와 상호 작용하는 샘플 클라이언트 애플리케이션을 설정합니다.

컴퓨터에서 이전에 Azure Digital Twins 엔드투엔드 샘플에서 다운로드한 파일로 이동합니다. 아직 압축을 풀지 않은 경우 압축을 풉니다.

폴더 내부에서 digital-twins-samples-main\AdtSampleApp\SampleClientApp으로 이동하여 appsettings.json 파일을 엽니다. 이 JSON 파일에는 프로젝트를 실행하는 데 필요한 구성 변수가 포함되어 있습니다.

파일 본문에서 instanceUrl을 Azure Digital Twins 인스턴스 호스트 이름 URL로 변경합니다(아래와 같이 호스트 이름 앞에 https:// 추가).

{
  "instanceUrl": "https://<your-Azure-Digital-Twins-instance-host-name>"
}

파일을 저장 후 닫습니다.

로컬 Azure 자격 증명 설정

이 샘플은 로컬 컴퓨터에서 실행할 때 DefaultAzureCredential(Azure.Identity 라이브러리의 일부)을 사용하여 Azure Digital Twins 인스턴스에서 사용자를 인증합니다. 클라이언트 앱에서 Azure Digital Twins를 사용하여 인증하는 여러 방법에 대한 자세한 내용은 앱 인증 코드 작성을 참조하세요.

DefaultAzureCredential을 사용하면 샘플에서 로컬 Azure CLI 또는 Visual Studio 또는 Visual Studio Code의 Azure 로그인과 같은 로컬 환경에서 자격 증명을 검색합니다. 이러한 이유로 샘플에 대한 자격 증명을 설정하려면 이러한 메커니즘 중 하나를 통해 Azure에 로컬로 로그인해야 합니다.

Visual Studio 또는 Visual Studio Code를 사용하여 코드 샘플을 실행하는 경우 Azure Digital Twins 인스턴스에 액세스하는 데 사용하려는 것과 동일한 Azure 자격 증명을 사용하여 해당 편집기에 로그인했는지 확인합니다. 로컬 CLI 창을 사용하는 경우 az login 명령을 실행하여 Azure 계정에 로그인합니다. 그런 다음 코드 샘플을 실행하면 자동으로 인증을 받아야 합니다.

샘플 프로젝트 실행

이제 앱 및 인증이 설정되었으므로 프로젝트를 실행하는 데 사용할 로컬 콘솔 창을 엽니다. 콘솔에서 digital-twins-samples-main\AdtSampleApp\SampleClientApp 폴더로 이동하고 다음 dotnet 명령을 사용하여 프로젝트를 실행합니다.

dotnet run

프로젝트에서 실행을 시작하고, 인증을 수행하고, 명령을 기다립니다.

프로젝트 콘솔의 스크린샷은 다음과 같습니다.

Screenshot of the welcome message from the command-line app.

팁

이 프로젝트에서 사용할 수 있는 모든 명령 목록을 보려면 프로젝트 콘솔에 help를 입력하고 Return 키를 누릅니다.

앱이 성공적으로 실행되고 있는지 확인한 후에는 프로젝트 실행을 중지할 수 있습니다. 자습서 뒷부분에서 다시 실행합니다.

DTDL로 물리적 환경 모델링

Azure Digital Twins 인스턴스와 샘플 앱이 설정되었으므로 이제 시나리오의 그래프를 만들 수 있습니다.

Azure Digital Twins 솔루션을 만드는 첫 번째 단계는 사용자 환경에 대한 트윈 모델을 정의하는 것입니다.

모델은 개체 지향 프로그래밍 언어의 클래스와 유사합니다. 이는 디지털 트윈을 만들기 위해 인스턴스화할 수 있는 사용자 정의 템플릿입니다. Azure Digital Twins용 모델은 DTDL(Digital Twins 정의 언어)이라는 JSON과 유사한 언어로 작성되며 해당 속성, 관계 및 구성 요소 측면에서 트윈 형식을 정의합니다.

참고 항목

또한 DTDL은 Digital Twins에 명령 정의를 허용합니다. 그러나 Azure Digital Twins 서비스에서는 현재 명령이 지원되지 않습니다.

이전에 다운로드한 샘플 프로젝트 폴더에서 digital-twins-samples-main\AdtSampleApp\SampleClientApp\Models 폴더로 이동합니다. 이 폴더에는 샘플 모델이 있습니다.

편집을 위해 Room.json을 열고 코드를 다음과 같이 변경합니다.

  1. 버전 번호를 업데이트하여 이 모델의 최신 버전을 제공하고 있음을 나타냅니다. 이렇게 하려면 @id 값의 끝에 있는 1을 2로 변경합니다. 현재 버전 번호보다 큰 번호도 사용할 수 있습니다.

  2. 속성을 편집합니다. Humidity 속성의 이름을 HumidityLevel로 변경합니다. 원하는 경우 다른 이름을 사용할 수 있습니다. HumidityLevel이 아닌 다른 이름을 사용하는 경우 해당 이름을 기억하여 자습서 전체에서 HumidityLevel 대신 사용합니다.

  3. 속성을 추가합니다. 줄 15에서 끝나는 HumidityLevel 속성 아래에 다음 코드를 붙여 넣어 RoomName 속성을 room에 추가합니다.

    ,{
  "@type": "Property",
  "name": "RoomName",
  "schema": "string"
}

  4. 관계 추가. 방금 추가한 RoomName 속성 아래에 다음 코드를 붙여 넣어 이러한 유형의 트윈이 다른 트윈과 contains 관계를 형성하는 기능을 추가합니다.

    ,{
  "@type": "Relationship",
  "name": "contains"
}

완료 시 업데이트된 모델은 이와 일치해야 합니다.

{
    "@id": "dtmi:example:Room;2",
    "@type": "Interface",
    "displayName": "Room",
    "contents": [
      {
        "@type": "Property",
        "name": "Temperature",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "HumidityLevel",
        "schema": "double"
      }
      ,{
        "@type": "Property",
        "name": "RoomName",
        "schema": "string"
      }
      ,{
        "@type": "Relationship",
        "name": "contains"
      }
    ],
    "@context": "dtmi:dtdl:context;3"
  }

계속 진행하기 전에 파일을 저장합니다.

Azure Digital Twins에 모델 업로드

모델을 설계한 후에는 Azure Digital Twins 인스턴스에 업로드해야 합니다. 이렇게 하면 고유의 사용자 지정 도메인 어휘를 사용하여 Azure Digital Twins 서비스 인스턴스가 구성됩니다. 모델이 업로드되면 이를 사용하는 트윈 인스턴스를 만들 수 있습니다.

  1. digital-twins-samples-main\AdtSampleApp\SampleClientApp 폴더에 열려 있는 콘솔 창으로 돌아가서 dotnet run을 사용하여 콘솔 앱을 다시 실행합니다.

  2. 프로젝트 콘솔 창에서 다음 명령을 실행하여 다음 섹션에서도 사용할 Floor 모델과 함께 업데이트된 Room 모델을 업로드하여 여러 유형의 트윈을 만듭니다.

    CreateModels Room Floor

    출력에 모델이 성공적으로 만들어졌다고 표시되어야 합니다.

  3. 명령 GetModels true를 실행하여 모델이 만들어졌는지 확인합니다. 이 명령은 Azure Digital Twins 인스턴스에 업로드된 모든 모델에 대한 전체 정보를 출력합니다. 결과에서 편집된 Room 모델을 찾습니다.

    Screenshot of the result from GetModels, showing the updated Room model.

다음 단계를 위해 콘솔 앱을 계속 실행합니다.

Errors

샘플 애플리케이션은 서비스의 오류도 처리합니다.

이를 테스트하려면 CreateModels 명령을 다시 실행하여 이미 업로드한 Room 모델을 다시 업로드해 봅니다.

CreateModels Room

모델을 덮어쓸 수 없으므로 이 명령은 만들려는 모델 ID 중 일부가 이미 있음을 나타내는 서비스 오류를 반환합니다.

기존 모델을 삭제하는 방법에 대한 자세한 내용은 DTDL 모델 관리를 참조하세요.

디지털 트윈 만들기

일부 모델이 Azure Digital Twins 인스턴스에 업로드되었으므로 모델 정의를 기반으로 디지털 트윈을 만들 수 있습니다. 디지털 트윈은 농장의 센서, 건물의 방 또는 자동차의 조명과 같은 비즈니스 환경 내의 엔터티를 나타냅니다.

디지털 트윈을 만들려면 CreateDigitalTwin 명령을 사용합니다. 트윈이 기반으로 하는 모델을 참조해야 하며, 필요에 따라 모델의 속성에 대한 초기 값을 정의할 수 있습니다. 이 단계에서는 관계 정보를 전달할 필요가 없습니다.

  1. 실행 중인 프로젝트 콘솔에서 이 코드를 실행하여 이전에 업데이트한 Room 모델과 또 다른 모델인 Floor를 기반으로 여러 개의 트윈을 만듭니다. Room에는 세 가지 속성이 있으므로 이러한 속성에 대한 초기 값을 인수에 제공할 수 있습니다. (속성 값 초기화는 일반적으로 선택 사항이지만 이 자습서에는 필요합니다.)

    CreateDigitalTwin dtmi:example:Room;2 room0 RoomName string Room0 Temperature double 70 HumidityLevel double 30
CreateDigitalTwin dtmi:example:Room;2 room1 RoomName string Room1 Temperature double 80 HumidityLevel double 60
CreateDigitalTwin dtmi:example:Floor;1 floor0
CreateDigitalTwin dtmi:example:Floor;1 floor1

    이러한 명령의 출력에 트윈이 성공적으로 만들어졌다고 표시되어야 합니다.

    Screenshot showing an excerpt from the result of the CreateDigitalTwin commands, which includes floor0, floor1, room0, and room1.

  2. Query 명령을 실행하여 트윈이 만들어졌는지 확인할 수 있습니다. 이 명령은 Azure Digital Twins 인스턴스에 포함된 모든 디지털 트윈을 쿼리합니다. 결과에서 room0, room1, floor0, floor1 트윈을 찾습니다.

참고 항목

그래프의 데이터를 변경한 후 변경 사항이 쿼리에 반영될 때까지 대기 시간은 최대 10초일 수 있습니다.

DigitalTwins API는 변경 사항을 즉시 반영하므로 즉각적인 응답이 필요한 경우 API 요청(DigitalTwins GetById)이나 SDK 호출(GetDigitalTwin)을 사용하여 쿼리 대신 트윈 데이터를 가져옵니다.

디지털 트윈 수정

사용자가 만든 트윈의 속성을 수정할 수도 있습니다.

참고 항목

기본 REST API는 JSON 패치 형식을 사용하여 트윈에 대한 업데이트를 정의합니다. 명령줄 앱도 이 형식을 사용하여 기본 API가 기대하는 바를 보다 정확하게 경험할 수 있습니다.

  1. 이 명령을 실행하여 room0의 RoomName을 "Room0"에서 "PresidentialSuite"로 변경합니다.

    UpdateDigitalTwin room0 add /RoomName string PresidentialSuite

    출력에 트윈이 성공적으로 업데이트되었다고 표시되어야 합니다.

  2. 이 명령을 실행하여 room0의 정보를 확인하여 업데이트 성공 여부를 확인할 수 있습니다.

    GetDigitalTwin room0

    출력에 업데이트된 이름이 반영되어야 합니다.

관계를 추가하여 그래프 만들기

다음으로, 이러한 트윈 간의 몇 가지 관계를 만들어 트윈 그래프로 연결할 수 있습니다. 트윈 그래프는 전체 환경을 나타내는 데 사용됩니다.

한 트윈에서 다른 트윈으로 작성할 수 있는 관계 유형은 이전에 업로드한 모델 내에서 정의됩니다. Floor에 대한 모델 정의는 층이 contains라는 관계 형식을 가질 수 있음을 지정합니다. 이를 통해 각 Floor 트윈에서 포함된 해당 방까지 contains 형식 관계를 만들 수 있습니다.

관계를 추가하려면 CreateRelationship 명령을 사용합니다. 관계가 시작되는 트윈, 관계 유형 및 관계가 연결되는 트윈을 지정합니다. 마지막으로 관계에 고유한 ID를 지정합니다.

  1. 다음 명령을 실행하여 이전에 만든 각 Floor 트윈의 contains 관계를 해당 Room 트윈에 추가합니다. 관계 이름은 relationship0 및 relationship1입니다.

    CreateRelationship floor0 contains room0 relationship0
CreateRelationship floor1 contains room1 relationship1

    팁

    Floor 모델의 contains 관계도 ownershipUser 및 ownershipDepartment의 두 가지 문자열 속성으로 정의되었으므로 관계를 만들 때 인수를 이러한 관계에 대한 초기 값으로 제공할 수도 있습니다. 다음은 이러한 속성에 대한 초기값도 지정하는 relationship0을 만드는 위 명령의 대체 버전입니다.

    CreateRelationship floor0 contains room0 relationship0 ownershipUser string MyUser ownershipDepartment string myDepartment

    이러한 명령의 출력은 관계가 성공적으로 만들어졌는지 확인합니다.

    Screenshot of an excerpt from the result of the CreateRelationship commands, which includes relationship0 and relationship1.

  2. Azure Digital Twins 인스턴스의 관계를 출력하는 다음 명령 중 하나를 사용하여 관계를 확인할 수 있습니다.

    • 각 floor에서 시작되는 모든 관계를 보려면 다음 명령을 실행합니다(한 쪽에서 관계 보기). 
      GetRelationships floor0
GetRelationships floor1
    • 각 room에 도착하는 모든 관계를 보려면 다음 명령을 실행합니다("다른" 쪽에서 관계 보기). 
      GetIncomingRelationships room0
GetIncomingRelationships room1
    • 이러한 관계를 ID별로 개별적으로 찾으려면 다음 명령을 실행합니다. 
      GetRelationship floor0 relationship0
GetRelationship floor1 relationship1

이 자습서에서 설정한 트윈과 관계는 다음과 같은 개념적 그래프를 만듭니다.

A diagram showing a conceptual graph. floor0 is connected via relationship0 to room0, and floor1 is connected via relationship1 to room1.

트윈 그래프를 쿼리하여 환경 질문에 대답

Azure Digital Twins의 주요 기능은 환경에 대한 질문에 답하도록 쉽고 효율적으로 트윈 그래프를 쿼리하는 기능입니다.

참고 항목

그래프의 데이터를 변경한 후 변경 사항이 쿼리에 반영될 때까지 대기 시간은 최대 10초일 수 있습니다.

DigitalTwins API는 변경 사항을 즉시 반영하므로 즉각적인 응답이 필요한 경우 API 요청(DigitalTwins GetById)이나 SDK 호출(GetDigitalTwin)을 사용하여 쿼리 대신 트윈 데이터를 가져옵니다.

실행 중인 프로젝트 콘솔에서 다음 명령어를 실행하여 샘플 환경에 대한 몇 가지 질문에 답변합니다.

  1. Azure Digital Twins에 표시되는 내 환경의 모든 엔터티는 무엇인가요? (모두 쿼리)

    Query

    이 명령을 사용하면 환경을 한눈에 파악하고 모든 것이 Azure Digital Twins 내에 원하는 대로 표시되는지 확인할 수 있습니다. 이 명령의 결과는 해당 세부 정보와 함께 각 디지털 트윈이 포함된 출력입니다. 발췌한 출력은 다음과 같습니다.

    Screenshot showing a partial result from the twin query, including room0 and floor1.

    팁

    샘플 프로젝트에서 추가 인수가 없는 명령 Query는 Query SELECT * FROM DIGITALTWINS와 같습니다. 쿼리 API 또는 CLI 명령을 사용하여 인스턴스의 모든 쌍을 쿼리하려면 더 긴(전체) 쿼리를 사용합니다.

  2. 내 환경의 모든 room은 무엇인가요? (모델로 쿼리)

    Query SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')

    특정 유형의 트윈으로 쿼리를 제한하여 표시되는 항목에 대한 보다 구체적인 정보를 얻을 수 있습니다. 이 쿼리의 결과는 room0 및 room1을 표시하지만 floor0 또는 floor1을 표시하지 않습니다(방이 아니라 층이므로).

    Screenshot of the result from the model query, showing only room0 and room1.

  3. floor0의 모든 room은 무엇인가요? (관계로 쿼리)

    Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0'

    그래프의 관계를 기반으로 쿼리하여 트윈 연결 방식에 대한 정보를 얻거나 쿼리를 특정 영역으로 제한할 수 있습니다. room0만 floor0에 있으므로 이것이 결과의 유일한 room입니다.

    Screenshot of the result from the relationship query, showing room0.

  4. 내 환경에서 온도가 75를 초과하는 모든 쌍은 무엇인가요?라는 질문에 대답합니다. (속성으로 쿼리)

    Query SELECT * FROM DigitalTwins T WHERE T.Temperature > 75

    속성을 기준으로 그래프를 쿼리하여 주의가 필요할 수 있는 환경의 이상값 찾기를 포함하여 다양한 질문에 대답할 수 있습니다. 다른 비교 연산자(<,>, = 또는 !=)도 지원됩니다. room1이 온도가 80도이기 때문에 다음 결과에 표시됩니다.

    Screenshot of the result from the property query, showing only room1.

  5. 온도가 75도가 넘는 floor0의 모든 room은 무엇인가요? (복합 쿼리)

    Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0' AND IS_OF_MODEL(room, 'dtmi:example:Room;2') AND room.Temperature > 75

    AND, OR, NOT과 같은 조합 연산자를 사용하여 SQL에서와 같이 이전 쿼리를 결합할 수도 있습니다. 이 쿼리는 AND를 사용하여 트윈 온도에 대한 이전 쿼리를 더 구체화합니다. 이제 결과에는 floor0에서 온도가 75도가 넘는 room만 포함됩니다(이 경우에는 없음). 결과 집합이 비어 있습니다.

    Screenshot of the result from the compound query, showing no results.

설정한 시나리오에서 여러 쿼리를 실행했으므로 자습서가 완료되었습니다. 프로젝트 실행을 중지하고 콘솔 창을 닫습니다.

리소스 정리

이 자습서를 완료한 후 다음에 수행하려는 작업에 따라 제거할 리소스를 선택할 수 있습니다.

  • 다음 자습서로 계속 진행할 계획인 경우 여기에서 설정한 리소스를 유지하여 이 Azure Digital Twins 인스턴스와 구성된 샘플 앱을 다음 자습서에서 계속 사용할 수 있습니다.

  • Azure Digital Twins 인스턴스를 계속 사용하지만 해당 모델, 트윈 및 관계를 모두 지우려는 경우 샘플 앱의 DeleteAllTwins 및 DeleteAllModels 명령을 사용하여 각각 인스턴스의 트윈과 모델을 지울 수 있습니다.

  • 이 자습서에서 만든 리소스가 필요하지 않으면 az group delete CLI 명령을 사용하여 이 문서의 Azure Digital Twins 인스턴스 및 기타 모든 리소스를 삭제할 수 있습니다. 이는 리소스 그룹의 모든 Azure 리소스와 리소스 그룹 자체를 삭제합니다.

    Important

    리소스 그룹을 삭제하면 다시 되돌릴 수 없습니다. 리소스 그룹 및 그 안에 포함된 모든 리소스가 영구적으로 삭제됩니다. 잘못된 리소스 그룹 또는 리소스를 자동으로 삭제하지 않도록 해야 합니다.

    Azure Cloud Shell 또는 로컬 CLI 창을 열고, 다음 명령을 실행하여 리소스 그룹과 이 그룹에 포함된 모든 항목을 삭제합니다.

    az group delete --name <your-resource-group>

로컬 머신에서 다운로드한 프로젝트 폴더를 삭제할 수도 있습니다.

다음 단계

이 자습서에서는 샘플 클라이언트 애플리케이션을 사용하여 인스턴스에서 그래프를 만들어 Azure Digital Twins를 시작했습니다. 모델, 디지털 트윈 및 관계를 만들어 그래프를 구성했습니다. 또한 그래프에서 몇 가지 쿼리를 실행하여 Azure Digital Twins가 환경에 대해 어떤 종류의 질문에 답할 수 있는지 알아보았습니다.

다음 자습서에서 Azure Digital Twins와 다른 Azure 서비스를 결합하여 데이터 기반의 엔드투엔드 시나리오를 완성하세요.

엔드투엔드 솔루션 연결