Azure Digital Twins API 및 SDK
이 문서에서는 사용할 수 있는 Azure Digital Twins API의 개요와 이 API와 상호 작용하는 방법을 제공합니다. Postman과 같은 도구를 통해 또는 SDK를 통해 REST API를 관련 Swagger에 함께 직접 사용할 수 있습니다.
Azure Digital Twins는 인스턴스 및 해당 요소를 관리하기 위한 컨트롤 플레인 API, 데이터 평면 API 및 SDK를 모두 제공합니다.
- 컨트롤 플레인 API는 ARM(Azure Resource Manager) API이며, 인스턴스를 만들고 삭제하는 것과 같은 리소스 관리 작업을 다룹니다.
- 데이터 평면 API는 Azure Digital Twins API이며 모델, 트윈 및 그래프 관리와 같은 데이터 관리 작업에 사용됩니다.
- SDK는 기존 API를 활용하여 Azure Digital Twins를 사용하는 사용자 지정 애플리케이션을 쉽게 개발하게 해줍니다.
컨트롤 플레인 API
컨트롤 플레인 API는 전체 인스턴스를 만들거나 삭제하는 것과 같은 작업을 수행하기 위해 Azure Digital Twins 인스턴스 전체를 관리하는 데 사용되는 ARM API입니다. 또한 엔드포인트를 만들고 삭제하는 이러한 API를 사용합니다.
API를 직접 호출하려면 컨트롤 플레인 Swagger 리포지토리의 최신 Swagger 폴더를 참조합니다. 이 폴더에는 사용법을 보여 주는 예제 폴더도 포함되어 있습니다.
다음은 현재 Azure Digital Twins 컨트롤 플레인 API에 사용할 수 있는 SDK입니다.
또한 Azure Portal 및 CLI를 통해 Azure Digital Twins와 상호 작용하여 컨트롤 플레인 API를 연습할 수 있습니다.
데이터 평면 API
데이터 평면 API는 Azure Digital Twins 인스턴스 내에서 요소를 관리하는 데 사용되는 Azure Digital Twins API입니다. 여기에는 경로 만들기, 모델 업로드, 관계 만들기 및 트윈 관리와 같은 작업이 포함되며 다음 범주로 크게 나눌 수 있습니다.
DigitalTwinModels- DigitalTwinModels 범주에는 Azure Digital Twins 인스턴스에서 모델을 관리하는 API가 포함되어 있습니다. 관리 작업에는 DTDL에서 작성된 모델의 업로드, 유효성 검사, 검색 및 삭제가 포함됩니다.DigitalTwins- DigitalTwins 범주에는 개발자가 Azure Digital Twins 인스턴스에서 디지털 트윈 및 해당 관계를 만들고, 수정하고, 삭제할 수 있도록 하는 API가 포함되어 있습니다.Query- 쿼리 범주를 통해 개발자는 관계 전반에 걸쳐 트윈 그래프에서 디지털 트윈 세트를 찾을 수 있습니다.Event Routes- 이벤트 경로 범주에는 시스템 및 다운스트림 서비스를 통해 데이터를 라우팅하는 API가 포함되어 있습니다.Import Jobs- 작업 API 가져오기를 사용하면 모델, 트윈, 관계를 대량으로 가져오는 장기 실행 비동기 작업을 관리할 수 있습니다.Delete Jobs- 삭제 작업 API를 사용하면 인스턴스의 모든 모델, 트윈, 관계를 삭제하는 장기 실행 비동기 작업을 관리할 수 있습니다.
API를 직접 호출하려면 데이터 평면 Swagger 리포지토리의 최신 Swagger 폴더를 참조합니다. 이 폴더에는 사용법을 보여 주는 예제 폴더도 포함되어 있습니다. 데이터 평면 API 참조 설명서를 볼 수도 있습니다.
다음은 현재 Azure Digital Twins 데이터 평면 API에 사용할 수 있는 SDK입니다.
CLI를 통해 Azure Digital Twins와 상호 작용하여 데이터 평면 API를 연습할 수도 있습니다.
사용량 및 인증 정보
이 섹션에는 API 및 SDK 사용에 대한 자세한 정보가 포함되어 있습니다.
API 참고 사항
다음은 Azure Digital Twins API를 직접 호출하기 위한 몇 가지 일반적인 정보입니다.
- Postman과 같은 HTTP REST 테스트 도구를 사용하여 Azure Digital Twins API에 대한 직접 호출을 수행할 수 있습니다. 이 프로세스에 대한 자세한 내용은 Postman을 사용하여 Azure Digital Twins API 호출을 참조하세요.
- Azure Digital Twins는 현재 CORS(원본 간 리소스 공유)를 지원하지 않습니다. 영향 및 해결 방법에 대한 자세한 내용은 Azure Digital Twins용 CORS(원본 간 리소스 공유)를 참조하세요.
API 요청 인증에 대한 자세한 내용은 다음과 같습니다.
- Azure Digital Twins API 요청에 대한 전달자 토큰을 생성하는 한 가지 방법은 az account get-access-token CLI 명령을 사용하는 것입니다. 자세한 지침은 전달자 토큰 가져오기를 참조하세요.
- Azure Digital Twins API에 대한 요청에는 해당 Azure Digital Twins 인스턴스가 있는 동일한 Microsoft Entra ID 테넌트의 일부인 사용자 또는 서비스 주체가 필요합니다. Azure Digital Twins 엔드포인트의 악의적인 검색을 방지하기 위해 원래 테넌트 외부에서 액세스 토큰이 있는 요청은 "404 하위 도메인을 찾을 수 없음" 오류 메시지가 반환됩니다. 이 오류는 Microsoft Entra B2B 협업을 통해 사용자 또는 서비스 주체에게 Azure Digital Twins 데이터 소유자 또는 Azure Digital Twins 데이터 읽기 권한자 역할이 부여된 경우에도 반환됩니다. 여러 테넌트 간 액세스를 구현하는 방법에 대한 자세한 내용은 앱 인증 코드 작성을 참조하세요.
SDK 노트
Azure Digital Twins의 기본 SDK는 Azure.Core입니다. SDK 인프라 및 유형에 대한 참조는 Azure 네임스페이스 설명서를 참조하세요.
SDK 인증에 대한 자세한 내용은 다음과 같습니다.
- 먼저
DigitalTwinsClient클래스를 인스턴스화합니다. 생성자에는Azure.Identity패키지의 다양한 종류의 인증 방법을 사용하여 얻을 수 있는 자격 증명이 필요합니다.Azure.Identity에 대한 자세한 내용은 네임스페이스 설명서를 참조하세요. - 시작하는 동안 유용한
InteractiveBrowserCredential을 찾을 수 있지만, Azure Digital Twins에 대해 MSI로 설정된 Azure 함수를 인증하는 데 사용할 수 있는 관리 ID에 대한 자격 증명을 비롯하여 몇 가지 다른 옵션이 있습니다.InteractiveBrowserCredential에 대한 자세한 내용은 클래스 설명서를 참조하세요.
함수 및 반환된 데이터에 대한 자세한 내용은 다음과 같습니다.
- 모든 서비스 API 호출은
DigitalTwinsClient클래스에서 멤버 함수로 노출됩니다. - 모든 서비스 함수는 동기 및 비동기 버전으로 존재합니다.
- 모든 서비스 함수는 400 이상의 반환 상태에 대한 예외를 throw합니다.
try섹션으로 호출을 래핑하고 최소한의RequestFailedExceptions를 catch해야 합니다. 이러한 형식의 예외에 대한 자세한 내용은 해당 참조 설명서를 참조하세요. - 대부분의 서비스 메서드는
Response<T>(또는 비동기 호출의 경우Task<Response<T>>)를 반환합니다. 여기서T는 서비스 호출에 대한 반환 개체의 클래스입니다. Response 클래스는 서비스 반환을 캡슐화하고 해당Value필드에 반환 값을 제공합니다. - 페이징 결과를 포함하는 서비스 메서드는
Pageable<T>또는AsyncPageable<T>를 결과로 반환합니다.Pageable<T>클래스에 대한 자세한 내용은 해당 참조 설명서를 참조하세요.AsyncPageable<T>에 대한 자세한 내용은 해당 참조 설명서를 참조하세요. await foreach루프를 사용하여 페이징 결과를 반복할 수 있습니다. 이 프로세스에 대한 자세한 내용은 C# 8에서 비동기 열거형으로 반복을 참조하세요.- 서비스 메서드는 가능한 경우 항상 강력한 형식의 개체를 반환합니다. 그러나 Azure Digital Twins는 런타임에 사용자가 구성한 모델을 기반으로 하기 때문에(서비스에 업로드된 DTDL 모델을 통해) 많은 서비스 API가 트윈 데이터를 JSON 형식으로 사용하고 반환합니다.
.NET(C#) SDK의 Serialization 도우미
Serialization 도우미는 기본 정보에 대한 액세스를 위해 트윈 데이터를 신속하게 만들거나 역직렬화하기 위해 .NET(C#) SDK 내에서 사용할 수 있는 도우미 함수입니다. 핵심 SDK 메서드는 기본적으로 트윈 데이터를 JSON으로 반환하므로 이러한 도우미 클래스를 사용하여 트윈 데이터를 더 분할하는 것이 유용할 수 있습니다.
사용 가능한 도우미 클래스는 다음과 같습니다.
BasicDigitalTwin: 일반적으로 디지털 트윈의 핵심 데이터를 나타냅니다.BasicDigitalTwinComponent: 일반적으로BasicDigitalTwin의Contents속성의 구성 요소를 나타냅니다.BasicRelationship: 일반적으로 관계의 핵심 데이터를 나타냅니다.DigitalTwinsJsonPropertyName: 사용자 지정 디지털 트윈 유형에 대한 JSON serialization 및 deserialization에 사용되는 문자열 상수를 포함합니다.
가져오기 작업 API를 사용하여 대량으로 가져오기
가져오기 작업 API는 단일 API 호출에서 모델, 트윈 및/또는 관계 세트를 가져올 수 있는 데이터 평면 API입니다. 가져오기 작업 API 작업도 CLI 명령 및 데이터 평면 SDK에 포함됩니다. 가져오기 작업 API를 사용하려면 Azure Blob Storage를 사용해야 합니다.
권한 확인
가져오기 작업 API를 사용하려면 이 섹션에 설명된 사용 권한 설정을 사용하도록 설정해야 합니다.
먼저 Azure Digital Twins 인스턴스에는 시스템이 할당한 관리 ID를 사용해야 합니다. 인스턴스별로 시스템 관리 ID를 설정하는 지침은 인스턴스에 관리 ID 사용/사용 안 함을 참조하세요.
Azure Digital Twins 인스턴스에서 다음 데이터 작업 범주에 대한 쓰기 권한이 있어야 합니다.
Microsoft.DigitalTwins/jobs/*- 작업 호출에 포함하려는 모든 그래프 요소입니다. 여기에는
Microsoft.DigitalTwins/models/*,Microsoft.DigitalTwins/digitaltwins/*및/또는Microsoft.DigitalTwins/digitaltwins/relationships/*가 포함될 수 있습니다.
이러한 모든 권한을 제공하는 기본 제공 역할은 Azure Digital Twins 데이터 소유자입니다. 사용자 지정 역할을 사용하여 필요한 데이터 형식에만 세분화된 액세스 권한을 부여할 수도 있습니다. Azure Digital Twins의 역할에 대한 자세한 내용은 Azure Digital twins 솔루션의 보안을 참조하세요.
참고 항목
가져오기 작업 API 호출을 시도하고 가져오려는 그래프 요소 유형 중 하나에 대한 쓰기 권한이 누락된 경우 작업은 해당 유형을 건너뛰고 다른 유형을 가져옵니다. 예를 들어 모델과 트윈에 대한 쓰기 액세스 권한이 있지만 관계에 대한 권한이 없는 경우 세 가지 유형의 요소를 모두 대량으로 가져오려는 시도는 모델 및 트윈을 가져오는 데만 성공합니다. 작업 상태는 실패를 반영하고 메시지는 누락된 권한을 나타냅니다.
또한 Azure Blob Storage 컨테이너의 입력 및 출력 파일에 액세스할 수 있도록 Azure Digital Twins 인스턴스의 시스템 할당 관리 ID에 다음 RBAC 권한을 부여해야 합니다.
- Azure Storage 입력 Blob 컨테이너에 대한 Storage Blob 데이터 읽기 권한자
- Azure Storage 출력 Blob 컨테이너에 대한 Storage Blob 데이터 기여자
마지막으로 작업 API 요청에 사용할 수 있는 전달자 토큰을 생성합니다. 지침은 전달자 토큰 가져오기를 참조하세요.
데이터 형식 지정
API는 Azure Blob Storage 컨테이너에 업로드해야 하는 NDJSON 파일의 그래프 정보 입력을 허용합니다. 파일은 Header 섹션으로 시작하고 그 뒤에 선택적 섹션인 Models, Twins 및 Relationships가 옵니다. 파일에 세 가지 유형의 그래프 데이터를 모두 포함할 필요는 없지만 존재하는 모든 섹션은 해당 순서를 따라야 합니다. 이 API로 만들어진 트윈 및 관계는 해당 속성의 초기화를 선택적으로 포함할 수 있습니다.
가져오기 API에 대한 샘플 입력 데이터 파일은 다음과 같습니다.
{"Section": "Header"}
{"fileVersion": "1.0.0", "author": "foobar", "organization": "contoso"}
{"Section": "Models"}
{"@id":"dtmi:com:microsoft:azure:iot:model0;1","@type":"Interface","contents":[{"@type":"Property","name":"property00","schema":"integer"},{"@type":"Property","name":"property01","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}},{"@type":"Relationship","name":"has","target":"dtmi:com:microsoft:azure:iot:model1;1","properties":[{"@type":"Property","name":"relationshipproperty1","schema":"string"},{"@type":"Property","name":"relationshipproperty2","schema":"integer"}]}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"@id":"dtmi:com:microsoft:azure:iot:model1;1","@type":"Interface","contents":[{"@type":"Property","name":"property10","schema":"string"},{"@type":"Property","name":"property11","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"Section": "Twins"}
{"$dtId":"twin0","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model0;1"},"property00":10,"property01":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"$dtId":"twin1","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model1;1"},"property10":"propertyValue1","property11":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"Section": "Relationships"}
{"$dtId":"twin0","$relationshipId":"relationship","$targetId":"twin1","$relationshipName":"has","relationshipProperty1":"propertyValue1","relationshipProperty2":10}
팁
모델, 트윈 및 관계를 가져오기 API에서 지원하는 NDJSON으로 변환하는 샘플 프로젝트는 Azure Digital Twins 대량 가져오기 NDJSON 생성기를 참조하세요. 샘플 프로젝트는 .NET용으로 작성되었으며 사용자 고유의 가져오기 파일을 만드는 데 도움이 되도록 다운로드하거나 조정할 수 있습니다.
파일이 만들어지면 원하는 업로드 방법(일부 옵션은 AzCopy 명령, Azure CLI 또는 Azure Portal)을 사용하여 Azure Blob Storage의 블록 Blob에 업로드합니다. 가져오기 작업 API 호출 본문에서 NDJSON 파일의 Blob Storage URL을 사용합니다.
가져오기 작업 실행
이제 가져오기 작업 API 호출을 진행할 수 있습니다. 한 번의 API 호출로 전체 그래프를 가져오는 방법에 대한 자세한 지침은 가져오기 작업 API를 사용하여 모델, 트윈, 관계를 대량으로 업로드를 참조하세요. 가져오기 작업 API를 사용하여 각 리소스 종류를 독립적으로 가져올 수도 있습니다. 개별 리소스 종류와 함께 가져오기 작업 API를 사용하는 방법에 대한 자세한 내용은 모델, 트윈, 관계에 대한 가져오기 작업 API 지침을 참조하세요.
API 호출 본문에서 NDJSON 입력 파일의 Blob Storage URL을 제공합니다. 또한 서비스에서 출력 로그를 만든 후 이를 저장할 위치를 나타내는 새 Blob Storage URL을 제공합니다.
Important
Azure Digital Twins 인스턴스의 시스템 할당 관리 ID에 사용 권한 확인 섹션에 설명된 스토리지 Blob RBAC 사용 권한이 있는지 확인합니다.
가져오기 작업이 실행되면 구조화된 출력 로그가 서비스에서 생성되고 요청의 출력 Blob에 대해 지정한 URL 위치에서 Blob 컨테이너의 새 추가 Blob으로 저장됩니다. 다음은 모델, 트윈 및 관계를 가져오는 성공적인 작업에 대한 예제 출력 로그입니다.
{"timestamp":"2022-12-30T19:50:34.5540455Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Started"}}
{"timestamp":"2022-12-30T19:50:37.2406748Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Started"}}
{"timestamp":"2022-12-30T19:50:38.1445612Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:38.5475921Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Started"}}
{"timestamp":"2022-12-30T19:50:39.2744802Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:39.7494663Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Started"}}
{"timestamp":"2022-12-30T19:50:40.4480645Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:41.3043264Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Succeeded"}}
작업이 완료되면 BulkOperationEntityCount 메트릭을 사용하여 수집된 엔터티의 총 수를 볼 수 있습니다.
가져오기 작업 API에서 취소 작업을 사용하여 실행 중인 가져오기 작업을 취소할 수도 있습니다. 작업이 취소되어 더 이상 실행되지 않으면 삭제할 수 있습니다.
제한 및 고려 사항
가져오기 작업 API를 사용하는 동안 다음 고려 사항에 유의하세요.
- 가져오기 작업은 원자성 작업이 아닙니다. 실패, 부분 작업 완료 또는 취소 작업 사용의 경우 롤백이 없습니다.
- Azure Digital Twins 인스턴스 내에서 한 번에 하나의 대량 작업만 지원됩니다. Azure Digital Twins 제한에서 작업 API의 이 정보 및 기타 숫자 제한을 볼 수 있습니다.
삭제 작업 API를 사용하여 대량 삭제
삭제 작업 API는 단일 API 호출을 사용하여 인스턴스의 모든 모델, 트윈, 관계를 삭제할 수 있는 데이터 평면 API입니다. 삭제 작업 API 작업은 CLI 명령으로 사용할 수도 있습니다. API 설명서를 방문하여 삭제 작업을 만들고 해당 상태를 확인하기 위한 요청 세부 정보를 확인합니다.
모든 요소가 삭제되었는지 확인하려면 삭제 작업 API를 사용하는 동안 다음 권장 사항을 따르세요.
- API 요청을 인증하기 위해 전달자 토큰을 생성하는 방법에 대한 지침은 전달자 토큰 가져오기를 참조하세요.
- 최근에 많은 수의 엔터티를 그래프로 가져온 경우 잠시 기다렸다가 삭제 작업을 시작하기 전에 모든 요소가 그래프에서 동기화되는지 확인합니다.
- 삭제 작업이 완료될 때까지 인스턴스의 모든 작업, 특히 업로드 작업을 중지합니다.
삭제되는 그래프의 크기에 따라 삭제 작업은 몇 분에서 몇 시간까지 걸릴 수 있습니다.
삭제 작업의 기본 시간 제한 기간은 12시간이며, API에서 쿼리 매개 변수를 사용하여 15분~24시간 사이의 모든 값으로 조정할 수 있습니다. 삭제 작업이 시간 초과되기 전에 실행되는 시간입니다. 이때 서비스가 아직 완료되지 않은 경우 작업을 중지하려고 시도합니다.
제한 및 기타 고려 사항
삭제 작업 API를 사용하는 동안 다음 고려 사항에 유의하세요.
- 삭제 작업은 원자성 작업이 아닙니다. 실패, 부분 작업 완료 또는 작업 시간 제한의 경우 롤백이 없습니다.
- Azure Digital Twins 인스턴스 내에서 한 번에 하나의 대량 작업만 지원됩니다. Azure Digital Twins 제한에서 작업 API의 이 정보 및 기타 숫자 제한을 볼 수 있습니다.
API 메트릭 모니터링
요청, 대기 시간 및 실패율과 같은 API 메트릭은 Azure Portal에서 볼 수 있습니다.
Azure Digital Twins 메트릭 보기 및 관리에 대한 자세한 내용은 인스턴스 모니터링을 참조하세요. Azure Digital Twins에 사용할 수 있는 API 메트릭의 전체 목록은 Azure Digital Twins API 요청을 참조하세요.
다음 단계
Postman을 사용하여 Azure Digital Twins API에 직업 요청 만드는 방법은 다음을 참조하세요.
또는 다음 자습서를 사용하여 클라이언트 앱을 만들어 .NET SDK 사용을 연습합니다.