그래프에서 디지털 트윈 관리

완료됨

트윈 그래프 관리에는 Azure Digital Twins 인스턴스에서 디지털 트윈 만들기, 수정 및 삭제가 포함될 수 있습니다. 기본 모델을 관리할 수도 있습니다. 이러한 작업을 완료하려면 Digital Twins API 및 SDK, Azure Digital Twins CLI 명령 집합 또는 Azure Digital Twins 탐색기와 같은 GUI 도구를 사용할 수 있습니다.

.NET(C#) SDK 사용

Azure Digital Twins .NET(C#) SDK는 .Net용 Azure SDK의 일부입니다. 오픈 소스이며 Azure Digital Twins 데이터 평면 API를 기반으로 합니다.

다음 섹션에서는 .NET(C#) SDK를 사용하여 몇 가지 일반적인 관리 작업을 수행하는 방법을 설명합니다.

디지털 트윈 만들기

트윈을 만들려면 서비스 클라이언트에서 다음과 같이 CreateOrReplaceDigitalTwinAsync() 메서드를 사용합니다.

await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinId, initData);

디지털 트윈을 만들려면 다음을 제공해야 합니다.

  • 원하는 디지털 트윈 ID
  • 사용할 모델

필요에 따라 디지털 트윈의 모든 속성에 대해 초기 값을 제공할 수 있습니다. 속성은 선택 사항으로 취급되며 나중에 설정할 수 있지만 설정될 때까지는 트윈의 일부로 표시되지 않습니다.

참고

트윈 속성을 초기화할 필요는 없지만 트윈을 만들 때 트윈의 모든 구성 요소를 설정해야 합니다. 비어 있는 개체일 수 있지만 구성 요소 자체는 존재해야 합니다.

모델 및 초기 속성 값은 관련 데이터가 포함된 JSON 문자열인 initData 매개 변수를 통해 제공됩니다.

트윈 속성 초기화

트윈이 생성될 때 트윈의 속성을 초기화할 수 있습니다.

BasicDigitalTwin의 도우미 클래스를 사용하여 속성 필드를 "트윈" 개체에 직접 저장할 수 있습니다. Dictionary<string, object>를 사용하여 속성 목록을 빌드할 수 있습니다. 그런 다음 트윈 개체에 CustomProperties로 직접 추가할 수 있습니다.

string twinId = "myTwinID";
var initData = new BasicDigitalTwin
{
    Id = twinId,
    Metadata = { ModelId = "dtmi:example:Room;1" },
    // Initialize properties
    Contents =
    {
        { "Temperature", 25.0 },
        { "Humidity", 50.0 },
    },
};

await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinId, initData);

참고

앞의 코드에 표시된 것처럼 BasicDigitalTwin 개체에는 자체 ‘Id’ 필드가 있습니다. 이 필드를 비워 둘 수 있지만 ID 값을 제공하는 경우 이 값이 ‘CreateOrReplaceDigitalTwinAsync()’ 호출에 전달된 ID 매개 변수의 값과 일치해야 하며 ID 매개 변수도 포함해야 합니다.

디지털 트윈에 대한 데이터 가져오기

다음과 같이 GetDigitalTwin() 메서드를 호출하여 디지털 트윈의 세부 정보에 액세스할 수 있습니다.

Response<BasicDigitalTwin> twinResponse = await client.GetDigitalTwinAsync<BasicDigitalTwin>(twinId);
twin = twinResponse.Value;

이 호출은 트윈 데이터를 BasicDigitalTwin과 같은 강력한 형식의 개체 형식으로 반환합니다.

디지털 쌍 업데이트

디지털 트윈의 속성을 업데이트하려면 JSON 패치 형식으로 바꿀 정보를 작성합니다. 이러한 방식으로 여러 속성을 한 번에 바꿀 수 있습니다. 그런 다음 JSON 패치 문서를 UpdateDigitalTwin() 메서드에 전달합니다.

참고

JSON 패치에 익숙하지 않은 경우 ASP.NET Core Web API의 JsonPatch에서 자세한 내용을 참조할 수 있습니다.

await client.UpdateDigitalTwinAsync(twinId, updateTwinData);

한 번의 패치 호출로 단일 트윈의 속성을 원하는 만큼(심지어 모두) 업데이트할 수 있습니다. 여러 트윈에서 속성을 업데이트해야 하는 경우 각 트윈에 대해 별도의 업데이트 호출이 필요합니다.

트윈을 만들거나 업데이트한 후에는 변경 내용이 쿼리에 반영될 때까지 최대 10초의 대기 시간이 있을 수 있습니다. GetDigitalTwin API(이 문서의 앞부분에서 설명)에서는 이러한 지연이 발생하지 않으므로 즉각적인 응답이 필요한 경우 쿼리하는 대신 API 호출을 사용하여 새로 업데이트된 트윈을 확인합니다.

다음은 JSON 패치 코드의 예입니다. 이 문서는 적용되는 디지털 트윈의 mass 및 radius 속성 값을 대체합니다.

[
    {
      "op": "replace",
      "path": "/mass",
      "value": 0.0799
    },
    {
      "op": "replace",
      "path": "/radius",
      "value": 0.800
    }
  ]

Azure .NET SDK의 JsonPatchDocument를 사용하여 패치를 만들 수 있습니다. 다음은 예제입니다.

var updateTwinData = new JsonPatchDocument();
updateTwinData.AppendAdd("/Temperature", 25.0);
updateTwinData.AppendAdd("/myComponent/Property", "Hello");
// Un-set a property
updateTwinData.AppendRemove("/Humidity");

await client.UpdateDigitalTwinAsync("myTwin", updateTwinData);

디지털 트윈의 모델 업데이트

UpdateDigitalTwin() 함수를 사용하여 디지털 트윈을 다른 모델로 마이그레이션할 수도 있습니다.

예를 들어 디지털 트윈의 메타데이터 $model 필드를 대체하는 다음과 같은 JSON 패치 문서를 고려합니다.

[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:example:foo;1"
  }
]

이 작업은 패치로 수정되는 디지털 트윈이 새 모델을 준수하는 경우에만 성공합니다. 다음 예제를 참조하세요.

  • foo_old 모델을 사용하는 디지털 트윈을 생각해 보세요. foo_old는 필요한 속성 mass를 정의합니다.
  • 새 모델 foo_new는 속성 mass를 정의하고 새로운 필수 속성 temperature를 추가합니다.
  • 패치 후에 디지털 트윈에는 mass 속성과 temperature 속성이 모두 있어야 합니다.

이 상황에 대한 패치는 모델과 트윈의 temperature 속성을 모두 업데이트해야 합니다. 예를 들면 다음과 같습니다.

[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:example:foo_new;1"
  },
  {
    "op": "add",
    "path": "/temperature",
    "value": 60
  }
]

디지털 트윈 삭제

DeleteDigitalTwin() 메서드를 사용하여 트윈을 삭제할 수 있습니다. 그러나 더 이상 관계가 없는 경우에만 트윈을 삭제할 수 있습니다. 따라서 트윈의 들어오고 나가는 관계를 먼저 삭제합니다.

다음은 트윈 및 해당 관계를 삭제하는 코드의 예입니다. 더 광범위한 예제 컨텍스트에서 어디에 속하는지 명확하게 하기 위해 DeleteDigitalTwin SDK 호출이 강조 표시되어 있습니다.

private static async Task CustomMethod_DeleteTwinAsync(DigitalTwinsClient client, string twinId)
{
    await CustomMethod_FindAndDeleteOutgoingRelationshipsAsync(client, twinId);
    await CustomMethod_FindAndDeleteIncomingRelationshipsAsync(client, twinId);
    try
    {
        await client.DeleteDigitalTwinAsync(twinId);
        Console.WriteLine("Twin deleted successfully");
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine($"*** Error:{ex.Message}");
    }
}

private static async Task CustomMethod_FindAndDeleteOutgoingRelationshipsAsync(DigitalTwinsClient client, string dtId)
{
    // Find the relationships for the twin

    try
    {
        // GetRelationshipsAsync will throw an error if a problem occurs
        AsyncPageable<BasicRelationship> rels = client.GetRelationshipsAsync<BasicRelationship>(dtId);

        await foreach (BasicRelationship rel in rels)
        {
            await client.DeleteRelationshipAsync(dtId, rel.Id).ConfigureAwait(false);
            Console.WriteLine($"Deleted relationship {rel.Id} from {dtId}");
        }
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine($"*** Error {ex.Status}/{ex.ErrorCode} retrieving or deleting relationships for {dtId} due to {ex.Message}");
    }
}

private static async Task CustomMethod_FindAndDeleteIncomingRelationshipsAsync(DigitalTwinsClient client, string dtId)
{
    // Find the relationships for the twin

    try
    {
        // GetRelationshipsAsync will throw an error if a problem occurs
        AsyncPageable<IncomingRelationship> incomingRels = client.GetIncomingRelationshipsAsync(dtId);

        await foreach (IncomingRelationship incomingRel in incomingRels)
        {
            await client.DeleteRelationshipAsync(incomingRel.SourceId, incomingRel.RelationshipId).ConfigureAwait(false);
            Console.WriteLine($"Deleted incoming relationship {incomingRel.RelationshipId} from {dtId}");
        }
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine($"*** Error {ex.Status}/{ex.ErrorCode} retrieving or deleting incoming relationships for {dtId} due to {ex.Message}");
    }
}

Azure Digital Twins Explorer 사용

Azure Digital Twins Explorer는 모델 및 트윈 그래프를 포함하여 Azure Digital Twins 인스턴스의 데이터를 시각화하고 상호 작용하기 위한 개발자 도구입니다.

Azure Digital Twins Explorer에 액세스하는 주요 방법은 Azure Portal을 사용하는 것입니다. 포털에서 Azure Digital Twins 인스턴스를 열면 Azure Digital Twins Explorer 열기(미리 보기) 단추를 선택하여 연결된 Azure Digital Twins Explorer 창을 열 수 있습니다.

다음 섹션에서는 Azure Digital Twins Explorer를 사용하여 완료할 수 있는 몇 가지 일반적인 작업에 대해 설명합니다.

Digital Twin 그래프 쿼리

탐색기 맨 위에 있는 쿼리 탐색기 패널을 사용하여 그래프에서 쿼리를 수행할 수 있습니다. 실행하려는 쿼리를 입력하고 쿼리 실행 단추를 선택합니다. 이 작업은 트윈 그래프 패널에 쿼리 결과를 로드합니다.

트윈 만들기

탐색기 창의 왼쪽에 있는 모델 패널의 모델 정의에서 새 디지털 트윈을 만들 수 있습니다.

모델에서 트윈을 만들려면 목록에서 해당 모델을 찾고 모델 이름 옆에 있는 트윈 만들기 아이콘을 선택합니다. 새 트윈의 이름을 입력하라는 메시지가 표시됩니다. 이 이름은 고유해야 합니다. 그런 다음, 트윈을 저장하여 그래프에 추가합니다.

관계 만들기

두 트윈 간의 관계를 만들려면 탐색기 창 중간에 있는 트윈 그래프 영역에서 관계의 원본 트윈을 선택하는 것부터 시작합니다. 다음으로, CTRL/CMD 또는 SHIFT 키를 누른 상태에서 두 번째 트윈을 선택하여 관계의 대상으로 지정합니다.

두 트윈을 동시에 선택한 후에는 트윈 중 하나를 마우스 오른쪽 단추로 클릭합니다. 그러면 두 항목 간의 관계를 추가하는 옵션이 포함된 메뉴가 표시됩니다. 관계 추가를 클릭하면 관계의 원본 트윈과 대상 트윈을 보여주는 관계 만들기 대화 상자가 표시되고, 원본 트윈이 가질 수 있는 관계 유형(DTDL 모델에 정의됨)이 포함된 관계 드롭다운 메뉴가 표시됩니다. 관계 유형에 대한 옵션을 선택하고 새 관계를 저장합니다.

트윈 및 관계 편집

트윈 또는 관계의 속성 값을 보려면 트윈 그래프에서 요소를 선택하고 속성 검사기 설정/해제 단추를 사용하여 속성 패널을 확장합니다.

이 패널을 사용하여 쓰기 가능한 속성을 직접 편집할 수 있습니다. 값을 인라인으로 업데이트하고 패널 위쪽의 패치 트윈(저장) 단추를 클릭하여 변경 내용을 저장합니다. 업데이트를 저장하면 업데이트 API에서 적용한 JSON 패치 작업을 보여 주는 모달 창이 화면에 표시됩니다.

트윈 및 관계 삭제

트윈 또는 관계를 삭제하려면 트윈 그래프 창에서 해당 항목을 마우스 오른쪽 단추로 클릭합니다. 이 작업을 수행하면 요소를 삭제하는 옵션이 있는 메뉴가 열립니다.

CTRL/CMD 또는 SHIFT 키를 사용하여 그래프에서 동일한 유형의 여러 요소를 다중 선택하여 여러 개의 트윈이나 관계를 한 번에 삭제할 수도 있습니다. 지금부터 동일한 오른쪽 클릭 프로세스에 따라 요소를 삭제합니다.

위쪽의 도구 모음에 있는 모든 트윈 삭제 단추를 사용하여 인스턴스의 모든 트윈을 동시에 삭제하도록 선택할 수도 있습니다.

모델 및 모델 그래프 살펴보기

모델은 Azure Digital Twins Explorer 화면의 왼쪽에 있는 모델 패널과, 화면 중간의 모델 그래프 패널에서 볼 수 있습니다.

그래프 가져오기

탐색기의 가져오기 기능을 사용하여 인스턴스에 트윈, 관계 및 모델을 추가할 수 있습니다. 이 방법은 단일 작업으로 더 많은 수의 트윈, 관계 및/또는 모델을 만드는 데 유용할 수 있습니다.

가져오기 파일 만들기

그래프를 가져오는 첫 번째 단계는 추가하려는 트윈과 관계를 나타내는 파일을 만드는 것입니다.

가져오기 파일은 다음 두 가지 형식 중 하나일 수 있습니다.

  • 사용자 지정 Excel 기반 형식은 이 섹션의 나머지 부분에서 설명하며, 이 형식을 사용하면 트윈 및 관계를 업로드할 수 있습니다.
  • JSON 기반 형식은 그래프 내보내기에서 생성되며, 이 형식은 트윈, 관계 및/또는 모델을 포함할 수 있습니다.

Azure Digital Twins Explorer로 파일 가져오기

로컬 컴퓨터에 가져올 준비가 된 파일이 있으면 트윈 그래프 패널에서 그래프 가져오기 아이콘을 선택합니다.

표시되는 파일 선택기 상자에서 업로드할 그래프 파일(.xlsx 또는. json)로 이동하고 열기를 선택하여 업로드합니다.

Azure Digital Twins Explorer가 가져올 그래프의 미리 보기를 보여주는 가져오기 패널을 엽니다. 확인하려면 패널의 오른쪽 위 모서리에서 저장 아이콘을 선택합니다.

가져오기가 성공적으로 완료되면 모달 창에는 모델, 트윈 및 업로드된 관계의 수가 표시됩니다.

그래프 및 모델 내보내기

내보내기 기능을 사용하여 모델, 트윈 및 관계를 포함한 부분 또는 전체 그래프를 내보낼 수 있습니다. 내보내기는 최신 쿼리 결과의 트윈 및 관계 그리고 인스턴스의 모든 모델을 로컬 컴퓨터에 다운로드할 수 있는 JSON 기반 형식으로 직렬화합니다.

시작하려면 쿼리 탐색기 패널을 사용하여 다운로드하려는 트윈 및 관계를 선택하는 쿼리를 실행합니다. 쿼리 결과는 트윈 그래프 패널을 채우는 데 사용됩니다.

트윈 그래프 패널에 다운로드하려는 그래프 부분이 표시되면 그래프 내보내기 아이콘을 선택합니다.

그러면 트윈 그래프 상자에서 다운로드 링크가 활성화됩니다. 이를 선택하여 쿼리 결과의 JSON 기반 표현과 인스턴스의 모든 모델을 사용자 컴퓨터에 다운로드합니다.