API запросов Аналитика временных рядов Azure 1-го поколения
Внимание!
Эта статья посвящена службе "Аналитика временных рядов Azure" 1-го поколения.
В этой статье описываются различные API запросов REST. REST API — это конечные точки служб, поддерживающие наборы http-операций (методов), которые позволяют запрашивать Аналитика временных рядов Azure средах 1-го поколения.
Важно!
- Аналитика временных рядов Azure 1-го поколения использует протокол HTTPS для API получения сред, получения доступности среды, получения метаданных, получения событий среды и получения статистических выражений среды.
- Аналитика временных рядов Azure 1-го поколения использует протокол WebSocket Secure (WSS) для API Get Environment Streamed и Get Aggregates Streamed.
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 запросов для каждой среды.
API получения доступных событий в среде;
API получения доступности среды возвращает распределение количества событий по метке времени события $ts. Доступность среды кэшируется, а время отклика не зависит от количества событий в среде.
Совет
API получения доступности среды можно использовать для инициализации интерфейсного интерфейса.
Конечная точка и операция:
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 1-го поколения внутренне кэширует и аппроксимирует метаданные и может возвращать дополнительные свойства, которые присутствуют в точных событиях в диапазоне поиска.
Конечная точка и операция:
POST https://<environmentFqdn>/metadata?api-version=2016-12-12Структура полезных данных входных данных:
- Предложение Search span (обязательно)
Пример тела запроса:
{ "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>Структура полезных данных входных данных:
- Предложение Search span (обязательно)
- Предложение Предиката (необязательно)
- Предложение 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] } ] }
API получения событий в среде в формате потоковой передачи;
API получения потоковой передачи событий среды возвращает список необработанных событий, соответствующих диапазону поиска и предикату.
Этот API использует протокол WebSocket Secure Для выполнения потоковой передачи и возврата частичных результатов. Он всегда возвращает дополнительные события. То есть новое сообщение является дополнением к предыдущему. Новое сообщение содержит новые события, которые не были в предыдущем сообщении. Предыдущее сообщение следует сохранить при добавлении нового сообщения.
Конечная точка и операция:
GET wss://<environmentFqdn>/events?api-version=<apiVersion>Структура полезных данных входных данных:
- Предложение Search span (обязательно)
- Предложение Предиката (необязательно)
- Предложение 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 }
API получения статистических данных среды.
API Get Environment Aggregates группирует события по указанному свойству, так как при необходимости измеряет значения других свойств.
Примечание
Границы контейнеров поддерживают значения 10ⁿ, 2×10ⁿ или 5×10ⁿ для выравнивания и лучшей поддержки числовых гистограмм.
Конечная точка и операция:
POST https://<environmentFqdn>/aggregates?api-version=<apiVersion>Структура полезных данных входных данных:
- Предложение Search span (обязательно)
- Предложение Предиката (необязательно)
- Предложение 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": [] }Если выражения мер не указаны и список событий пуст, ответ будет пустым.
Если меры присутствуют, ответ содержит одну запись со значением
nullизмерения, значением0для счетчика и значениемnullдля других типов мер.
API получения статистических данных среды в формате потоковой передачи.
Api Получения агрегатов среды streamed группирует события по указанному свойству, так как при необходимости измеряет значения других свойств:
- Этот API использует протокол WebSocket Secure для потоковой передачи и возврата частичных результатов.
- Он всегда возвращает замену (snapshot) всех значений.
- Клиент может отменить предыдущие пакеты.
Примечание
Границы контейнеров поддерживают значения 10ⁿ, 2×10ⁿ или 5×10ⁿ для выравнивания и лучшей поддержки числовых гистограмм.
Конечная точка и операция:
GET wss://<environmentFqdn>/aggregates?api-version=<apiVersion>Структура полезных данных входных данных:
- Предложение Search span (обязательно)
- Предложение Предиката (необязательно)
- Предложение 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 }Если выражения мер не указаны и список событий пуст, ответ будет пустым.
Если меры присутствуют, ответ содержит одну запись со значением
nullизмерения, значением0для счетчика и значениемnullдля других типов мер.
Ограничения
Следующие ограничения применяются во время выполнения запроса, чтобы справедливо использовать ресурсы между несколькими средами и пользователями:
| Применимые API | Имя ограничения | Предельное значение | Затронутые номера SKU | Примечания |
|---|---|---|---|---|
| Все | Максимальный размер запроса | 32 КБ | S1, S2 | |
| Получение доступности среды, получение метаданных среды, получение событий среды, получение потоковой передачи статистических выражений среды | Максимальное число одновременных запросов на среду | 10 | S1, S2 | |
| Получение событий среды, получение потоковой передачи статистических выражений среды | Максимальный размер ответа | 16 МБ | S1, S2 | |
| Получение событий среды, получение потоковой передачи статистических выражений среды | Максимальное число уникальных ссылок на свойства в предикате, включая строковые выражения предиката | 50 | S1, S2 | |
| Получение событий среды, получение потоковой передачи статистических выражений среды | Максимальное число терминов полнотекстового поиска без ссылки на свойство в строке предиката | 2 | S1, S2 | Пример: HAS 'abc', 'abc'. |
| Получение событий среды | Максимальное число событий в ответе | 10 000 | S1, S2 | |
| Получение потоковой передачи статистических выражений среды | Максимальное число измерений | 5 | S1, S2 | |
| Получение потоковой передачи статистических выражений среды | Максимальная общая кратность во всех измерениях | 150 000 | S1, S2 | |
| Получение потоковой передачи статистических выражений среды | Максимальное число мер | 20 | S1, S2 |
Обработка и устранение ошибок
Поведение свойства не найдено
Для свойств, на которые ссылается запрос( как часть предикатов или часть агрегатов (мер), по умолчанию запрос пытается разрешить свойство в глобальный поиск диапазоне среды. Если свойство найдено, запрос выполняется успешно. Если свойство не найдено, запрос завершается ошибкой.
Однако это поведение можно изменить, чтобы свойства рассматривались как существующие, но со значениями null , если они отсутствуют в среде. Для этого задав для необязательного заголовка x-ms-property-not-found-behavior запроса значение UseNull.
Возможные значения заголовка запроса: UseNull или ThrowError (по умолчанию). Если в качестве значения задано UseNull значение, запрос будет выполнен успешно, даже если свойства не существуют, а ответ будет содержать предупреждения, отображающие свойства, которые не найдены.
Отчет о неразрешенных свойствах
Можно указать ссылки на свойства для выражений предикатов, измерений и мер. Если свойство с определенным именем и типом не существует для указанного диапазона поиска, предпринимается попытка разрешить свойство в течение глобального интервала времени.
В зависимости от успешности решения может быть выдано следующее предупреждение или ошибка:
- Если свойство существует в среде в течение глобального периода времени, оно разрешается соответствующим образом, и выдается предупреждение, уведомляющее вас о том, что значение этого свойства соответствует
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 разрешены по пути "aggregates". | |
| 400 | InvalidUrl | "Не удалось проанализировать URL-адрес запроса "/a/b"." | |
| 408 | RequestTimeout | "Время ожидания запроса истекло после 30 секунд". | |
| 503 | TooManyRequests | "Превышено число одновременных запросов "10" для среды "95880732-01b9-44ea-8d2d-4d764dfe1904". | EnvRequestLimitExceeded |
Предупреждения
Ответ API запроса может содержать список предупреждений в виде "warnings" записи в корне ответа HTTP или ответного сообщения WebSocket. В настоящее время предупреждения создаются, если свойство не найдено для заданного диапазона поиска, но найдено в среде для глобального интервала времени. Он также создается, если для заголовка x-ms-property-not-found-behavior задано значение UseNull , а свойство, на которое ссылается ссылка, не существует даже в глобальный поиск диапазоне.
Каждый объект предупреждения может содержать следующие поля:
| Имя поля | Тип поля | Примечания |
|---|---|---|
| code | String | Один из стандартных кодов предупреждений |
| message | String | Подробное предупреждающее сообщение |
| target | String | Разделенный точками путь JSON к входной записи полезных данных JSON, вызывающий предупреждение |
| warningDetails | Словарь | Дополнительные; дополнительные сведения о предупреждении (например, позиция в строке предиката) |
В следующем коде представлены примеры предупреждений для предиката, строки предиката в предикате, измерении и мере:
"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. Это средство можно использовать для быстрого дампа утверждений в маркере носителя, а затем проверки их содержимого.
- Почтальо. Это бесплатное средство тестирования HTTP-запросов и ответов для отладки REST API.
Дополнительные сведения о Аналитика временных рядов Azure 1-го поколения см. в документации по Gen1.