Azure Digital Twins SDK 검토

완료됨

Microsoft는 다음과 같이 API를 다루는 Azure Digital Twins SDK를 개발했습니다.

  • 컨트롤 플레인 API: Azure Digital Twins 서비스를 구현하는 데 사용할 수 있는 리소스 관리 SDK입니다.
  • 데이터 평면 API: 디지털 트윈, 모델, 쿼리 및 이벤트 경로를 구현하는 데 사용할 수 있는 클라이언트 SDK입니다.

지원되는 프로그래밍 언어는 다음과 같습니다.

  • 컨트롤 플레인 API:
    • .NET (C#)
    • Java
    • JavaScript
    • Python
    • Go
  • 데이터 평면 API
    • .NET (C#)
    • Java
    • JavaScript
    • Python

SDK에 대한 GitHub 프로젝트 및 네임스페이스 설명서는 프로그래밍 언어별로 구성되어 있습니다. 예를 들어 .NET(C#) SDK 정보는 다음 위치에서 찾을 수 있습니다.

.NET용 GitHub 프로젝트에는 다음 작업을 보여주는 샘플 프로젝트가 포함되어 있습니다.

  • 클라이언트를 인스턴스화합니다.
  • 모델 만들기, 가져오기 및 제거
  • 디지털 트윈 만들기, 쿼리 및 삭제
  • 디지털 트윈의 구성 요소 가져오기 및 업데이트
  • 디지털 트윈 간의 관계 만들기, 가져오기 및 삭제
  • 디지털 트윈의 이벤트 경로 만들기, 가져오기 및 삭제
  • 디지털 트윈 및 디지털 트윈 구성 요소에 원격 분석 메시지 게시

Serialization 도우미

Serialization 도우미는 기본 정보에 대한 액세스를 위해 트윈 데이터를 신속하게 만들거나 역직렬화하기 위해 SDK 내에서 사용할 수 있는 도우미 함수입니다. 핵심 SDK 메서드는 기본적으로 트윈 데이터를 JSON으로 반환하기 때문에 이러한 도우미 클래스를 사용하여 트윈 데이터를 추가로 분석하는 것이 유용할 수 있습니다.

사용 가능한 도우미 클래스는 다음과 같습니다.

  • BasicDigitalTwin: 일반적으로 디지털 트윈의 핵심 데이터를 나타냅니다.
  • BasicDigitalTwinComponent: 일반적으로 BasicDigitalTwin의 Contents 속성에서 구성 요소를 나타냅니다.
  • BasicRelationship: 일반적으로 관계의 핵심 데이터를 나타냅니다.
  • DigitalTwinsJsonPropertyName: 사용자 지정 디지털 트윈 형식에 대한 JSON 직렬화 및 역직렬화에 사용할 문자열 상수를 포함합니다.

.NET(C#) SDK(데이터 평면) 코드 예제

SDK를 사용하는 코드를 개발하는 경우 프로젝트 내에 다음 NuGet 패키지의 최신 버전을 포함해야 합니다.

  • Azure.DigitalTwins.Core. 이 패키지는 .NET용 Azure Digital Twins SDK의 패키지입니다.
  • Azure.Identity. 이 라이브러리는 Azure에 대한 인증에 유용한 도구를 제공합니다.

다음 코드 샘플에서는 .NET SDK의 사용을 보여줍니다.

서비스에 대한 인증:

// Authenticate against the service and create a client
string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-hostName>";
var credential = new DefaultAzureCredential();
DigitalTwinsClient client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);

모델 업로드:

// 'client' is an instance of DigitalTwinsClient
// Read model file into string (not part of SDK)
string dtdl = new File.ReadAllText("MyModelFile.json");
await client.CreateModelsAsync(new[] { dtdl });

모델 나열:

// 'client' is a valid DigitalTwinsClient object

// Get a single model, metadata and data
Response<DigitalTwinsModelData> md1 = await client.GetModelAsync(id);
DigitalTwinsModelData model1 = md1.Value;

// Get a list of the metadata of all available models; print their display names and IDs
AsyncPageable<DigitalTwinsModelData> md2 = client.GetModelsAsync();
await foreach (DigitalTwinsModelData md in md2)
{
    Console.WriteLine($"Type name: {md.DisplayName}: {md.Id}");
}

// Get models and metadata for a model ID, including all dependencies (models that it inherits from, components it references)
AssyncPageable<DigitalTwinsModelData> md3 = client.GetModelsAsync(new GetModelsOptions { IncludeModelDefinition = true });

트윈 만들기:

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);

트윈 쿼리 및 결과 반복:

AsyncPageable<string> result = client.QueryAsync("Select * From DigitalTwins");
try
{
    await foreach(BasicDigitalTwin twin in result)
    {
        // You can include your own logic to print the result
        // The logic below prints the twin's ID and contents
        Console.WriteLine($"Twin ID: {twin.Id} \nTwin data");
        foreach (KeyValuePair<string, object> kvp in twin.Contents)
        {
            Console.WriteLine($"{kvp.Key}  {kvp.Value}");
        }
    }
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"Error {ex.Status}, {ex.ErrorCode}, {ex.Message}");
    throw;
}

디지털 트윈 역직렬화

언제든지 System.Text.Json 또는 Newtonsoft.Json 같은 선택한 JSON 라이브러리를 사용하여 트윈 데이터를 역직렬화할 수 있습니다. 트윈에 대한 기본 액세스의 경우 도우미 클래스를 사용하면 더 편리합니다.

또한 BasicDigitalTwin 도우미 클래스는 Dictionary<string, object>를 통해 트윈에 정의된 속성에 대한 액세스 권한을 제공합니다. 트윈의 속성을 나열하려면 다음을 사용할 수 있습니다.

BasicDigitalTwin twin;
Response<BasicDigitalTwin> twinResponse = await client.GetDigitalTwinAsync<BasicDigitalTwin>(twinId);
twin = twinResponse.Value;
Console.WriteLine($"Model id: {twin.Metadata.ModelId}");
foreach (string prop in twin.Contents.Keys)
{
    if (twin.Contents.TryGetValue(prop, out object value))
        Console.WriteLine($"Property '{prop}': {value}");
}

참고

BasicDigitalTwin은 ```System.Text.Json``` 특성을 사용합니다. BasicDigitalTwin을 DigitalTwinsClient와 함께 사용하려면 기본 생성자를 사용하여 클라이언트를 초기화해야 하며, serializer 옵션을 사용자 지정하려면 JsonObjectSerializer를 사용합니다.