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

Статья
07/19/2023

Внимание!

Эта статья посвящена службе "Аналитика временных рядов Azure" 1-го поколения.

В этой статье описывается API справочника Управление данными Аналитика временных рядов Azure 1-го поколения, который используется для управления элементами в эталонном наборе данных. Предполагается, что эталонный набор данных уже создан в среде.

Эталонные данные включают данные о изготовителе или расположении, которые изменяются редко. Эталонные данные используются для контекстуализации данных телеметрии и служат для сравнения данных телеметрии.

Совет

Сведения о создании эталонного набора данных см. в статье Создание эталонного набора данных.

Так как наборы данных уже существуют и исправлены, каждый пакет данных, отправляемый устройством, будет содержать идентичные сведения. Следовательно, эталонные данные не отправляются с устройств, и вы управляете ими с помощью API эталонного Управление данными или портал Azure.

Обзор API

Api эталонного Управление данными является пакетным API.

Важно!

Все операции с этим API являются операциями HTTP POST.
Каждая операция принимает объекты JSON в качестве полезных данных запроса.
Объекты JSON HTTP-запроса определяют одно имя свойства, указывающее операцию, выполняемую API.

Допустимые имена свойств операции запроса JSON:

Положить
Обновление
Удаление свойств
Удалить
Get

Важно!

Значение свойства представляет собой массив элементов ссылочных данных, к которым должна применяться операция.
Каждый элемент обрабатывается по отдельности, и ошибка с одним элементом не препятствует успешной записи других элементов. Например, если запрос содержит 100 элементов и один элемент содержит ошибку, записывается 99 элементов, а один отклоняется.
Элементы эталонных данных запрашиваются с использованием их полностью перечислимых ключевых свойств.

Примечание

Во всех приведенных ниже примерах текста JSON предполагается, что эталонный набор данных с одним ключом свойства с именем deviceId и типом String.

Размещение элементов ссылочных данных

Вставляет или заменяет весь элемент $.put[i] ссылочных данных (^i-й элемент в массиве с помещенным ключом). Единица фиксации — $.put[i]. Операция идемпотентна.

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

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 reference Управление данными обрабатывает каждый элемент по отдельности, и ошибка с одним элементом не препятствует успешной записи других элементов. Например, если запрос содержит 100 элементов и один элемент содержит ошибку, записывается 99 элементов, а один отклоняется.

Коды ошибок элемента

Коды ошибок элемента возникают в успешном тексте ответа JSON с кодом состояния HTTP 200.

InvalidInput: ключ не найден. Указывает, что запрашиваемый элемент не найден в эталонном наборе данных.
```
{
  "code": "InvalidInput",
  "message": "Key not found.",
  "target": null,
  "details": null,
  "innerError": null
}
```
InvalidInput: ключ полезных данных не должен содержать неключевых свойств.: указывает, что элементы запроса текста запроса JSON не должны содержать свойства, которые не являются ключевыми свойствами (т. е. свойства, указанные в схеме набора ссылок). Ключевые свойства можно найти в портал Azure.
```
{
  "code": "InvalidInput",
  "message": "Payload key should not contain any non-key property.",
  "target": null,
  "details": null,
  "innerError": null
}
```
InvalidInput: элемент полезных данных должен содержать все ключевые свойства. Указывает, что элементы запроса текста запроса JSON должны включать все ключевые свойства (т. е. свойства, указанные в схеме набора ссылок). Ключевые свойства можно найти в портал Azure.
```
{
  "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"
  }
]

Рассмотрим элемент эталонных данных, который задается с именем contoso и ключом deviceId типа String и имеет следующую структуру:

deviceId	color	maxSpeed	floor
Fan1	Красный	5
Fan2	White		2

Когда два события в сообщении концентратора событий обрабатываются подсистемой входящего трафика Аналитика временных рядов Azure 1-го поколения, они объединяются с правильным элементом ссылочных данных. Выходные данные событий имеют следующую структуру:

[
  {
    "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 1-го поколения можно добавить до двух эталонных наборов данных. Дополнительные ограничения, связанные со справочными данными Аналитика временных рядов Azure 1-го поколения, перечислены в следующей таблице:

Имя ограничения	Предельное значение	Затронутые номера SKU	Примечания
Число свойств ключей	3	S1, S2	На ссылочный набор данных; Только Resource Manager Azure и портал Azure
Размер свойства ключа	1 КБ	S1, S2	На ссылочный набор данных
Количество элементов ссылочных данных	2 000/20 000 (S1/S2)	S1, S2	На единицу; Например, 4 единицы SKU S1 = 8000 элементов (4 x 2000)
Максимальное количество одновременных транзакций	2/10 (S1/S2)	S1, S2
Максимальное число транзакций ссылочных данных	120/600 (S1/S2)	S1, S2	Почасовая
Максимальное число элементов ссылочных данных	1000	S1, S2	За транзакцию
Максимальный размер элемента ссылочных данных	8 192 КБ	S1, S2	За транзакцию

См. также раздел

Дополнительные сведения о регистрации приложений и модели программирования Azure Active Directory см. в статье Azure Active Directory для разработчиков.

Дополнительные сведения о параметрах запроса и проверки подлинности см. в статье Проверка подлинности и авторизация.

Ниже представлены средства, помогающие тестировать HTTP-запросы и ответы.

Фиддлер. Этот бесплатный прокси-сервер веб-отладки может перехватывать запросы REST, чтобы можно было диагностировать HTTP-запросы и ответные сообщения.
JWT.io. Это средство можно использовать для быстрого дампа утверждений в маркере носителя, а затем для проверки их содержимого.
Postman. Это бесплатное средство тестирования HTTP-запросов и ответов для отладки REST API.

Дополнительные сведения о Аналитика временных рядов Azure 1-го поколения см. в документации 1-го поколения.

Поделиться через

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

Обзор API

Размещение элементов ссылочных данных

Исправление элементов ссылочных данных

Удаление свойств в элементах ссылочных данных

Удаление элементов ссылочных данных

Получение элементов эталонных данных

Проверка и обработка ошибок

Коды ошибок элемента

Пример соединения эталонных данных

Правила и семантика соединения

Текущие ограничения

См. также раздел

Дополнительные ресурсы