Azure Time Series Insights Gen1 Query API
Caution
This is a Gen1 article.
This article describes various REST Query APIs. REST APIs are service endpoints that support sets of HTTP operations (methods), which enable you to query Azure Time Series Insights Gen1 environments.
Important
- Azure Time Series Insights Gen1 uses the HTTPS Protocol for the Get Environments, Get Environment Availability, Get Metadata, Get Environment Events, and Get Environment Aggregates APIs.
- Azure Time Series Insights Gen1 uses the WebSocket Secure (WSS) Protocol for the Get Environment Events Streamed and Get Aggregates Streamed APIs.
Get Environments API
The Get Environments API returns the list of environments that the caller is authorized to access.
Endpoint and operation:
GET https://api.timeseries.azure.com/environments?api-version=2016-12-12Example request body: Not applicable
Example response body:
{ "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" ] } ] }Note
The response property environmentFqdn is a unique, fully-qualified domain name for the environment that's used in per-environment Query API requests.
Get Environment Availability API
The Get Environment Availability API returns the distribution of event count over the event timestamp $ts. Environment availability is cached, and the response time does not depend on the number of events in an environment.
Tip
The Get Environment Availability API can be used to initialize a front-end UI experience.
Endpoint and operation:
GET https://<environmentFqdn>/availability?api-version=2016-12-12Example request body: Not applicable
Example response body:
{ "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 } }An empty object is returned for environments with no events.
Get Environment Metadata API
The Get Environment Metadata API returns environment metadata for a given search span. Metadata is returned as a set of property references. Azure Time Series Insights Gen1 internally caches and approximates metadata and may return more properties that are present in the exact events in the search span.
Endpoint and operation:
POST https://<environmentFqdn>/metadata?api-version=2016-12-12Input payload structure:
- Search span clause (mandatory)
Example request body:
{ "searchSpan": { "from": {"dateTime":"2016-08-01T00:00:00.000Z"}, "to": {"dateTime":"2016-08-31T00:00:00.000Z"} } }Example response body:
{ "properties": [ { "name": "sensorId", "type": "String" }, { "name": "sensorValue", "type": "Double" }, { "name": "iothub-connection-device-id", "type": "String" } ] }An empty
propertiesarray is returned when the environment is empty or there are no events in a search span.Built-in properties are not returned in the list of properties.
Get Environment Events API
The Get Environment Events API returns a list of raw events that match the search span and predicate.
Endpoint and operation:
POST https://<environmentFqdn>/events?api-version=<apiVersion>Input payload structure:
- Search span clause (mandatory)
- Predicate clause (optional)
- Limit clause (mandatory)
Example request body:
{ "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 } }Note
- Nested sorting (that is, sorting by two or more properties) is currently not supported.
- Events can be sorted and limited to the top.
- Sorting is supported on all property types. Sorting relies on comparison operators that are defined for Boolean expressions.
Example response body:
{ "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
The Get Environment Events Streamed API returns a list of raw events that match the search span and predicate.
This API uses the WebSocket Secure Protocol to do streaming and return partial results. It always returns additional events. That is, the new message is additive to the previous one. The new message contains new events that were not in the previous message. The previous message should be kept when the new message is added.
Endpoint and operation:
GET wss://<environmentFqdn>/events?api-version=<apiVersion>Input payload structure:
- Search span clause (mandatory)
- Predicate clause (optional)
- Limit clause (mandatory)
Example request message:
{ "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 } } }Note
- Nested sorting (that is, sorting by two or more properties) is currently not supported.
- Events can be sorted and limited to the top.
- Sorting is supported on all property types. Sorting relies on comparison operators that are defined for Boolean expressions.
Example response message:
{ "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
The Get Environment Aggregates API groups events by a specified property as it optionally measures the values of other properties.
Note
Bucket boundaries support 10ⁿ, 2×10ⁿ, or 5×10ⁿ values to align with and better support numeric histograms.
Endpoint and operation:
POST https://<environmentFqdn>/aggregates?api-version=<apiVersion>Input payload structure:
- Search span clause (mandatory)
- Predicate clause (optional)
- Aggregates clause (mandatory)
Example request body:
{ "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": {} } ] } } ] }Example response body:
{ "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": [] }If no measure expressions are specified and the list of events is empty, the response will be empty.
If measures are present, the response contains a single record with a
nulldimension value, a0value for count, and anullvalue for other kinds of measures.
Get Environment Aggregates Streamed API
The Get Environment Aggregates Streamed API groups events by a specified property as it optionally measures the values of other properties:
- This API uses the WebSocket Secure Protocol for streaming and to return partial results.
- It always returns a replacement (snapshot) of all the values.
- Previous packets can be discarded by the client.
Note
Bucket boundaries support 10ⁿ, 2×10ⁿ, or 5×10ⁿ values to align with and better support numeric histograms.
Endpoint and operation:
GET wss://<environmentFqdn>/aggregates?api-version=<apiVersion>Input payload structure:
- Search span clause (mandatory)
- Predicate clause (optional)
- Aggregates clause (mandatory)
Example request message:
{ "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":{} }] }] } }Example response messages:
{ "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 }If no measure expressions are specified and the list of events is empty, the response will be empty.
If measures are present, the response contains a single record with a
nulldimension value, a0value for count, and anullvalue for other kinds of measures.
Limits
The following limits are applied during query execution to fairly utilize resources among multiple environments and users:
| Applicable APIs | Limit name | Limit value | SKUs affected | Notes |
|---|---|---|---|---|
| All | Max request size | 32 KB | S1, S2 | |
| Get Environment Availability, Get Environment Metadata, Get Environment Events, Get Environment Aggregates Streamed | Max number of concurrent requests per environment | 10 | S1, S2 | |
| Get Environment Events, Get Environment Aggregates Streamed | Max response size | 16 MB | S1, S2 | |
| Get Environment Events, Get Environment Aggregates Streamed | Max number of unique property references in predicate, including predicate string expressions | 50 | S1, S2 | |
| Get Environment Events, Get Environment Aggregates Streamed | Max full-text search terms with no property reference in predicate string | 2 | S1, S2 | Example: HAS 'abc', 'abc' |
| Get Environment Events | Max number of events in response | 10,000 | S1, S2 | |
| Get Environment Aggregates Streamed | Max number of dimensions | 5 | S1, S2 | |
| Get Environment Aggregates Streamed | Max total cardinality across all dimensions | 150,000 | S1, S2 | |
| Get Environment Aggregates Streamed | Max number of measures | 20 | S1, S2 |
Error handling and resolution
Property Not Found behavior
For properties referenced in the query, either as part of predicates or part of aggregates (measures), by default, the query tries to resolve the property in the global search span of the environment. If the property is found, the query succeeds. If the property is not found, the query fails.
However, you can modify this behavior to treat properties as existing but with null values if they are not present in the environment. You do this by setting the optional request header x-ms-property-not-found-behavior with the value UseNull.
Possible values for the request header are UseNull or ThrowError (default). When you set UseNull as the value, the query will succeed even though the properties do not exist, and the response will contain warnings that display the properties that are not found.
Report unresolved properties
You can specify property references for predicate, dimension, and measure expressions. If a property with a specific name and type doesn't exist for a specified search span, an attempt is made to resolve a property over a global time span.
Depending on the success of resolution, the following warning or error might be emitted:
- If a property exists in the environment over a global time span, it is resolved appropriately, and a warning is emitted to notify you that the value of this property is
nullfor a given search span. - If a property does not exist in the environment, an error is emitted, and the query execution fails.
Error responses
If the query execution fails, the JSON response payload contains an error response with the following structure:
{
"error" : {
"code" : "...",
"message" : "...",
"innerError" : {
"code" : "...",
"message" : "...",
}
}
}
Here, innerError is optional. In addition to basic errors, such as a malformed request, the following errors are returned:
| HTTP status code | Error code | Example of error message | Possible inner error codes |
|---|---|---|---|
| 400 | InvalidApiVersion | "API version '2016' is not supported. Supported versions are '2016-12-12'." | |
| 400 | InvalidInput | "Unable to parse predicate string." | PredicateStringParseError |
| 400 | InvalidInput | "Unable to translate predicate string." | InvalidTypes, LimitExceeded, MissingOperand, InvalidPropertyType, InvalidLiteral, PropertyNotFound |
| 400 | InvalidInput | "Multiple aggregates are not supported." | |
| 400 | InvalidInput | "Predicate property not found." | PropertyNotFound |
| 400 | InvalidInput | "Measure property not found." | PropertyNotFound |
| 400 | InvalidInput | "Dimension property not found." | PropertyNotFound |
| 400 | InvalidInput | "Number of measures exceeded limit." | NumberOfMeasuresExceededLimit |
| 400 | InvalidInput | "Aggregate depth exceeded limit." | AggregateDepthExceededLimit |
| 400 | InvalidInput | "Total cardinality exceeded limit." | TotalCardinalityExceededLimit |
| 400 | InvalidInput | "Property 'from' is missing." | BreaksPropertyMissing |
| 400 | InvalidInput | "Property 'to' is missing." | BreaksPropertyMissing |
| 400 | InvalidInput | "Request size exceeded limit." | RequestSizeExceededLimit |
| 400 | InvalidInput | "Response size exceeded limit." | ResponseSizeExceededLimit |
| 400 | InvalidInput | "Event count exceeded limit." | EventCountExceededLimit |
| 400 | InvalidInput | "Property reference count exceeded limit." | PropertyReferenceCountExceededLimit |
| 400 | InvalidMethod | "Only WebSocket requests are allowed on the path 'aggregates'." | |
| 400 | InvalidUrl | "The request URL '/a/b' could not be parsed." | |
| 408 | RequestTimeout | "Request timed out after '30' second(s)." | |
| 503 | TooManyRequests | "Concurrent request count of '10' exceeded for environment '95880732-01b9-44ea-8d2d-4d764dfe1904'." | EnvRequestLimitExceeded |
Warnings
A Query API response may contain a list of warnings as "warnings" entry under the root of the HTTP response or WebSocket response message. Currently warnings are generated if property is not found for a given search span but is found in an environment for global time span. It is also generated when the header x-ms-property-not-found-behavior is set to UseNull and a property that is referenced does not exist even in the global search span.
Each warning object may contain the following fields:
| Field name | Field type | Notes |
|---|---|---|
| code | String | One of the predefined warning codes |
| message | String | A detailed warning message |
| target | String | A dot-separated JSON path to the JSON input payload entry causing the warning |
| warningDetails | Dictionary | Optional; additional warning details (for example, the position in predicate string) |
The following code presents examples of warnings for predicate, predicate string within predicate, dimension, and measure:
"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"
}
]
See also
For more information about application registration and the Azure Active Directory programming model, see Azure Active Directory for developers.
To learn about request and authentication parameters, see Authentication and authorization.
Tools that assist with testing HTTP requests and responses include:
- Fiddler. This free web debugging proxy can intercept your REST requests, so you can diagnose the HTTP request and response messages.
- JWT.io. You can use this tool to quickly dump the claims in your bearer token and then validate their contents.
- Postman. This is a free HTTP request and response testing tool for debugging REST APIs.
Learn more about Azure Time Series Insights Gen1 by reviewing the Gen1 documentation.