Azure Digital Twins 데이터 기록(Azure Data Explorer 사용)

아티클
02/26/2024

데이터 기록은 Azure Digital Twins의 통합 기능입니다. 그래프 업데이트가 Azure Data Explorer에 자동으로 기록되도록 Azure Digital Twins 인스턴스를 Azure Data Explorer 클러스터에 연결할 수 있습니다. 이러한 기록 업데이트에는 트윈 속성 업데이트, 트윈 수명 주기 이벤트 및 관계 수명 주기 이벤트가 포함됩니다.

그래프 업데이트가 Azure Data Explorer에 기록되면 Azure Data Explorer용 Azure Digital Twins 플러그 인을 사용하여 공동 쿼리를 실행하여 Digital Twins, 그 관계 및 시계열 데이터를 추론할 수 있습니다. 이는 과거의 그래프 상태를 되돌아보거나 모델링된 환경의 동작에 대한 인사이트를 얻는 데 사용할 수 있습니다. 또한 이러한 쿼리를 사용하여 운영 대시보드를 구동하고, 2D 및 3D 웹 애플리케이션을 보강하고, 몰입형 증강/혼합 현실 환경을 구동하여 Azure Digital Twins에서 모델링된 자산, 프로세스 및 사용자의 현재 및 과거 상태를 전달할 수 있습니다.

빠른 데모를 포함하여 데이터 기록의 소개에 대한 자세한 내용을 보려면 다음 IoT 쇼 동영상을 시청하세요.

데이터 기록에서 내보낸 메시지는 메시지 가격 책정 차원에 계량화됩니다.

필수 구성 요소: 리소스 및 권한

데이터 기록에는 다음 리소스가 필요합니다.

시스템 할당 관리 ID를 사용하는 Azure Digital Twins 인스턴스.
이벤트 허브가 포함된 Event Hubs 네임스페이스
데이터베이스가 포함된 Azure Data Explorer 클러스터 클러스터에는 공용 네트워크 액세스가 사용하도록 설정되어 있어야 합니다.

이러한 리소스는 다음 흐름에 연결됩니다.

Diagram showing the flow of device telemetry data into Azure Digital Twins, through an event hub, to Azure Data Explorer.

디지털 트윈 그래프가 업데이트되면 정보는 이벤트 허브를 통해 대상 Azure Data Explorer 클러스터로 전달됩니다. 여기서 Azure Data Explorer는 데이터를 해당 테이블의 타임스탬프 레코드로 저장합니다.

데이터 기록 작업 시 API의 2023-01-31 버전 이상을 사용하는 것이 좋습니다. 2022-05-31 버전에서는 트윈 속성(트윈 수명 주기 또는 관계 수명 주기 이벤트 아님)만 기록할 수 있습니다. 이전 버전에서는 데이터 기록을 사용할 수 없습니다.

필요한 사용 권한

데이터 기록 연결을 설정하려면 Azure Digital Twins 인스턴스에 Event Hubs 및 Azure Data Explorer 리소스에 액세스할 수 있는 다음 권한이 있어야 합니다. 이러한 역할을 통해 Azure Digital Twins는 사용자 대신 이벤트 허브 및 Azure Data Explorer 데이터베이스를 구성할 수 있습니다(예: 데이터베이스에 테이블 만들기). 이러한 권한은 데이터 기록이 설정된 후 선택적으로 제거할 수 있습니다.

Event Hubs 리소스: Azure Event Hubs 데이터 소유자
Azure Data Explorer 클러스터: 기여자(전체 클러스터 또는 특정 데이터베이스로 범위 지정)
Azure Data Explorer 데이터베이스 보안 주체 할당: 관리자(사용 중인 데이터베이스로 범위 지정)

나중에 데이터 기록이 사용되는 동안 Azure Digital Twins 인스턴스에 Event Hubs 리소스에 대한 다음과 같은 권한이 있어야 합니다. Azure Event Hubs 데이터 발신자(데이터 기록 설정에서 Azure Event Hubs 데이터 소유자를 유지하도록 선택할 수도 있음).

이러한 권한은 Azure CLI 또는 Azure Portal을 사용하여 할당할 수 있습니다.

데이터 기록과 관련된 리소스(Azure Digital Twins 인스턴스, 이벤트 허브 또는 Azure Data Explorer 클러스터)에 대한 네트워크 액세스를 제한하려면 데이터 기록 연결을 설정한 후에 해당 제한 사항을 설정해야 합니다. 이 프로세스에 대한 자세한 내용은 데이터 기록 리소스에 대한 네트워크 액세스 제한을 참조하세요.

데이터 기록 연결 만들기 및 관리

이 섹션에는 데이터 기록 연결을 만들고, 업데이트하고, 삭제하기 위한 정보가 포함되어 있습니다.

데이터 기록 연결 만들기

모든 리소스 및 권한이 설정되면 Azure CLI, Azure Portal 또는 Azure Digital Twins SDK를 사용하여 해당 리소스와 권한 사이에 데이터 기록 연결을 만들 수 있습니다. CLI 명령 집합은 az dt data-history입니다.

이 명령은 기본 이름 또는 제공한 사용자 지정 이름을 사용할 수 있는 기록된 트윈 속성 이벤트에 대한 테이블을 항상 만듭니다. 트윈 속성 삭제는 선택적으로 이 테이블에 포함될 수 있습니다. 또한 관계 수명 주기 이벤트 및 트윈 수명 주기 이벤트에 대한 테이블 이름을 제공할 수 있으며 명령은 해당 이벤트 유형을 기록하기 위해 해당 이름으로 테이블을 만듭니다.

데이터 기록 연결을 설정하는 방법에 대한 단계별 지침은 데이터 기록 연결 만들기를 참조하세요.

여러 Azure Digital Twins 인스턴스의 기록

원하는 경우 여러 Azure Digital Twins 인스턴스가 동일한 Azure Data Explorer 클러스터에 대한 업데이트를 기록하도록 할 수 있습니다.

각 Azure Digital Twins 인스턴스에는 동일한 Azure Data Explorer 클러스터를 대상으로 하는 자체 데이터 기록 연결이 있습니다. 클러스터 내에서 인스턴스는 다음 중 하나로 트윈 데이터를 보낼 수 있습니다.

Azure Data Explorer 클러스터의 개별 테이블 집합.
Azure Data Explorer 클러스터의 동일한 테이블 집합. 이렇게 하려면 데이터 기록 연결을 만드는 동안 동일한 Azure Data Explorer 테이블 이름을 지정합니다. 데이터 기록 테이블 스키마에서 각 테이블의 ServiceId 열에는 원본 Azure Digital Twins 인스턴스의 URL이 포함되므로 이 필드를 사용하여 공유 테이블에서 각 레코드를 내보낸 Azure Digital Twins 인스턴스를 확인할 수 있습니다.

속성 전용 데이터 기록 연결 업데이트

2023년 2월 이전에는 데이터 기록 기능이 기록된 트윈 속성 업데이트만 제공합니다. 해당 시간부터 속성 전용 데이터 기록 연결이 있는 경우 Azure Data Explorer에 대한 모든 그래프 업데이트(트윈 속성, 트윈 수명 주기 이벤트 및 관계 수명 주기 이벤트 포함)를 기록하도록 연결을 업데이트할 수 있습니다.

이렇게 하려면 새로운 형식의 기록된 업데이트(트윈 수명 주기 이벤트 및 관계 수명 주기 이벤트)를 위해 Azure Data Explorer 클러스터에 새 테이블을 만들어야 합니다. 트윈 속성 이벤트의 경우 앞으로 트윈 속성 업데이트를 저장하기 위해 원래 데이터 기록 연결의 동일한 테이블을 사용하여 새 연결을 계속할지 또는 새 연결이 완전히 새로운 테이블 집합을 사용하도록 할지 결정할 수 있습니다. 그런 다음 기본 설정에 따라 아래 지침을 따릅니다.

트윈 속성 업데이트에 기존 테이블을 계속 사용하려는 경우:데이터 기록 연결 만들기의 지침을 사용하여 새 기능으로 새 데이터 기록 연결을 만듭니다. 데이터 기록 연결 이름은 원래 이름과 동일하거나 다른 이름일 수 있습니다. 매개 변수 옵션을 사용하여 두 개의 새 이벤트 유형 테이블에 새 이름을 제공하고 트윈 속성 업데이트 테이블에 원래 테이블 이름을 전달합니다. 새 연결은 이전 연결을 재정의하고 향후 기록 트윈 속성 업데이트를 위해 원래 테이블을 계속 사용합니다.

모든 새 테이블을 사용하려는 경우: 먼저 원래 데이터 기록 연결을 삭제합니다. 그런 다음 데이터 기록 연결 만들기의 지침에 따라 새 기능으로 새 데이터 기록 연결을 만듭니다. 데이터 기록 연결 이름은 원래 이름과 동일하거나 다른 이름일 수 있습니다. 세 가지 이벤트 유형 테이블 모두에 새 이름을 제공하려면 매개 변수 옵션을 사용합니다.

데이터 기록 연결 삭제

Azure CLI, Azure Portal 또는 Azure Digital Twins API 및 SDK를 사용하여 데이터 기록 연결을 삭제할 수 있습니다. CLI 명령은 az dt data-history connection delete입니다.

연결을 삭제하면 데이터 기록 연결과 관련된 리소스를 정리하는 옵션도 제공됩니다(CLI 명령의 경우 추가할 선택적 매개 변수는 --clean true임). 이 옵션을 사용하는 경우 이 명령은 데이터베이스에 대한 데이터 연결 및 테이블과 연결된 수집 매핑을 포함하여 클러스터를 이벤트 허브에 연결하는 데 사용되는 Azure Data Explorer 내의 리소스를 삭제합니다. "리소스 정리" 옵션은 데이터 기록 연결에 사용된 실제 이벤트 허브 및 Azure Data Explorer 클러스터를 삭제하지 않습니다.

정리는 최선의 시도이며 명령을 실행하는 계정에 이러한 리소스에 대한 삭제 권한이 있어야 합니다.

참고 항목

동일한 이벤트 허브 또는 Azure Data Explorer 클러스터를 공유하는 여러 데이터 기록 연결이 있는 경우 이러한 연결 중 하나를 삭제하는 동안 "리소스 정리" 옵션을 사용하면 이러한 리소스에 의존하는 다른 데이터 기록 연결이 중단될 수 있습니다.

데이터 형식 및 스키마

데이터 기록은 관계 수명 주기 이벤트, 트윈 수명 주기 이벤트 및 트윈 속성 업데이트(선택적으로 트윈 속성 삭제를 포함할 수 있음)라는 세 가지 형식의 이벤트를 Azure Digital Twins 인스턴스에서 Azure Data Explorer로 기록합니다. 이러한 각 이벤트 유형은 Azure Data Explorer 데이터베이스 내의 자체 테이블에 저장됩니다. 즉, 데이터 기록은 총 3개의 테이블을 유지합니다. 데이터 기록 연결을 설정할 때 테이블의 사용자 지정 이름을 지정할 수 있습니다.

이 섹션의 나머지 부분에서는 각 테이블의 데이터 스키마를 포함하여 세 개의 Azure Data Explorer 테이블에 대해 자세히 설명합니다.

트윈 속성 업데이트

트윈 속성 업데이트를 위한 Azure Data Explorer 테이블의 기본 이름은 AdtPropertyEvents입니다. 연결을 만들 때 기본 이름을 그대로 두거나 사용자 지정 표 이름을 지정할 수 있습니다.

트윈 속성 업데이트에 대한 시계열 데이터는 다음 스키마와 함께 저장됩니다.

Attribute	Type	설명
`TimeStamp`	DateTime	Azure Digital Twins에서 속성 업데이트 메시지를 처리한 날짜/시간입니다. 이 필드는 시스템에서 설정하며 사용자가 쓸 수 없습니다.
`SourceTimeStamp`	DateTime	현실 세계에서 속성 업데이트가 관찰되었을 때 타임스탬프를 나타내는 선택적인 쓰기 가능한 속성입니다. 이 속성은 Azure Digital Twins API/SDK의 2022-05-31 버전을 사용해서만 작성할 수 있으며 값은 ISO 8601 날짜 및 시간 형식을 준수해야 합니다. 이 속성을 업데이트하는 방법에 대한 자세한 내용은 속성의 sourceTime 업데이트를 참조하세요.
`ServiceId`	문자열	레코드를 로그하는 Azure IoT 서비스의 서비스 인스턴스 ID
`Id`	문자열	트윈 ID
`ModelId`	문자열	DTDL 모델 ID(DTMI)
`Key`	문자열	업데이트된 속성의 이름
`Value`	동적	업데이트된 속성의 값
`RelationshipId`	문자열	관계(트윈 또는 디바이스와 반대)에 정의된 속성이 업데이트되면 이 필드는 관계의 ID로 채워집니다. 트윈 속성이 업데이트되면 이 필드는 비어 있습니다.
`RelationshipTarget`	문자열	관계(트윈 또는 디바이스와 반대)에 정의된 속성이 업데이트되면 이 필드는 관계가 대상으로 하는 트윈의 트윈 ID로 채워집니다. 트윈 속성이 업데이트되면 이 필드는 비어 있습니다.
`Action`	문자열	이 열은 속성 삭제 이벤트를 기록하도록 선택한 경우에만 존재합니다. 그렇다면 이 열에는 트윈 속성 이벤트 형식(업데이트 또는 삭제)이 포함됩니다.

다음은 Azure Data Explorer에 저장된 트윈 속성 업데이트의 예제 테이블입니다.

`TimeStamp`	`SourceTimeStamp`	`ServiceId`	`Id`	`ModelId`	`Key`	`Value`
2022-12-15 20:23:29.8697482	2022-12-15 20:22:14.3854859	dairyadtinstance.api.wcus.digitaltwins.azure.net	PasteurizationMachine_A01	`dtmi:assetGen:PasteurizationMachine;1`	출력	130
2022-12-15 20:23:39.3235925	2022-12-15 20:22:26.5837559	dairyadtinstance.api.wcus.digitaltwins.azure.net	PasteurizationMachine_A01	`dtmi:assetGen:PasteurizationMachine;1`	출력	140
2022-12-15 20:23:47.078367	2022-12-15 20:22:34.9375957	dairyadtinstance.api.wcus.digitaltwins.azure.net	PasteurizationMachine_A01	`dtmi:assetGen:PasteurizationMachine;1`	출력	130
2022-12-15 20:23:57.3794198	2022-12-15 20:22:50.1028562	dairyadtinstance.api.wcus.digitaltwins.azure.net	PasteurizationMachine_A01	`dtmi:assetGen:PasteurizationMachine;1`	출력	123

여러 필드가 포함된 속성 표시

여러 필드를 사용하여 속성을 저장해야 할 수 있습니다. 이러한 속성은 스키마의 Value 특성에서 JSON 개체로 표시됩니다.

예를 들어 롤, 피치 및 요에 대한 3개의 필드가 있는 속성을 나타내는 경우 데이터 기록은 JSON 개체 {"roll": 20, "pitch": 15, "yaw": 45}를 Value로 저장합니다.

트윈 수명 주기 이벤트

트윈 수명 주기 이벤트에 대한 Azure Data Explorer 테이블에는 데이터 기록 연결을 만들 때 지정하는 사용자 지정 이름이 있습니다.

트윈 수명 주기 이벤트에 대한 시계열 데이터는 다음 스키마와 함께 저장됩니다.

Attribute	Type	Description
`TwinId`	문자열	트윈 ID
`Action`	문자열	트윈 수명 주기 이벤트의 형식(만들기 또는 삭제)
`TimeStamp`	DateTime	Azure Digital Twins에서 트윈 수명 주기 이벤트를 처리한 날짜/시간입니다. 이 필드는 시스템에서 설정하며 사용자가 쓸 수 없습니다.
`ServiceId`	문자열	레코드를 로그하는 Azure IoT 서비스의 서비스 인스턴스 ID
`ModelId`	문자열	DTDL 모델 ID(DTMI)

아래는 Azure Data Explorer에 저장된 트윈 수명 주기 업데이트의 테이블 예입니다.

`TwinId`	`Action`	`TimeStamp`	`ServiceId`	`ModelId`
PasteurizationMachine_A01	만들기	2022-12-15 07:14:12.4160	dairyadtinstance.api.wcus.digitaltwins.azure.net	`dtmi:assetGen:PasteurizationMachine;1`
PasteurizationMachine_A02	만들기	2022-12-15 07:14:12.4210	dairyadtinstance.api.wcus.digitaltwins.azure.net	`dtmi:assetGen:PasteurizationMachine;1`
SaltMachine_C0	만들기	2022-12-15 07:14:12.5480	dairyadtinstance.api.wcus.digitaltwins.azure.net	`dtmi:assetGen:SaltMachine;1`
PasteurizationMachine_A02	삭제	2022-12-15 07:15:49.6050	dairyadtinstance.api.wcus.digitaltwins.azure.net	`dtmi:assetGen:PasteurizationMachine;1`

관계 수명 주기 이벤트

관계 수명 주기 이벤트에 대한 Azure Data Explorer 테이블에는 데이터 기록 연결을 만들 때 지정하는 사용자 지정 이름이 있습니다.

관계 수명 주기 이벤트에 대한 시계열 데이터는 다음 스키마와 함께 저장됩니다.

Attribute	Type	Description
`RelationshipId`	문자열	관계 ID입니다. 이 필드는 시스템에서 설정하며 사용자가 쓸 수 없습니다.
`Name`	문자열	관계의 이름
`Action`	관계 수명 주기 이벤트 형식(만들기 또는 삭제)
`TimeStamp`	DateTime	Azure Digital Twins에서 관계 수명 주기 이벤트를 처리한 날짜/시간입니다. 이 필드는 시스템에서 설정하며 사용자가 쓸 수 없습니다.
`ServiceId`	레코드를 로그하는 Azure IoT 서비스의 서비스 인스턴스 ID
`Source`	원본 트윈 ID입니다. 이는 관계가 시작된 트윈의 ID입니다.
`Target`	대상 트윈 ID입니다. 이는 관계가 도착하는 트윈의 ID입니다.

아래는 Azure Data Explorer에 저장된 관계 수명 주기 업데이트의 테이블 예입니다.

`RelationshipId`	`Name`	`Action`	`TimeStamp`	`ServiceId`	`Source`	`Target`
PasteurizationMachine_A01_feeds_Relationship0	feeds	만들기	2022-12-15 07:16:12.7120	dairyadtinstance.api.wcus.digitaltwins.azure.net	PasteurizationMachine_A01	SaltMachine_C0
PasteurizationMachine_A02_feeds_Relationship0	feeds	만들기	2022-12-15 07:16:12.7160	dairyadtinstance.api.wcus.digitaltwins.azure.net	PasteurizationMachine_A02	SaltMachine_C0
PasteurizationMachine_A03_feeds_Relationship0	feeds	만들기	2022-12-15 07:16:12.7250	dairyadtinstance.api.wcus.digitaltwins.azure.net	PasteurizationMachine_A03	SaltMachine_C1
OsloFactory_contains_Relationship0	contains	삭제	2022-12-15 07:16:13.1780	dairyadtinstance.api.wcus.digitaltwins.azure.net	OsloFactory	SaltMachine_C0

엔드투엔드 수집 대기 시간

Azure Digital Twins 데이터 기록은 Azure Data Explorer가 제공하는 기존 수집 메커니즘을 기반으로 합니다. Azure Digital Twins는 2초 이내에 Azure Data Explorer에서 그래프 업데이트 이벤트를 사용할 수 있도록 합니다. Azure에 Data Explorer가 데이터를 수집하는 동안 추가 대기 시간이 발생할 수 있습니다.

Azure Data Explorer에서 데이터를 수집하는 방법으로는 일괄 수집 및 스트리밍 수집이라는 두 가지 방법이 있습니다. 요구 사항 및 특정 데이터 수집 시나리오에 따라 개별 테이블에 대해 이러한 수집 방법을 구성할 수 있습니다.

스트리밍 수집의 대기 시간이 가장 낮습니다. 그러나 처리 오버헤드로 인해 이 모드는 매 시간 4GB 미만의 데이터를 수집하는 경우에만 사용해야 합니다. 높은 수집 데이터 속도가 필요한 경우 일괄 처리 수집이 가장 적합합니다. Azure Data Explorer는 기본적으로 일괄 수집을 사용합니다. 다음 표에는 예상되는 최악의 엔드투엔드 대기 시간이 요약되어 있습니다.

Azure Data Explorer 구성	예상되는 엔드투엔드 대기 시간	권장 데이터 속도
스트리밍 수집	<12초(보통 <3초)	<4GB/시간
일괄 수집	변동(구성에 따라 12초~15분)	>4GB/시간

이 섹션의 나머지 부분에는 각 수집 유형을 사용하도록 설정하기 위한 세부 정보가 포함되어 있습니다.

일괄 수집(기본값)

달리 구성하지 않으면 Azure Data Explorer에서 일괄 수집을 사용합니다. 기본 설정으로 인해 디지털 트윈에 대한 업데이트가 수행된 후 5~10분이 지나야만 쿼리에 데이터를 사용할 수 있습니다. 일괄 처리가 최대 10초마다(최소값. 최대값은 15분) 발생하도록 수집 정책을 변경할 수 있습니다. 수집 정책을 변경하려면 Azure Data Explorer 쿼리 뷰에서 다음 명령을 실행해야 합니다.

.alter table <table_name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'

<table_name>이 자동으로 설정된 테이블의 이름으로 대체되었는지 확인합니다. MaximumBatchingTimeSpan은 기본 일괄 처리 간격으로 설정해야 합니다. 정책이 적용되는 데 5~10분이 걸릴 수 있습니다. 수집 일괄 처리에 대한 자세한 내용은 Kusto IngestionBatching 정책 관리 명령 링크에서 확인할 수 있습니다.

스트리밍 수집

스트리밍 수집을 사용하도록 설정하는 것은 2단계 프로세스입니다.

클러스터에 스트리밍 수집을 사용하도록 설정합니다. 이 작업은 한 번만 수행하면 됩니다. (경고: 이렇게 하면 핫 캐시에 사용할 수 있는 스토리지 양이 달라지며 추가 제한 사항이 발생할 수 있습니다.) 자세한 내용은 Azure Data Explorer 클러스터에서 스트리밍 수집 구성을 참조하세요.
원하는 테이블에 대한 스트리밍 수집 정책을 추가합니다. 클러스터에 대한 스트리밍 수집을 사용하도록 설정하는 방법에 대한 자세한 내용은 Azure Data Explorer 설명서 Kusto IngestionBatching 정책 관리 명령에서 확인할 수 있습니다.

Azure Digital Twins 데이터 기록 테이블에 스트리밍 수집을 사용하도록 설정하려면 Azure Data Explorer 쿼리 창에서 다음 명령을 실행해야 합니다.

.alter table <table_name> policy streamingingestion enable

<table_name>이 자동으로 설정된 테이블의 이름으로 대체되었는지 확인합니다. 정책이 적용되는 데 5~10분이 걸릴 수 있습니다.

기록된 속성 시각화

Azure Digital Twins 데이터를 시각화하고 상호 작용하기 위한 개발자 도구인 Azure Digital Twins Explorer는 차트 또는 테이블에서 시간 경과에 따라 기록된 속성을 볼 수 있는 데이터 기록 탐색기 기능을 제공합니다. 이 기능은 Azure Digital Twins에 3D 자산의 시각적 컨텍스트를 제공하기 위한 몰입형 3D 환경인 3D Scenes Studio에서도 사용할 수 있습니다.

데이터 기록 탐색기 사용에 대한 자세한 내용은 기록된 속성의 유효성 검사 및 탐색을 참조하세요.