Azure Time Series Insights Gen1 참조 데이터 API
주의
이는 Gen1 문서입니다.
이 문서에서는 참조 데이터 세트 내의 항목을 관리하는 데 사용되는 Azure Time Series Insights Gen1 참조 데이터 관리 API에 대해 설명합니다. 환경 내에서 참조 데이터 세트가 이미 만들어졌다고 가정합니다.
참조 데이터에는 자주 변경되지 않는 제조업체 또는 위치 데이터가 포함됩니다. 참조 데이터는 원격 분석 데이터를 컨텍스트화하는 데 사용되며 원격 분석 데이터를 비교하는 데 사용됩니다.
팁
- 참조 데이터 세트를 만들려면 참조 데이터 세트를 만드는 방법을 참조하세요.
데이터 세트는 기존 및 고정되므로 디바이스에서 전송되는 각 데이터 패킷에는 동일한 정보가 포함됩니다. 따라서 참조 데이터는 디바이스에서 전송되지 않으며 참조 데이터 관리 API 또는 Azure Portal 사용하여 데이터를 관리합니다.
API 개요
참조 데이터 관리 API는 일괄 처리 API입니다.
중요
- 이 API에 대한 모든 작업은 HTTP POST 작업입니다.
- 각 작업은 JSON 개체를 요청 페이로드로 허용합니다.
- HTTP 요청 JSON 개체는 API에서 실행할 작업을 지정하는 단일 속성 이름을 정의합니다.
유효한 JSON 요청 작업 속성 이름은 다음과 같습니다.
중요
- 속성 값은 작업을 적용해야 하는 참조 데이터 항목의 배열입니다.
- 각 항목은 개별적으로 처리되며 한 항목의 오류로 인해 다른 항목이 성공적으로 작성되지는 않습니다. 예를 들어 요청에 100개의 항목이 있고 한 항목에 오류가 있는 경우 99개의 항목이 작성되고 1개는 거부됩니다.
- 참조 데이터 항목은 완전히 열거된 키 속성을 사용하여 쿼리됩니다.
참고
다음 JSON 본문 예제에서는 이름이 deviceId 이고 String을 입력하는 단일 속성 키가 있는 참조 데이터 세트를 가정합니다.
참조 데이터 항목 배치
전체 참조 데이터 항목(배열의 i번째 항목 $.put[i] )을 삽입하거나 키 배치로 바꿉니다. 커밋 단위는 $.put[i]. 작업이 idempotent입니다.
엔드포인트 및 작업:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12요청 본문 예제:
{ "put": [{ "deviceId": "Fan1", "color": "Red", "maxSpeed": 5 }, { "deviceId": "Fan2", "color": "White", "floor": 2 }] }응답 예제:
{ "put": [ null, null ] }
패치 참조 데이터 항목
참조 데이터 항목 $.patch[i]에 대한 특정 속성을 업데이트 삽입합니다.
엔드포인트 및 작업:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12요청 본문 예제:
{ "patch": [ { "deviceId": "Fan1", "maxSpeed": 108 }, { "deviceId": "Fan2", "floor": 18 } ] }응답 본문 예제:
{ "patch": [ null, null ] }
참조 데이터 항목의 속성 삭제
참조 데이터 항목 $.deleteproperties[i]에서 지정된 속성을 삭제합니다.
엔드포인트 및 작업:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12요청 본문 예제:
{ "deleteProperties":[ { "key":{ "deviceId":"Fan2" }, "properties":[ "floor" ] } ] }응답 본문 예제:
{ "deleteProperties": [ null ] }
참조 데이터 항목 삭제
각 $.delete[i]에 지정된 키 속성 값으로 식별되는 전체 참조 데이터 항목을 삭제합니다.
엔드포인트 및 작업:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12요청 본문 예제:
{ "delete": [{ "deviceId": "Fan1" }] }응답 본문 예제:
{ "delete": [ null ] }
참조 데이터 항목 가져오기
각 $.get[i]에 지정된 키 속성 값으로 식별되는 전체 참조 데이터 항목을 가져옵니다.
엔드포인트 및 작업:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12요청 본문 예제:
{ "get": [{ "deviceId": "Fan1" }, { "deviceId": "Fan2" }] }응답 본문 예제:
{ "get": [ { "code": "InvalidInput", "message": "Key not found.", "target": null, "details": null, "innerError": null }, { "id": "Fan2", "floor": 18 } ] }
유효성 검사 및 오류 처리
참조 데이터 관리 API는 각 항목을 개별적으로 처리하며, 한 항목의 오류로 인해 다른 항목이 성공적으로 작성되지는 않습니다. 예를 들어 요청에 100개의 항목이 있고 한 항목에 오류가 있는 경우 99개의 항목이 작성되고 1개는 거부됩니다.
항목 오류 코드
항목 오류 코드는 HTTP 상태 코드 200이 있는 성공적인 JSON 응답 본문 내에서 발생합니다.
InvalidInput: 키를 찾을 수 없습니다.: 쿼리된 항목을 참조 데이터 세트에서 찾을 수 없음을 나타냅니다.
{ "code": "InvalidInput", "message": "Key not found.", "target": null, "details": null, "innerError": null }InvalidInput: 페이로드 키에는 키가 아닌 속성이 포함되어서는 안 됩니다.: JSON 요청 본문 쿼리 항목에 키 속성이 아닌 속성(즉, 참조 집합 스키마에 지정된 속성)이 포함되어서는 안 됨을 나타냅니다. 키 속성은 Azure Portal 찾을 수 있습니다.
{ "code": "InvalidInput", "message": "Payload key should not contain any non-key property.", "target": null, "details": null, "innerError": null }InvalidInput: 페이로드 항목에는 모든 키 속성이 포함되어야 합니다.: JSON 요청 본문 쿼리 항목에 모든 키 속성(즉, 참조 집합 스키마에 지정된 속성)이 포함되어야 했음을 나타냅니다. 키 속성은 Azure Portal 찾을 수 있습니다.
{ "code": "InvalidInput", "message": "Payload item should contain all key properties.", "target": null, "details": null, "innerError": null }
참조 데이터 조인 예제
다음 구조가 있는 이벤트 허브 메시지를 고려합니다.
[
{
"deviceId":"Fan1",
"timestamp":"1/5/2015T00:10:30Z"
},
{
"deviceId":"Fan2",
"timestamp":"1/5/2015T00:10:30Z"
}
]
String 형식의 이름 contoso 및 key deviceId로 설정되고 다음 구조가 있는 참조 데이터 항목을 고려합니다.
| deviceId | 색 | maxSpeed | floor |
|---|---|---|---|
| Fan1 | 빨간색 | 5 | |
| Fan2 | 흰색 | 2 |
이벤트 허브 메시지의 두 이벤트가 Azure Time Series Insights Gen1 수신 엔진에서 처리되면 올바른 참조 데이터 항목과 조인됩니다. 이벤트 출력에는 다음과 같은 구조가 있습니다.
[
{
"deviceId":"Fan1",
"timestamp":"1/5/2015T00:10:30Z",
"color":"Red",
"maxSpeed":5
},
{
"deviceId":"Fan2",
"timestamp":"1/5/2015T00:10:30Z",
"color":"White",
"floor":2
}
]
조인 규칙 및 의미 체계
참조 데이터를 조인하는 경우 다음 제약 조건을 준수합니다.
- 키 이름 비교는 대/소문자를 구분합니다.
- 키 값 비교는 문자열 속성에 대/소문자를 구분합니다.
둘 이상의 참조 데이터 세트가 있는 환경의 경우 조인 중에 세 가지 추가 제약 조건이 적용됩니다.
- 참조 데이터 세트의 각 항목은 키가 아닌 속성의 자체 목록을 지정할 수 있습니다.
- 두 개의 참조 데이터 세트 A와 B의 경우 키가 아닌 속성이 교차해서는 안 됩니다.
- 참조 데이터 세트는 다른 참조된 데이터 세트(및 이벤트에) 연결되지 않은 이벤트에만 직접 조인됩니다. 참조 데이터 항목을 이벤트에 조인하려면 참조 데이터 항목에 사용되는 모든 키 속성이 이벤트에 있어야 합니다. 또한 키 속성은 다른 참조 데이터 항목을 통해 이벤트에 조인된 키가 아닌 속성에서 제공되지 않아야 합니다.
이러한 제약 조건을 감안할 때 조인 엔진은 지정된 이벤트에 대한 순서대로 조인을 적용할 수 있습니다. 계층 구조 및 순서는 고려되지 않습니다.
현재 제한
Azure Time Series Insights Gen1 환경당 최대 2개의 참조 데이터 세트를 추가할 수 있습니다. Azure Time Series Insights Gen1 참조 데이터와 관련된 추가 제한 사항은 다음 표에 나와 있습니다.
| 제한 이름 | 제한 값 | 영향을 받는 SKU | 참고 |
|---|---|---|---|
| 키 속성 수 | 3 | S1, S2 | 참조별 데이터 세트; Azure Resource Manager 및 Azure Portal만 |
| 키 속성 크기 | 1KB | S1, S2 | 참조별 데이터 세트 |
| 참조 데이터 항목 수 | 2,000/20,000(S1/S2) | S1, S2 | 단위당; 예: 4단원 S1 SKU = 8,000개 항목(4 x 2,000) |
| 최대 동시 트랜잭션 | 2/10(S1/S2) | S1, S2 | |
| 최대 참조 데이터 트랜잭션 | 120/600(S1/S2) | S1, S2 | 시간당 |
| 최대 참조 데이터 항목 수 | 1,000 | S1, S2 | 트랜잭션당 |
| 최대 참조 데이터 항목 크기 | 8,192KB | S1, S2 | 트랜잭션당 |
추가 정보
애플리케이션 등록 및 Azure Active Directory 프로그래밍 모델에 대한 자세한 내용은 개발자용 Azure Active Directory를 참조하세요.
요청 및 인증 매개 변수에 대한 자세한 내용은 인증 및 권한 부여를 참조하세요.
HTTP 요청 및 응답 테스트를 지원하는 도구는 다음과 같습니다.
- Fiddler. 이 무료 웹 디버깅 프록시는 REST 요청을 가로챌 수 있으므로 HTTP 요청 및 응답 메시지를 진단할 수 있습니다.
- JWT.io. 이 도구를 사용하여 전달자 토큰에서 클레임을 신속하게 덤프한 다음 해당 콘텐츠의 유효성을 검사할 수 있습니다.
- 우체부. REST API를 디버깅하기 위한 무료 HTTP 요청 및 응답 테스트 도구입니다.
Gen1 설명서를 검토하여 Gen1 Azure Time Series Insights 대해 자세히 알아보세요.