API запросов Аналитика временных рядов Azure 1-го поколения

В этой статье описываются различные API запросов REST. REST API — это конечные точки служб, поддерживающие наборы http-операций (методов), которые позволяют запрашивать Аналитика временных рядов Azure средах 1-го поколения.

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. Доступность среды кэшируется, а время отклика не зависит от количества событий в среде.

• Конечная точка и операция:

  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 группирует события по указанному свойству, так как при необходимости измеряет значения других свойств.

• Конечная точка и операция:

  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) всех значений.
• Клиент может отменить предыдущие пакеты.

• Конечная точка и операция:

  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 для других типов мер.

Ограничения

Следующие ограничения применяются во время выполнения запроса, чтобы справедливо использовать ресурсы между несколькими средами и пользователями:

Обработка и устранение ошибок

Поведение свойства не найдено

Для свойств, на которые ссылается запрос( как часть предикатов или часть агрегатов (мер), по умолчанию запрос пытается разрешить свойство в глобальный поиск диапазоне среды. Если свойство найдено, запрос выполняется успешно. Если свойство не найдено, запрос завершается ошибкой.

Однако это поведение можно изменить, чтобы свойства рассматривались как существующие, но со значениями null , если они отсутствуют в среде. Для этого задав для необязательного заголовка x-ms-property-not-found-behavior запроса значение UseNull.

Возможные значения заголовка запроса: UseNull или ThrowError (по умолчанию). Если в качестве значения задано UseNull значение, запрос будет выполнен успешно, даже если свойства не существуют, а ответ будет содержать предупреждения, отображающие свойства, которые не найдены.

Отчет о неразрешенных свойствах

Можно указать ссылки на свойства для выражений предикатов, измерений и мер. Если свойство с определенным именем и типом не существует для указанного диапазона поиска, предпринимается попытка разрешить свойство в течение глобального интервала времени.

В зависимости от успешности решения может быть выдано следующее предупреждение или ошибка:

• Если свойство существует в среде в течение глобального периода времени, оно разрешается соответствующим образом, и выдается предупреждение, уведомляющее вас о том, что значение этого свойства соответствует null заданному диапазону поиска.
• Если свойство не существует в среде, возникает ошибка и выполнение запроса завершается ошибкой.

Сообщения об ошибках

Если выполнение запроса завершается сбоем, полезные данные ответа JSON содержат ответ об ошибке со следующей структурой:

{
  "error" : {
    "code" : "...",
    "message" : "...",
    "innerError" : {  
      "code" : "...",
      "message" : "...",
    }
  }
}

Здесь является innerError необязательным. Помимо основных ошибок, таких как неправильный запрос, возвращаются следующие ошибки:

Предупреждения

Ответ API запроса может содержать список предупреждений в виде "warnings" записи в корне ответа HTTP или ответного сообщения WebSocket. В настоящее время предупреждения создаются, если свойство не найдено для заданного диапазона поиска, но найдено в среде для глобального интервала времени. Он также создается, если для заголовка x-ms-property-not-found-behavior задано значение UseNull , а свойство, на которое ссылается ссылка, не существует даже в глобальный поиск диапазоне.

Каждый объект предупреждения может содержать следующие поля:

В следующем коде представлены примеры предупреждений для предиката, строки предиката в предикате, измерении и мере:

"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.