Azure Digital Twins 모델 관리

아티클
10/03/2023

이 문서에서는 Azure Digital Twins 인스턴스에서 모델을 관리하는 방법을 설명합니다. 관리 작업에는 모델 업로드, 유효성 검사, 검색 및 삭제가 포함됩니다.

필수 조건

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

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

개발자 인터페이스

이 문서에서는 .NET(C#) SDK를 사용하여 다양한 관리 작업을 완료하는 방법을 중점적으로 설명합니다. Azure Digital Twins API 및 SDK에 설명된 다른 언어 SDK를 사용하여 이와 동일한 관리 호출을 만들 수도 있습니다.

이러한 작업을 완료하는 데 사용할 수 있는 다른 개발자 인터페이스는 다음과 같습니다.

시각화

Azure Digital Twins Explorer는 Azure Digital Twins 그래프의 데이터를 탐색하기 위한 시각적 도구입니다. 탐색기를 사용하여 모델, 쌍, 관계를 확인, 쿼리, 편집할 수 있습니다.

Azure Digital Twins Explorer 도구에 대한 자세한 내용은 Azure Digital Twins Explorer를 참조하세요. 해당 기능을 사용하는 방법에 대한 자세한 단계는 Azure Digital Twins Explorer 사용을 참조하세요.

시각화하면 다음과 같습니다.

모델 만들기

처음부터 사용자 고유의 모델을 만들거나 업계에서 사용할 수 있는 기존 온톨로지를 사용할 수 있습니다.

모델 작성

Azure Digital Twins에 대한 모델은 DTDL로 작성되고 JSON 파일로 저장됩니다. DTDL 문서 작성을 용이하게 하는 구문 유효성 검사 및 기타 기능을 제공하는 Visual Studio Code에 사용할 수 있는 DTDL 확장명도 있습니다.

병원에서 병실을 디지털로 표현하는 예를 생각해 보세요. 각 병실에는 손 씻기를 모니터링하는 스마트 비누 디스펜서와 병실 트래픽을 모니터링하는 센서가 포함되어 있습니다.

솔루션에 대한 첫 번째 단계는 병원의 양상을 나타내는 모델을 만드는 것입니다. 이 시나리오에서 병실은 다음과 같이 설명할 수 있습니다.

{
    "@id": "dtmi:com:contoso:PatientRoom;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Patient Room",
    "contents": [
      {
        "@type": "Property",
        "name": "visitorCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashPercentage",
        "schema": "double"
      },
      {
        "@type": "Relationship",
        "name": "hasDevices"
      }
    ]
  }

참고 항목

이는 모델을 정의하고 저장하는 JSON 파일에 대한 샘플 본문으로, 클라이언트 프로젝트의 일부로 업로드됩니다. 반면에 REST API 호출은 위에 있는 것과 같은 모델 정의의 배열을 사용하며 이 배열은 .NET SDK의 IEnumerable<string>에 매핑됩니다. 따라서 REST API에서 이 모델을 직접 사용하려면 대괄호로 묶습니다.

이 모델은 병실의 이름과 고유 ID, 방문자 수 및 손 씻기 상태를 나타내는 속성을 정의합니다. 이러한 카운터는 동작 센서와 스마트 비누 디스펜서에서 업데이트되며 함께 사용되어 handwash percentage 속성을 계산합니다. 또한 모델은 hasDevices 관계를 정의하며 이는 Room 모델을 기반으로 모든 디지털 트윈을 실제 디바이스에 연결하는 데 사용됩니다.

참고 항목

속성 및 관계에 대한 writable 특성과 관계에 대한 minMultiplicity 및 maxMultiplicity를 포함하여 현재 Azure Digital Twins에서 지원하지 않는 몇 가지 DTDL 기능이 있습니다. 자세한 내용은 서비스별 DTDL 참고 사항을 참조하세요.

이 메서드에 따라 병원의 병동, 구역 또는 병원 자체에 대한 모델을 정의할 수 있습니다.

업계 도메인을 설명하는 포괄적인 모델 집합을 빌드하는 것이 목표인 경우 모델을 더 쉽게 작성할 수 있는 기존 업계 온톨로지가 있는지 여부를 고려합니다. 다음 섹션에서는 업계 온톨로지의 자세한 내용을 설명합니다.

업계 표준 온톨로지 채택

온톨로지는 제조, 건물 구조, IoT 시스템, 스마트 도시, 에너지 그리드, 웹 콘텐츠 등과 같은 특정 영역을 포괄적으로 설명하는 모델 집합입니다.

솔루션이 특정 종류의 모델링 표준을 사용하는 특정 업계를 위한 것인 경우 모델을 처음부터 설계하는 대신 해당 업계용으로 설계된 기존 모델 집합으로 시작하는 것이 좋습니다. Microsoft는 도메인 전문가와 협력하여 업계 표준에 따라 DTDL 모델 온톨로지를 만들어 재창조를 최소화하고 업계 솔루션 전반에서 일관성과 간소화를 장려합니다. 온톨로지란?에서 온톨로지의 사용 방법 및 현재 사용할 수 있는 온톨로지를 포함하여 온톨로지에 대해 자세히 읽어볼 수 있습니다.

구문 유효성 검사

모델을 만든 후에는 Azure Digital Twins 인스턴스에 업로드하기 전에 오프라인으로 모델의 유효성을 검사하는 것이 좋습니다.

모델의 유효성을 검사하는 데 도움이 되도록 NuGet: DTDLParser에 .NET 클라이언트 측 DTDL 구문 분석 라이브러리가 제공됩니다. C# 코드에서 직접 파서 라이브러리를 사용할 수 있습니다. GitHub의 DTDLParserResolveSample에서 파서의 샘플 사용을 볼 수도 있습니다.

모델 업로드

모델을 만든 후에는 Azure Digital Twins 인스턴스에 업로드할 수 있습니다.

모델을 업로드할 준비가 되면 다음의 .NET SDK용 코드 조각을 사용할 수 있습니다.

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

업로드할 때 서비스에서 모델 파일의 유효성을 검사합니다.

일반적으로 둘 이상의 모델을 서비스에 업로드해야 합니다. 단일 트랜잭션에서 여러 모델을 한 번에 업로드할 수 있는 여러 가지 방법이 있습니다. 전략을 선택하는 데 도움이 되도록 이 섹션의 나머지 부분을 계속 진행하면서 모델 집합의 크기를 고려합니다.

작은 모델 집합 업로드

더 작은 모델 집합의 경우 개별 API 호출을 사용하여 한 번에 여러 모델을 업로드할 수 있습니다. Azure Digital Twins 제한에서 단일 API 호출에서 업로드할 수 있는 모델 수에 대한 현재 제한을 확인할 수 있습니다.

SDK를 사용하는 경우 다음과 같이 CreateModels 메서드를 사용하여 여러 모델 파일을 업로드할 수 있습니다.

var dtdlFiles = Directory.EnumerateFiles(sourceDirectory, "*.json");

var dtdlModels = new List<string>();
foreach (string fileName in dtdlFiles)
{
    // Read model file into string (not part of SDK)
    string dtdl = File.ReadAllText(fileName);
    dtdlModels.Add(dtdl);
}
await client.CreateModelsAsync(dtdlModels);

REST API 또는 Azure CLI를 사용하는 경우 함께 업로드할 여러 모델 정의를 단일 JSON 파일에 배치하여 여러 모델을 업로드할 수도 있습니다. 이 경우 모델은 다음 예와 같이 파일 내의 JSON 배열에 배치되어야 합니다.

[
    {
      "@id": "dtmi:com:contoso:Planet;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    },
    {
      "@id": "dtmi:com:contoso:Moon;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    }
]

가져오기 작업 API를 사용하여 대형 모델 집합 업로드

대형 모델 집합의 경우 가져오기 작업 API를 사용하여 단일 API 호출에서 여러 모델을 한 번에 업로드할 수 있습니다. API는 인스턴스에 있는 모델 수에 대해 Azure Digital Twins 한도까지 동시에 수락할 수 있으며, 필요한 경우 모델 간의 종속성을 확인하기 위해 모델을 자동으로 다시 정렬합니다. 이 방법을 사용하려면 모델 및 대량 작업을 위해 Azure Digital Twins 인스턴스에서 Azure Blob Storage와 쓰기 권한을 사용해야 합니다.

팁

또한 가져오기 작업 API를 사용하면 트윈과 관계를 동일한 호출로 가져와 한 번에 그래프의 모든 파트를 만들 수 있습니다. 이 프로세스에 대한 자세한 내용은 작업 가져오기 API를 사용하여 모델, 트윈 및 관계 대량 업로드를 참조하세요.

모델을 대량으로 가져오려면 모델(및 대량 가져오기 작업에 포함된 기타 리소스)을 NDJSON 파일로 구성해야 합니다. Models 섹션은 Header 섹션 바로 다음에 제공되므로 파일의 첫 번째 그래프 데이터 섹션이 됩니다. 작업 가져오기 API 소개에서 가져오기 파일 예와 이러한 파일을 만들기 위한 프로젝트 샘플을 볼 수 있습니다.

다음으로 파일을 Azure Blob Storage의 추가 Blob에 업로드해야 합니다. Azure Storage 컨테이너를 만드는 방법에 대한 지침은 컨테이너 만들기를 참조하세요. 그런 다음 기본 설정하는 업로드 방법(일부 옵션은 AzCopy 명령, Azure CLI 또는 Azure Portal)을 사용하여 파일을 업로드합니다.

NDJSON 파일이 컨테이너에 업로드되면 Blob 컨테이너 내에서 URL을 가져옵니다. 대량 가져오기 API 호출의 본문에서 나중에 이 값을 사용합니다.

다음은 Azure Portal에 있는 Blob 파일의 URL 값을 보여 주는 스크린샷입니다.

그런 다음 해당 파일을 Import Jobs API 호출에 사용할 수 있습니다. 입력 파일의 Blob Storage URL과 서비스에서 만들어질 때 출력 로그를 저장할 위치를 나타내는 새 Blob Storage URL을 제공합니다.

모델 검색

Azure Digital Twins 인스턴스에 저장된 모델을 나열하고 검색할 수 있습니다.

다음과 같은 선택 사항이 있습니다.

단일 모델 검색
모든 모델 검색
모델에 대한 메타데이터 및 종속성 검색

다음은 일부 예제 호출입니다.

// 'client' is a valid DigitalTwinsClient object

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

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

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

모델을 검색하는 SDK 호출은 모두 DigitalTwinsModelData 개체를 반환합니다. DigitalTwinsModelData는 이름, DTMI 및 모델 생성 날짜 등 Azure Digital Twins 인스턴스에 저장된 모델에 대한 메타데이터를 포함합니다. 경우에 따라 DigitalTwinsModelData 개체는 모델 자체를 포함하기도 합니다. 즉, 매개 변수에 따라 검색 호출을 사용하여 메타데이터만 검색하거나(예를 들어 사용 가능한 도구의 UI 목록을 표시하려는 경우에 유용) 전체 모델을 검색할 수 있습니다.

RetrieveModelWithDependencies 호출은 요청된 모델뿐만 아니라 요청된 모델이 종속된 모든 모델을 반환합니다.

모델이 업로드된 문서 양식으로 반드시 반환되는 것은 아닙니다. Azure Digital Twins는 반환 양식이 의미상 동일함을 보장합니다.

모델 업데이트

이 섹션에서는 모델 업데이트를 위한 고려 사항 및 전략에 대해 설명합니다.

업데이트 전: 전체 솔루션의 컨텍스트에서 생각합니다.

모델을 업데이트하기 전에 전체 솔루션과 수행하려는 모델 변경의 영향에 대해 전체적으로 생각하는 것이 좋습니다. Azure Digital Twins 솔루션의 모델은 종종 상호 연결되므로 한 모델을 업데이트하려면 다른 여러 모델을 업데이트해야 하는 계단식 변경을 인식하는 것이 중요합니다. 모델 업데이트는 모델을 사용하는 트윈에 영향을 미치며 수신 및 처리 코드, 클라이언트 애플리케이션 및 자동화된 보고서에도 영향을 미칠 수 있습니다.

다음은 모델 전환을 원활하게 관리하는 데 도움이 되는 몇 가지 권장 사항입니다.

모델을 별도의 엔터티로 생각하는 대신 모델과 해당 관계를 함께 최신 상태로 유지하기 위해 적절할 때 전체 모델 집합을 발전시키는 것을 고려합니다.
모델을 원본 코드처럼 취급하고 원본 제어에서 관리합니다. 솔루션의 다른 코드에 적용하는 것과 동일한 엄격함과 주의를 모델 및 모델 변경에 적용합니다.

모델 업데이트 프로세스를 계속할 준비가 되면 이 섹션의 나머지 부분에서 업데이트를 구현하는 데 사용할 수 있는 전략을 설명합니다.

모델 업데이트 전략

모델이 Azure Digital Twins 인스턴스에 업로드되면 모델 인터페이스는 변경할 수 없습니다. 즉, 기존의 모델 "편집"이 없습니다. Azure Digital Twins는 일치하는 모델이 이미 인스턴스에 있는 동안 동일한 정확한 모델의 다시 업로드를 허용하지 않습니다.

대신 displayName 또는 description 업데이트, 속성 추가 및 제거와 같이 모델을 변경하려면 원래 모델을 교체해야 합니다.

모델을 교체할 때 선택할 수 있는 두 가지 전략이 있습니다.

전략 1: 새 모델 버전 업로드: 새 버전 번호와 함께 모델을 업로드하고 해당 새 모델을 사용하도록 트윈을 업데이트합니다. 모델의 새 버전과 이전 버전은 모두 삭제할 때까지 인스턴스에 존재합니다.
- 이 모델을 사용하는 일부 트윈만 업데이트하려는 경우 또는 트윈이 모델을 준수하고 모델 전환을 통해 쓰기 가능한 상태를 유지하도록 하려는 경우에 이 전략을 사용합니다.
전략 2: 이전 모델을 삭제하고 다시 업로드: 원래 모델을 삭제하고 그 자리에 동일한 이름과 ID(DTMI 값)를 사용하여 새 모델을 업로드합니다. 기존 모델을 새 모델로 완전히 교체합니다.
- 모델에 반응하는 모든 코드 외에도 이 모델을 사용하는 모든 트윈을 한 번에 업데이트하려는 경우 이 전략을 사용합니다. 모델 업데이트에 모델 업데이트의 호환성이 손상되는 변경이 포함된 경우 트윈은 이전 모델에서 새 모델로 전환하는 동안 잠시 동안 해당 모델을 준수하지 않습니다. 즉, 새 모델이 업로드되고 트윈이 모델을 준수할 때까지 업데이트를 수행하지 못합니다.

참고 항목

개발 외에는 모델을 호환성이 손상되는 변경을 만들지 않는 것이 좋습니다.

각 전략 옵션에 대해 자세히 알아보려면 다음 섹션을 계속하세요.

전략 1: 새 모델 버전 업로드

이 옵션에는 모델의 새 버전을 만들고 인스턴스에 업로드하는 작업이 포함됩니다.

이 작업은 이전 버전의 모델을 덮어쓰지 않으므로 제거하기 전에는 여러 버전의 모델이 인스턴스에 공존하게 됩니다. 새 모델 버전과 이전 모델 버전이 공존하므로 트윈은 모델의 새 버전이나 이전 버전을 사용할 수 있습니다. 즉, 새 버전의 모델을 업로드해도 기존 트윈에 자동으로 영향을 미치지 않습니다. 기존 트윈은 이전 모델 버전의 인스턴스로 유지되며 이러한 트윈을 패치하여 새 모델 버전으로 업데이트할 수 있습니다.

이 전략을 사용하려면 아래 단계를 따르세요.

1. 새 모델 버전 만들기 및 업로드

기존 모델의 새 버전을 만들려면 원래 모델의 DTDL로 시작합니다. 변경할 필드를 업데이트, 추가 또는 제거합니다.

그런 다음 모델의 id 필드를 업데이트하여 이 모델을 최신 버전의 모델로 이 모델을 표시합니다. ; 뒤에 있는 모델 ID의 마지막 섹션은 모델 번호를 나타냅니다. 이제 이 모델의 더 업데이트된 버전임을 나타내려면 id 값의 끝에 있는 숫자를 현재 버전 번호보다 큰 숫자로 증분합니다.

예를 들어 이전 모델 ID가 다음과 같았다면

"@id": "dtmi:com:contoso:PatientRoom;1",

이 모델의 버전 2는 다음과 같습니다.

"@id": "dtmi:com:contoso:PatientRoom;2",

그런 다음 새 버전의 모델을 인스턴스에 업로드합니다.

그러면 이 버전의 모델이 인스턴스에 제공되어 디지털 트윈에 사용할 수 있습니다. 이전 버전의 모델을 덮어쓰지 않으므로 이제 여러 버전의 모델이 인스턴스에 공존하게 됩니다.

2. 필요에 따라 그래프 요소 업데이트

그런 다음 인스턴스의 트윈 및 관계를 업데이트하여 이전 모델 버전 대신 새 모델 버전을 사용합니다.

다음 지침에 따라 트윈을 업데이트하고 관계를 업데이트할 수 있습니다. 트윈 모델을 업데이트하기 위한 패치 작업은 다음과 같습니다.

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

Important

트윈을 업데이트할 때 동일한 패치를 사용하여 모델 ID(새 버전) 및 새 모델에 맞게 변경해야 하는 트윈의 모든 필드를 둘 다 업데이트합니다.

또한 이 모델을 참조하는 인스턴스의 관계 및 기타 모델을 업데이트하여 새 모델 버전을 참조하도록 해야 할 수도 있습니다. 이 목적을 달성하려면 다른 모델 업데이트 작업을 수행해야 하므로 이 섹션의 시작 부분으로 돌아가 업데이트가 필요한 모델에 대해 프로세스를 반복합니다.

3. (선택사항) 이전 모델 버전 서비스 해제 또는 삭제

이전 모델 버전을 더 이상 사용하지 않을 경우 이전 모델을 서비스 해제할 수 있습니다. 이 작업을 통해 모델이 인스턴스에 기존 상태를 유지할 수 있지만 새 디지털 트윈을 만드는 데 사용할 수는 없습니다.

인스턴스에서 더 이상 원하지 않는 경우 이전 모델을 완전히 삭제할 수도 있습니다.

위에 링크된 섹션에는 모델 서비스 해제 및 삭제에 대한 코드 예와 고려 사항이 포함되어 있습니다.

전략 2: 이전 모델 삭제 및 다시 업로드

모델의 버전을 높이는 대신 모델을 완전히 삭제하고 편집된 모델을 인스턴스에 다시 업로드할 수 있습니다.

Azure Digital Twins는 이전 모델이 업로드된 적이 있는지 기억하지 않으므로 이 작업은 완전히 새로운 모델을 업로드하는 것과 같습니다. 모델을 사용하는 트윈은 사용 가능한 새 정의로 자동 전환됩니다. 새 정의가 이전 정의와 어떻게 다른지에 따라 이러한 트윈에는 삭제된 정의와 일치하고 새 정의와 유효하지 않은 속성 및 관계가 있을 수 있으므로 유효한 상태를 유지하기 위해 패치해야 할 수 있습니다.

이 전략을 사용하려면 아래 단계를 따르세요.

1. 이전 모델 삭제

Azure Digital Twins는 동일한 ID를 가진 두 모델을 허용하지 않으므로 인스턴스에서 원래 모델을 삭제하여 시작합니다.

참고 항목

이 모델에 의존하는 다른 모델이 있는 경우(상속 또는 구성 요소를 통해) 모델을 삭제하기 전에 해당 참조를 제거해야 합니다. 이러한 종속 모델을 먼저 업데이트하여 참조를 일시적으로 제거하거나 종속 모델을 삭제하고 이후 단계에서 다시 업로드할 수 있습니다.

다음 지침에 따라 원래 모델을 삭제합니다. 이 작업을 수행하면 해당 모델을 사용하던 트윈이 더 이상 존재하지 않는 모델을 사용하고 있기 때문에 일시적으로 "분리됨" 상태가 됩니다. 이 상태는 업데이트된 모델을 다시 업로드할 때 다음 단계에서 복구됩니다.

2. 새 모델 만들기 및 업로드

원래 모델의 DTDL로 시작합니다. 변경할 필드를 업데이트, 추가 또는 제거합니다.

그런 다음 처음으로 업로드되는 새 모델인 것처럼 인스턴스에 모델을 업로드합니다.

3. 필요에 따라 그래프 요소 업데이트

이제 새 모델이 이전 모델 대신 업로드되었으므로 인스턴스의 캐싱이 만료되고 재설정되면 그래프의 트윈이 자동으로 새 모델 정의를 사용하기 시작합니다. 이 프로세스는 그래프 크기에 따라 10~15분 이상 걸릴 수 있습니다. 그 후에는 모델의 새 속성과 변경된 속성에 액세스할 수 있어야 하며 제거된 속성은 더 이상 액세스할 수 없습니다.

참고 항목

원래 모델을 삭제하기 위해 이전에 다른 종속 모델을 제거한 경우 캐시가 재설정된 후 지금 다시 업로드합니다. 원본 모델에 대한 참조를 일시적으로 제거하기 위해 종속 모델을 업데이트한 경우 참조를 되돌리기 위해 다시 업데이트할 수 있습니다.

그런 다음 해당 속성이 새 모델에서 정의한 속성과 일치하도록 인스턴스의 트윈 및 관계를 업데이트합니다. 이 단계가 완료되기 전에 해당 모델과 일치하지 않는 트윈은 여전히 읽을 수 있지만 쓸 수는 없습니다. 유효한 모델이 없는 트윈의 상태에 대한 자세한 내용은 모델이 없는 트윈을 참조하세요.

새 모델에 대한 트윈과 관계를 업데이트하여 다시 쓸 수 있도록 하는 방법에는 두 가지가 있습니다.

필요에 따라 트윈 및 관계를 패치하여 새 모델에 맞도록 합니다. 다음 지침에 따라 트윈을 업데이트하고 관계를 업데이트할 수 있습니다.
- 속성을 추가한 경우: 새 값이 누락된 트윈은 여전히 유효한 트윈이므로 새 값을 갖도록 트윈 및 관계를 업데이트할 필요가 없습니다. 그러나 새 속성에 대한 값을 추가하려는 경우 패치할 수 있습니다.
- 속성을 제거한 경우: 새 모델에서 현재 유효하지 않은 속성을 제거하려면 트윈을 패치해야 합니다.
- 속성을 업데이트한 경우: 새 모델에서 유효하도록 변경된 속성 값을 업데이트하려면 트윈을 패치해야 합니다.
모델을 사용하는 트윈 및 관계를 삭제하고 다시 만듭니다. 다음 지침에 따라 트윈 삭제 및 트윈 다시 만들기, 관계 삭제 및 관계 다시 만들기를 수행할 수 있습니다.
- 모델을 많이 변경하고 기존 트윈을 일치하도록 업데이트하기 어려운 경우 이 작업을 수행할 수 있습니다. 그러나 많은 관계로 상호 연결된 많은 트윈이 있는 경우 다시 만드는 것이 복잡할 수 있습니다.

모델 제거

모델은 다음 두 가지 방법 중 하나로 서비스에서 제거될 수 있습니다.

해제: 모델이 해제되면 더 이상 새 디지털 트윈을 만드는 데 사용할 수 없습니다. 이미 이 모델을 사용하는 기존 디지털 트윈은 영향을 받지 않으므로 속성 변경, 관계 추가 또는 삭제 등으로 업데이트할 수 있습니다.
삭제: 이 작업은 솔루션에서 모델을 완전히 제거합니다. 이 모델을 사용 중이었던 모든 트윈은 더 이상 유효한 모델과 연결되지 않으므로 모델이 전혀 없는 것처럼 처리됩니다. 여전히 이러한 트윈을 읽을 수는 있지만 다른 모델에 다시 할당될 때까지 업데이트를 수행할 수 없습니다.

이러한 작업은 개별 기능이며 서로에게 영향을 주지 않지만 모델을 점진적으로 제거하는 데 함께 사용할 수 있습니다.

참고 항목

인스턴스의 모든 모델, 트윈 및 관계를 한 번에 삭제하려면 작업 삭제 API를 사용합니다.

서비스 해제

모델을 서비스 해제하려면 SDK에서 DecommissionModel 메서드를 사용할 수 있습니다.

// 'client' is a valid DigitalTwinsClient
await client.DecommissionModelAsync(dtmiOfPlanetInterface);
// Write some code that deletes or transitions digital twins
//...

REST API 호출 DigitalTwinModels Update를 사용하여 모델을 서비스 해제할 수도 있습니다. decommissioned 속성은 이 API 호출로 바꿀 수 있는 유일한 속성입니다. JSON 패치 문서는 다음과 같습니다.

[
  {
    "op": "replace",
    "path": "/decommissioned",
    "value": true
  }
]

모델의 서비스 해제 상태는 모델 검색 API에서 반환하는 ModelData 레코드에 포함됩니다.

삭제

인스턴스의 모든 모델을 한 번에 삭제하거나 개별적으로 수행할 수 있습니다.

모든 모델을 동시에 삭제하는 방법의 예는 GitHub의 Azure Digital Twins용 엔드투엔드 샘플 리포지토리를 참조하세요. CommandLoop.cs 파일에는 인스턴스의 모든 모델을 삭제하는 코드가 포함된 CommandDeleteAllModels 함수가 포함되어 있습니다.

개별 모델을 삭제하려면 이 섹션의 나머지 부분에 있는 지침과 고려 사항을 따릅니다.

삭제 전: 삭제 요구 사항

일반적으로 모델은 언제든지 삭제할 수 있습니다.

다른 모델이 extends 관계 또는 구성 요소로 종속된 모델은 예외입니다. 예를 들어 ConferenceRoom 모델이 Room 모델을 확장하고 ACUnit 모델을 구성 요소로 포함하는 경우 ConferenceRoom이 해당 참조를 제거할 때까지 Room 또는 ACUnit을 삭제할 수 없습니다.

종속 모델을 업데이트하여 종속성을 제거하거나 종속 모델을 완전히 삭제하여 수행할 수 있습니다.

삭제 중: 삭제 프로세스

모델이 즉시 삭제하는 요구 사항을 충족하는 경우에도 남아 있는 트윈에 의도하지 않은 결과가 발생하지 않도록 몇 가지 단계를 수행하는 것이 좋습니다. 다음은 프로세스 관리에 도움이 되는 몇 가지 단계입니다.

먼저 모델을 서비스 해제합니다.
서비스에서 서비스를 해제하기 전에 전송된 마지막 순간 트윈 생성 요청을 처리했는지 확인할 수 있도록 몇 분 정도 기다립니다.
모델별로 트윈을 쿼리하여 현재 서비스 해제된 모델을 사용하는 모든 트윈을 확인합니다.
더 이상 필요하지 않은 경우 트윈을 삭제하거나 필요한 경우 새 모델에 패치합니다. 그대로 둘 수도 있으며 이 경우 모델이 삭제되고 나면 모델 없는 트윈이 됩니다. 이 상태의 의미에 대해서는 다음 섹션을 참조하세요.
몇 분 후에 변경 내용이 적용되었는지 확인합니다.
모델 삭제

모델을 삭제하려면 DeleteModel SDK 호출을 사용할 수 있습니다.

// 'client' is a valid DigitalTwinsClient
await client.DeleteModelAsync(IDToDelete);

DigitalTwinModels Delete REST API 호출을 사용하여 모델을 삭제할 수도 있습니다.

삭제 후: 모델 없는 트윈

모델을 삭제한 후에는 모델을 사용하던 모든 디지털 트윈이 이제 모델이 없는 것으로 간주됩니다. 이 상태의 모든 트윈 목록을 제공할 수 있는 쿼리가 없습니다. 그러나 영향을 받는 트윈을 확인하기 위해 삭제된 모델을 기준으로 트윈을 쿼리할 수 있습니다.

다음은 모델이 없는 트윈으로 수행할 수 있는 작업과 수행할 수 없는 작업에 대한 개요입니다.

수행할 수 있는 작업:

트윈 쿼리
속성 읽기
나가는 관계 읽기
들어오는 관계 추가 및 삭제(다른 트윈은 여전히 이 트윈으로의 관계를 형성할 수 있음)
- 관계 정의의 target은 삭제된 모델의 DTMI를 계속 반영할 수 있습니다. 정의된 대상이 없는 관계도 여기서 작동할 수 있습니다.
관계 삭제
트윈 삭제

수행할 수 없는 작업:

나가는 관계 편집(이 트윈에서 다른 트윈으로의 관계)
속성 편집

삭제 후: 모델 다시 업로드

모델을 삭제한 후 나중에 삭제한 모델과 동일한 ID를 사용하여 새 모델을 업로드하도록 결정할 수 있습니다. 이 경우 다음과 같은 상황이 발생합니다.

솔루션 저장소의 관점에서 이 작업은 완전히 새로운 모델을 업로드하는 것과 같습니다. 서비스는 이전에 업로드된 적이 있는지 기억하지 않습니다.
삭제된 모델을 참조하는 그래프에 남아 있는 트윈이 있으면 더 이상 분리되지 않습니다. 새 정의에서 이 모델 ID를 다시 사용할 수 있습니다. 그러나 모델에 대한 새 정의가 삭제된 모델 정의와 다를 경우 이러한 트윈은 삭제된 정의와 일치하고 새 정의에는 맞지 않는 속성 및 관계를 가질 수 있습니다.

Azure Digital Twins는 이 상태를 방지하지 않으므로 모델 정의 스위치를 통해 유효하게 유지할 수 있도록 적절하게 트윈을 패치해야 합니다.

v2 모델을 v3로 변환

Azure Digital Twins는 DTDL 버전 2와 3을 지원합니다(설명서에서 각각 v2 및 v3로 단축됨). V3는 확장된 기능에 따라 권장되는 선택입니다. 이 섹션에서는 기존 DTDL v2 모델을 DTDL v3로 업데이트하는 방법을 설명합니다.

컨텍스트를 업데이트합니다. 모델을 v2 또는 v3로 식별하는 주요 기능은 인터페이스의 @context 필드입니다. 모델을 v2에서 v3로 변환하려면 dtmi:dtdl:context;2 컨텍스트 값을 dtmi:dtdl:context;3로 변경합니다. 많은 모델의 경우 이 변경이 유일한 필수 변경입니다.
1. v2의 값: "@context": "dtmi:dtdl:context;2"
2. v3의 값: "@context": "dtmi:dtdl:context;3".
필요한 경우 의미 체계 형식을 업데이트합니다. DTDL v2에서는 의미 체계 형식이 기본적으로 지원됩니다. DTDL v3에서는 QuantitativeTypes 기능 확장에 포함됩니다. 따라서 v2 모델이 의미 체계 형식을 사용하는 경우 모델을 v3로 변환할 때 기능 확장을 추가해야 합니다. 이렇게 하려면 먼저 인터페이스의 @context 필드를 단일 값에서 값 배열로 변경한 다음, dtmi:dtdl:extension:quantitativeTypes;1 값을 추가합니다.
1. v2의 값: "@context": "dtmi:dtdl:context;2"
2. v3의 값: "@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:quantitativeTypes;1"]
필요한 경우 크기 제한을 고려합니다. V2와 v3는 크기 제한이 다르므로 인터페이스가 매우 큰 경우 DTDL v2와 v3 간의 차이점에서 제한을 검토할 수 있습니다.

이러한 변경 후 이전 DTDL v2 모델이 DTDL v3 모델로 변환되었습니다.

또한 배열 형식 속성, 버전 완화, 추가 기능 확장과 같은 DTDL v3의 새로운 기능을 고려하여 이러한 기능이 도움이 되는 추가 기능인지 확인할 수도 있습니다. DTDL v2와 v3 간의 차이점에 대한 전체 목록은 DTDL v3 언어 설명의 버전 2에서 변경 내용을 참조하세요.

다음 단계

모델을 기반으로 디지털 트윈을 만들고 관리하는 방법을 참조하세요.

디지털 트윈 관리

Azure Digital Twins 모델 관리

필수 조건

개발자 인터페이스

시각화

모델 만들기

모델 작성

업계 표준 온톨로지 채택

구문 유효성 검사

모델 업로드

작은 모델 집합 업로드

가져오기 작업 API를 사용하여 대형 모델 집합 업로드

모델 검색

모델 업데이트

업데이트 전: 전체 솔루션의 컨텍스트에서 생각합니다.

모델 업데이트 전략

전략 1: 새 모델 버전 업로드

1. 새 모델 버전 만들기 및 업로드

2. 필요에 따라 그래프 요소 업데이트

3. (선택사항) 이전 모델 버전 서비스 해제 또는 삭제

전략 2: 이전 모델 삭제 및 다시 업로드

1. 이전 모델 삭제

2. 새 모델 만들기 및 업로드

3. 필요에 따라 그래프 요소 업데이트

모델 제거

서비스 해제

삭제

삭제 전: 삭제 요구 사항

삭제 중: 삭제 프로세스

삭제 후: 모델 없는 트윈

삭제 후: 모델 다시 업로드

v2 모델을 v3로 변환

다음 단계

추가 리소스