Azure Time Series Insights Gen1 쿼리 API
주의
이는 Gen1 문서입니다.
이 문서에서는 다양한 REST 쿼리 API에 대해 설명합니다. REST API는 gen1 환경에 Azure Time Series Insights 쿼리할 수 있는 HTTP 작업 집합(메서드)을 지원하는 서비스 엔드포인트입니다.
중요
- Azure Time Series Insights Gen1은 환경 가져오기, 환경 가용성 가져오기, 메타데이터 가져오기, 환경 이벤트 가져오기 및 환경 집계 가져오기 API에 HTTPS 프로토콜을 사용합니다.
- Azure Time Series Insights Gen1은 WSS(WebSocket Secure) 프로토콜을 사용하여 환경 이벤트 스트리밍 가져오기 및 집계 스트리밍 API 가져오기를 사용합니다.
환경 API 가져오기
환경 가져오기 API는 호출자가 액세스할 수 있는 권한이 부여된 환경 목록을 반환합니다.
엔드포인트 및 작업:
GET https://api.timeseries.azure.com/environments?api-version=2016-12-12예제 요청 본문: 해당 없음
응답 본문 예제:
{ "environments": [ { "displayName":"Sensors", "environmentFqdn": "00000000-0000-0000-0000-000000000000.env.timeseries.azure.com", "environmentId":"00000000-0000-0000-0000-000000000000", "resourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/RdxProdAssetsEastUs/providers/Microsoft.TimeSeriesInsights/environments/Sensors", "roles": [ "Reader", "Contributor" ] } ] }참고
응답 속성 environmentFqdn 은 환경별 쿼리 API 요청에 사용되는 환경에 대한 고유한 정규화된 도메인 이름입니다.
Get Environment Availability API
환경 가용성 가져오기 API는 이벤트 타임스탬프 $ts 이벤트 수의 분포를 반환합니다. 환경 가용성은 캐시되며 응답 시간은 환경의 이벤트 수에 따라 달라지지 않습니다.
팁
환경 가용성 가져오기 API를 사용하여 프런트 엔드 UI 환경을 초기화할 수 있습니다.
엔드포인트 및 작업:
GET https://<environmentFqdn>/availability?api-version=2016-12-12예제 요청 본문: 해당 없음
응답 본문 예제:
{ "range": { "from": "2016-08-01T01:02:03Z", "to": "2016-08-31T03:04:05Z" }, "intervalSize": "1h", "distribution": { "2016-08-01T00:00:00Z": 123, "2016-08-31T03:00:00Z": 345 } }이벤트가 없는 환경에 대해 빈 개체가 반환됩니다.
환경 메타데이터 API 가져오기
환경 메타데이터 가져오기 API는 지정된 검색 범위에 대한 환경 메타데이터를 반환합니다. 메타데이터는 속성 참조 집합으로 반환됩니다. Azure Time Series Insights Gen1은 내부적으로 메타데이터를 캐시하고 근사치를 생성하며 검색 범위의 정확한 이벤트에 있는 더 많은 속성을 반환할 수 있습니다.
엔드포인트 및 작업:
POST https://<environmentFqdn>/metadata?api-version=2016-12-12입력 페이로드 구조:
- 검색 범위 절(필수)
요청 본문 예제:
{ "searchSpan": { "from": {"dateTime":"2016-08-01T00:00:00.000Z"}, "to": {"dateTime":"2016-08-31T00:00:00.000Z"} } }응답 본문 예제:
{ "properties": [ { "name": "sensorId", "type": "String" }, { "name": "sensorValue", "type": "Double" }, { "name": "iothub-connection-device-id", "type": "String" } ] }환경이 비어 있거나 검색 범위에 이벤트가 없는 경우 빈
properties배열이 반환됩니다.기본 제공 속성은 속성 목록에 반환되지 않습니다.
환경 이벤트 API 가져오기
환경 이벤트 가져오기 API는 검색 범위 및 조건자와 일치하는 원시 이벤트 목록을 반환합니다.
엔드포인트 및 작업:
POST https://<environmentFqdn>/events?api-version=<apiVersion>입력 페이로드 구조:
- 검색 범위 절(필수)
- 조건자 절(선택 사항)
- Limit 절(필수)
요청 본문 예제:
{ "searchSpan": { "from": { "dateTime": "2019-12-30T00:00:00.000Z" }, "to": { "dateTime": "2019-12-31T23:00:00.000Z" } }, "predicateString": "PointValue.Double = 3.14", "top": { "sort": [ { "input": { "builtInProperty": "$ts" }, "order": "Asc" } ], "count": 1000 } }참고
- 중첩된 정렬(즉, 둘 이상의 속성을 기준으로 정렬)은 현재 지원되지 않습니다.
- 이벤트를 정렬하고 위쪽으로 제한할 수 있습니다.
- 정렬은 모든 속성 형식에서 지원됩니다. 정렬은 부울 식에 대해 정의된 비교 연산자를 사용합니다.
응답 본문 예제:
{ "warnings": [], "events": [ { "schema": { "rid": 0, "$esn" : "buildingsensors", "properties" : [{ "name" : "sensorId", "type" : "String" }, { "name" : "sensorValue", "type" : "String" }] }, "$ts" : "2016-08-30T23:20:00Z", "values" : ["IndoorTemperatureSensor", 72.123] }, { "schemaRid" : 0, "$ts" : "2016-08-30T23:21:00Z", "values" : ["IndoorTemperatureSensor", 72.345] } ] }
Get Environment Events Streamed API
Get Environment Events Streamed API는 검색 범위 및 조건자와 일치하는 원시 이벤트 목록을 반환합니다.
이 API는 WebSocket 보안 프로토콜을 사용하여 스트리밍을 수행하고 부분 결과를 반환합니다. 항상 추가 이벤트를 반환합니다. 즉, 새 메시지는 이전 메시지에 추가됩니다. 새 메시지에는 이전 메시지에 없었던 새 이벤트가 포함되어 있습니다. 새 메시지가 추가될 때 이전 메시지를 유지해야 합니다.
엔드포인트 및 작업:
GET wss://<environmentFqdn>/events?api-version=<apiVersion>입력 페이로드 구조:
- 검색 범위 절(필수)
- 조건자 절(선택 사항)
- Limit 절(필수)
요청 메시지 예제:
{ "headers" : { "Authorization":"Bearer <YOUR_AAD_OAUTH_TOKEN>", "x-ms-client-request-id" : "132gae-w343-41a1-2342-w23ta4532" }, "content": { "searchSpan": { "from": "2017-04-30T23:00:00.000Z", "to": "2017-05-01T00:00:00.000Z" }, "top": { "sort": [ { "input": { "builtInProperty": "$ts" }, "order": "Asc" } ], "count": 1000 } } }참고
- 중첩된 정렬(즉, 둘 이상의 속성을 기준으로 정렬)은 현재 지원되지 않습니다.
- 이벤트를 정렬하고 위쪽으로 제한할 수 있습니다.
- 정렬은 모든 속성 형식에서 지원됩니다. 정렬은 부울 식에 대해 정의된 비교 연산자를 사용합니다.
응답 메시지 예제:
{ "headers": { "x-ms-request-id": "a325-a345-sy43-w332-a4qat36a2262" }, "content": { "events": [ { "schema": { "rid": 0, "$esn": "devicedata", "properties": [ { "name": "Id", "type": "String" }, { "name": "TemperatureControlLevel", "type": "Double" }, { "name": "Type", "type": "String" }, { "name": "UnitVersion", "type": "String" }, { "name": "Station", "type": "String" }, { "name": "ProductionLine", "type": "String" }, { "name": "Factory", "type": "String" }, { "name": "Timestamp", "type": "DateTime" } ] }, "$ts": "2017-04-30T23:00:00Z", "values": [ "82faa3c1-f11d-44f5-a1ca-e448f6123eee", 0.9835468282931982, "temp control rate", "1.1.7.0", "Station5", "Line1", "Factory2", "2017-04-30T23:00:00Z" ] }, { "schemaRid": 0, "$ts": "2017-04-30T23:00:00Z", "values": [ "acb2f926-62cc-4a88-9246-94a26ebcaee3", 0.8542095381579537, "temp control rate", "1.1.7.0", "Station2", "Line1", "Factory3", "2017-04-30T23:00:00Z" ] } ] }, "warnings": [], "percentCompleted": 100 }
Get Environment Aggregates API
Get Environment Aggregates API는 필요에 따라 다른 속성의 값을 측정하기 때문에 지정된 속성별로 이벤트를 그룹화합니다.
참고
버킷 경계는 10, 2×10 또는 5×10 값을 지원하여 숫자 히스토그램을 더 잘 지원합니다.
엔드포인트 및 작업:
POST https://<environmentFqdn>/aggregates?api-version=<apiVersion>입력 페이로드 구조:
- 검색 범위 절(필수)
- 조건자 절(선택 사항)
- Aggregates 절(필수)
요청 본문 예제:
{ "searchSpan": { "from": { "dateTime": "2019-12-30T00:00:00.000Z" }, "to": { "dateTime": "2019-12-31T23:00:00.000Z" } }, "predicateString": "PointValue.Double > 1000", "aggregates": [ { "dimension": { "uniqueValues": { "input": { "property": "iothub-connection-device-id", "type": "String" }, "take": 100 } }, "aggregate": { "dimension": { "dateHistogram": { "input": { "builtInProperty": "$ts" }, "breaks": { "size": "1h" } } }, "measures": [ { "min": { "input": { "property": "series.flowRate", "type": "Double" } } }, { "count": {} } ] } } ] }응답 본문 예제:
{ "aggregates": [ { "dimension": [ "Test-Device-A11342" ], "aggregate": { "dimension": [ "2019-12-30T23:00:00Z", "2019-12-31T00:00:00Z" ], "measures": [ [ [ 0.319668575730514, 2678 ], [ 0.08442680357734211, 1238 ] ] ] } } ], "warnings": [] }측정값 식을 지정하지 않고 이벤트 목록이 비어 있으면 응답이 비어 있습니다.
측정값이 있는 경우 응답에는 차원 값,
0개수 값 및 다른 종류의 측정값에 대한 값이 포함된null단일 레코드null가 포함됩니다.
Get Environment Aggregates Streamed API
Get Environment Aggregates Streamed API는 필요에 따라 다른 속성의 값을 측정하기 때문에 지정된 속성별로 이벤트를 그룹화합니다.
- 이 API는 스트리밍 및 부분 결과를 반환하기 위해 WebSocket 보안 프로토콜을 사용합니다.
- 항상 모든 값의 대체(스냅샷)를 반환합니다.
- 이전 패킷은 클라이언트에서 삭제할 수 있습니다.
참고
버킷 경계는 10, 2×10 또는 5×10 값을 지원하여 숫자 히스토그램을 더 잘 지원합니다.
엔드포인트 및 작업:
GET wss://<environmentFqdn>/aggregates?api-version=<apiVersion>입력 페이로드 구조:
- 검색 범위 절(필수)
- 조건자 절(선택 사항)
- Aggregates 절(필수)
요청 메시지 예제:
{ "headers":{ "Authorization":"Bearer <YOUR_AAD_OAUTH_TOKEN>" }, "content":{ "predicate":{ "predicateString":"" }, "searchSpan":{ "from":"2017-04-30T23:00:00.000Z", "to":"2017-05-01T00:00:00.000Z" }, "aggregates":[{ "dimension":{ "dateHistogram":{ "input":{ "builtInProperty":"$ts" }, "breaks":{ "size":"1m" } } }, "measures":[{ "count":{} }] }] } }응답 메시지 예제:
{ "headers":{ "x-ms-request-id":"abc3243-23af-23ad-3224s-a32525age" }, "content":[ { "dimension":[ "2017-04-30T23:00:00Z", "2017-04-30T23:01:00Z", "2017-04-30T23:02:00Z", "2017-04-30T23:03:00Z", "2017-04-30T23:04:00Z" ], "measures":[ [ 722 ], [ 721 ], [ 722 ], [ 721 ], [ 722 ] ] } ], "warnings":[ ], "percentCompleted":100 }측정값 식을 지정하지 않고 이벤트 목록이 비어 있으면 응답이 비어 있습니다.
측정값이 있는 경우 응답에는 차원 값,
0개수 값 및 다른 종류의 측정값에 대한 값이 포함된null단일 레코드null가 포함됩니다.
제한
여러 환경 및 사용자 간에 리소스를 상당히 활용하기 위해 쿼리 실행 중에 다음 제한이 적용됩니다.
| 적용 가능한 API | 제한 이름 | 제한 값 | 영향을 받는 SKU | 참고 |
|---|---|---|---|---|
| 모두 | 최대 요청 크기 | 32KB | S1, S2 | |
| 환경 가용성 가져오기, 환경 메타데이터 가져오기, 환경 이벤트 가져오기, 환경 집계 스트리밍 가져오기 | 환경당 최대 동시 요청 수 | 10 | S1, S2 | |
| 환경 이벤트 가져오기, 환경 집계 스트리밍 가져오기 | 최대 응답 크기 | 16MB | S1, S2 | |
| 환경 이벤트 가져오기, 환경 집계 스트리밍 가져오기 | 조건자 문자열 식을 포함하여 조건자의 최대 고유 속성 참조 수 | 50 | S1, S2 | |
| 환경 이벤트 가져오기, 환경 집계 스트리밍 가져오기 | 조건자 문자열에 속성 참조가 없는 최대 전체 텍스트 검색어 | 2 | S1, S2 | 예: HAS 'abc', 'abc' |
| 환경 이벤트 가져오기 | 응답의 최대 이벤트 수 | 10000 | S1, S2 | |
| 스트리밍된 환경 집계 가져오기 | 최대 차원 수 | 5 | S1, S2 | |
| 스트리밍된 환경 집계 가져오기 | 모든 차원의 최대 총 카디널리티 | 150,000 | S1, S2 | |
| 스트리밍된 환경 집계 가져오기 | 최대 측정값 수 | 20 | S1, S2 |
오류 처리 및 해결
속성 찾을 수 없음 동작
조건자의 일부 또는 집계(측정값)의 일부로 쿼리에서 참조되는 속성의 경우 기본적으로 쿼리는 환경의 전역 검색 범위에서 속성을 resolve 시도합니다. 속성이 있으면 쿼리가 성공합니다. 속성을 찾을 수 없으면 쿼리가 실패합니다.
그러나 이 동작을 수정하여 속성을 기존 속성으로 처리하지만 환경에 없는 경우 값으로 null 처리할 수 있습니다. 이 작업은 값UseNull으로 선택적 요청 헤더 x-ms-property-not-found-behavior 를 설정하여 수행합니다.
요청 헤더에 대한 가능한 값은 또는 ThrowError (기본값)입니다UseNull. 값으로 설정 UseNull 하면 속성이 없더라도 쿼리가 성공하고, 찾을 수 없는 속성을 표시하는 경고가 응답에 포함됩니다.
해결되지 않은 속성 보고
조건자, 차원 및 측정값 식에 대한 속성 참조를 지정할 수 있습니다. 특정 이름 및 형식의 속성이 지정된 검색 범위에 존재하지 않는 경우 전역 시간 범위 동안 속성을 resolve 시도합니다.
해결 성공에 따라 다음 경고 또는 오류가 내보내질 수 있습니다.
- 전역 시간 범위 동안 환경에 속성이 있는 경우 해당 속성이 적절하게 확인되고 이 속성의 값이 지정된 검색 범위에 대한 값임을
null알리는 경고가 내보내집니다. - 환경에 속성이 없으면 오류가 내보내지고 쿼리 실행이 실패합니다.
오류 응답
쿼리 실행이 실패하면 JSON 응답 페이로드에는 다음 구조의 오류 응답이 포함됩니다.
{
"error" : {
"code" : "...",
"message" : "...",
"innerError" : {
"code" : "...",
"message" : "...",
}
}
}
여기서 는 innerError 선택 사항입니다. 잘못된 형식의 요청과 같은 기본 오류 외에도 다음 오류가 반환됩니다.
| HTTP 상태 코드 | 오류 코드 | 오류 메시지의 예 | 가능한 내부 오류 코드 |
|---|---|---|---|
| 400 | InvalidApiVersion | "API 버전 '2016'은 지원되지 않습니다. 지원되는 버전은 '2016-12-12'입니다." | |
| 400 | InvalidInput | "조건자 문자열을 구문 분석할 수 없습니다." | PredicateStringParseError |
| 400 | InvalidInput | "조건자 문자열을 번역할 수 없습니다." |
InvalidTypes, LimitExceeded, MissingOperand, InvalidPropertyType, InvalidLiteral, PropertyNotFound |
| 400 | InvalidInput | "여러 집계는 지원되지 않습니다." | |
| 400 | InvalidInput | "조건자 속성을 찾을 수 없습니다." | PropertyNotFound |
| 400 | InvalidInput | "측정값 속성을 찾을 수 없습니다." | PropertyNotFound |
| 400 | InvalidInput | "Dimension 속성을 찾을 수 없습니다." | PropertyNotFound |
| 400 | InvalidInput | "측정값 수가 한도를 초과했습니다." | NumberOfMeasuresExceededLimit |
| 400 | InvalidInput | "집계 깊이가 제한을 초과했습니다." | AggregateDepthExceededLimit |
| 400 | InvalidInput | "총 카디널리티가 한도를 초과했습니다." | TotalCardinalityExceededLimit |
| 400 | InvalidInput | "'from' 속성이 없습니다." | BreaksPropertyMissing |
| 400 | InvalidInput | "속성 'to'이(가) 없습니다." | BreaksPropertyMissing |
| 400 | InvalidInput | "요청 크기가 제한을 초과했습니다." | RequestSizeExceededLimit |
| 400 | InvalidInput | "응답 크기가 제한을 초과했습니다." | ResponseSizeExceededLimit |
| 400 | InvalidInput | "이벤트 수가 제한을 초과했습니다." | EventCountExceededLimit |
| 400 | InvalidInput | "속성 참조 수가 제한을 초과했습니다." | PropertyReferenceCountExceededLimit |
| 400 | InvalidMethod | "경로 '집계'에서 WebSocket 요청만 허용됩니다." | |
| 400 | InvalidUrl | "요청 URL '/a/b'를 구문 분석할 수 없습니다." | |
| 408 | RequestTimeout | "요청 시간이 '30' 초 후에 초과되었습니다." | |
| 503 | TooManyRequests | "'10'의 동시 요청 수가 '95880732-01b9-44ea-8d2d-4d764dfe1904' 환경에 대해 초과되었습니다." | EnvRequestLimitExceeded |
경고
쿼리 API 응답에는 HTTP 응답 또는 WebSocket 응답 메시지의 루트 아래에 항목으로 "warnings" 경고 목록이 포함될 수 있습니다. 현재 지정된 검색 범위에 대한 속성을 찾을 수 없지만 전역 시간 범위에 대한 환경에서 찾을 수 있는 경우 경고가 생성됩니다. 헤더가 로 설정 UseNull 되고 참조되는 x-ms-property-not-found-behavior 속성이 전역 검색 범위에도 없는 경우에도 생성됩니다.
각 경고 개체에는 다음 필드가 포함될 수 있습니다.
| 필드 이름 | 필드 형식 | 참고 |
|---|---|---|
| code | String | 미리 정의된 경고 코드 중 하나 |
| message | String | 자세한 경고 메시지 |
| 대상 | String | 경고의 원인이 되는 JSON 입력 페이로드 항목에 대한 점으로 구분된 JSON 경로 |
| warningDetails | Dictionary | 선택적; 추가 경고 세부 정보(예: 조건자 문자열의 위치) |
다음 코드는 조건자, 차원 및 측정값 내의 조건자, 조건자 문자열에 대한 경고 예제를 제공합니다.
"warnings": [
{
"code": "PropertyNotFound",
"message": "Predicate property 'X' of type 'String' is not found in local search span.",
"target": "predicate.and[0].eq.left.property.name"
},
{
"code": "PropertyNotFound",
"message": "Predicate string property 'X' is not found in local search span.",
"target": "predicate.and[1].predicateString",
"warningDetails": {
"startPos": 1,
"endPos": 2,
"line": 1,
"col": 1
}
},
{
"code": "PropertyNotFound",
"message": "Dimension property 'X' of type 'String' is not found in local search span.",
"target": "aggregates.dimension.uniqueValues.input.property"
},
{
"code": "PropertyNotFound",
"message": "Measure property 'X' of type 'String' is not found in local search span.",
"target": "aggregates.aggregates.measures[0].min.input.property"
}
]
추가 정보
애플리케이션 등록 및 Azure Active Directory 프로그래밍 모델에 대한 자세한 내용은 개발자용 Azure Active Directory를 참조하세요.
요청 및 인증 매개 변수에 대한 자세한 내용은 인증 및 권한 부여를 참조하세요.
HTTP 요청 및 응답 테스트를 지원하는 도구는 다음과 같습니다.
- Fiddler. 이 무료 웹 디버깅 프록시는 REST 요청을 가로챌 수 있으므로 HTTP 요청 및 응답 메시지를 진단할 수 있습니다.
- JWT.io. 이 도구를 사용하여 전달자 토큰에서 클레임을 신속하게 덤프한 다음 해당 콘텐츠의 유효성을 검사할 수 있습니다.
- 포스트맨. REST API를 디버깅하기 위한 무료 HTTP 요청 및 응답 테스트 도구입니다.
Gen1 설명서를 검토하여 Azure Time Series Insights Gen1에 대해 자세히 알아보세요.