Отчёт о метрике пользовательского устройства

Материал из Документация Ключ-АСТРОМ
Версия от 14:33, 13 октября 2022; ENetrebin (обсуждение | вклад) (→‎Результат)
(разн.) ← Предыдущая | Текущая версия (разн.) | Следующая → (разн.)

Конечная точка пользовательского устройства API топологии и Smartscape позволяет отправлять точку данных пользовательской метрики на пользовательское устройство в Ключ-АСТРОМ. Этот запрос также может обновлять метаданные пользовательского устройства.

Метрика, о которой вы сообщаете, уже должна существовать в Ключ-АСТРОМ.

Чтобы узнать, как создать пользовательскую метрику, см. статью Timeseries API v1 — ВСТАВКА пользовательской метрики .

См. раздел Создание пользовательского устройства с помощью Ключ-АСТРОМ API , чтобы узнать, как создать пользовательское устройство без отправки на него данных.

Вы можете отправлять данные на пользовательское устройство задним числом — конечная точка пользовательского устройства поддерживает отчеты о данных до одного часа назад. Однако для обеспечения надлежащего функционирования анализа первопричин ИИ и оповещения на основе метрик мы рекомендуем отправлять данные в режиме реального времени.

Для этого варианта использования требуется элемент серии тела запроса .

Запрос потребляет и создает application/jsonполезную нагрузку.

POST Managed https://{your-domain}/e/{your-environment-id}/api/v1/entity/infrastructure/custom/{customDeviceId}
Cреда АктивногоШлюза https://{your-activegate-domain}/e/{your-environment-id}/api/v1/entity/infrastructure/custom/{customDeviceId}

Аутентификация

Чтобы выполнить этот запрос, вам нужен токен доступа с проблемой доступа и каналом событий, метриками и областью топологии ( DataExport) . Чтобы узнать, как его получить и использовать, см. раздел Токены и аутентификация .

Параметры

Параметр Тип Описание In Необходимость
customDeviceId string Идентификатор пользовательского устройства.

Если вы используете идентификатор существующего устройства, соответствующие параметры будут обновлены.

Не используйте здесь идентификатор объекта Ключ-АСТРОМ.

path требуется
body CustomDevicePushMessage Тело JSON запроса. Содержит параметры пользовательского устройства. body по желанию

Объекты тела запроса

Объект CustomDevicePushMessage

Конфигурация пользовательского устройства.

Элемент Тип Описание Необходимость
displayName string Имя пользовательского устройства, которое будет отображаться в пользовательском интерфейсе. по желанию
group string Определяемый пользователем идентификатор группы объекта.

Идентификатор группы помогает сохранить непротиворечивую картину отношений между группами устройств. Одним из многих случаев, когда важна правильная группа, является обнаружение службы: вы можете определить, какие пользовательские устройства должны вести к одной и той же службе, определив для них одинаковый идентификатор группы.

Если вы установите идентификатор группы, он будет хэширован в идентификатор объекта Ключ-АСТРОМ пользовательского устройства. В этом случае пользовательское устройство может быть частью только одной пользовательской группы устройств.

Если вы не укажете идентификатор группы, Ключ-АСТРОМ создаст ее на основе идентификатора или типа пользовательского устройства. Кроме того, группа не будет хеширована в идентификатор устройства, что означает, что устройство может переключаться между группами.

по желанию
ipAddresses string [] Список IP-адресов, принадлежащих пользовательскому устройству.

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

Если вы отправите значение (включая пустое значение), существующие значения будут перезаписаны.

Если вы отправите nullили опустите это поле, существующие значения будут сохранены.

по желанию
listenPorts integer [] Список портов, которые прослушиваются пользовательскими устройствами.

Эти порты используются для обнаружения горизонтальных коммуникационных отношений между этим компонентом и всеми другими наблюдаемыми компонентами в Smartscape.

Как только соединение обнаружено, оно автоматически отображается и отображается в Smartscape.

Если порты указаны, вы также должны добавить по крайней мере один IP-адрес или имя хоста для пользовательского устройства.

Если вы отправите значение, существующие значения будут перезаписаны.

Если вы отправите null, или пустое значение, или опустите это поле, существующие значения будут сохранены.

по желанию
type string Определение типа технологии пользовательского устройства.

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

Если вы отправите значение, существующее значение будет перезаписано.

Если вы отправите null, очистите или опустите это поле, существующее значение будет сохранено.

по желанию
favicon string Значок, который будет отображаться для вашего пользовательского компонента в Smartscape. Укажите полный URL-адрес файла значка. по желанию
configUrl string URL-адрес веб-страницы конфигурации пользовательского устройства, например страницы входа в брандмауэр или маршрутизатор. по желанию
properties object Список свойств пары "ключ-значение", которые будут отображаться под инфографикой вашего пользовательского устройства. по желанию
tags string [] Список пользовательских тегов, которые вы хотите прикрепить к своему пользовательскому устройству. по желанию
series EntityTimeseriesData[] Список значений метрик, о которых сообщается для пользовательского устройства.

Метрика, о которой вы сообщаете, уже должна существовать в Ключ-АСТРОМ. Чтобы узнать, как создать пользовательскую метрику, см. статью Timeseries API v1 — ВСТАВКА пользовательской метрики .

Ключ-АСТРОМ объединяет все значения, которые вы сообщаете для пользовательского устройства.

Если вы отправите значение (включая пустое значение), оно будет добавлено к набору существующих значений.

Если вы отправите nullили опустите это поле, набор существующих значений не изменится.

по желанию
hostNames string [] Список имен хостов, связанных с пользовательским устройством.

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

Если вы отправите значение, существующие значения будут перезаписаны.

Если вы отправляете nullили пустое значение; или опустите это поле, существующие значения будут сохранены.

по желанию

Объект EntityTimeseriesData

Информация о метрике и ее точках данных.

Элемент Тип Описание Необходимость
timeseriesId string Идентификатор метрики, в которую вы хотите опубликовать точки данных. требуется
dimensions object Размеры точек данных, которые вы публикуете.

Ключ измерения метрики должен быть определен ранее в определении метрики.

по желанию
dataPoints array[] Список точек данных.

Каждая точка данных представляет собой массив, содержащий метку времени и значение.

Отметка времени — это миллисекунды UTC, представленные в виде числа, например: 1520523365557.

У вас есть гарантированный таймфрейм на 30 минут в прошлое.

Пользовательская метрика должна быть зарегистрирована , прежде чем вы сможете сообщить о значении метрики. Поэтому отметка времени для сообщения о значении должна быть после времени регистрации метрики.

требуется

JSON-модель тела запроса

Это модель тела запроса, показывающая возможные элементы. Его необходимо настроить для использования в реальном запросе. 

{
  "displayName": "coffeeMachine",
  "group": "myCustomDeviceGroup",
  "ipAddresses": [
    "10.0.0.1"
  ],
  "listenPorts": [
    80
  ],
  "favicon": "https://www.freefavicon.com/freefavicons/food/cup-of-coffee-152-78475.png",
  "configUrl": "http://coffee-machine.ruscomtech.internal.com/coffeemachine/manage",
  "type": "coffee machine",
  "properties": {},
  "tags": [
    "office-linz"
  ],
  "series": [
    {
      "timeseriesId": "custom:created.coffee.metric",
      "dimensions": {
        "office": "Linz"
      },
      "dataPoints": [
        [
          1521542929000,
          13
        ]
      ]
    }
  ],
  "hostNames": [
    "coffee-machine.ruscomtech.internal.com"
  ]
}

Ответ

Коды ответов

Код Тип Описание
200 CustomDevicePushResult Успех. Пользовательское устройство создано или обновлено.
400 ErrorEnvelope Не удалось. Ввод недействителен.

Объекты тела ответа

Объект _ CustomDevicePushResult

Результат пользовательского push-запроса устройства. Идентификатор объекта рассчитывается автоматически.

Элемент Тип Описание
entityId string Идентификатор объекта Ключ-АСТРОМ пользовательского устройства.
groupId string Идентификатор объекта Ключ-АСТРОМ пользовательской группы устройств.

JSON-модель тела ответа

{
  "entityId": "string",
  "groupId": "string"
}

Пример

В этом примере запрос сообщает две точки данных custom:firewall.connections.droppedдля idOfmyCustomDeviceустройства. Точки данных (со значением 460временной 1539860400000метки и значением 456временной 1539860460000метки) принадлежат ethernetcard1значению nicизмерения.

Запрос также сообщает еще две точки данных той же метрики, но ethernetcard2в том же измерении, и обновляет метаданные устройства, добавляя свойство и тег.

Маркер API передается в заголовке авторизации .

Запрос возвращает идентификаторы пользовательского устройства (см. entityId) и его группы (см. groupId) в качестве подтверждения.

Вы можете скачать или скопировать образец тела запроса, чтобы попробовать его самостоятельно.

Curl

curl -X POST \
  https://mySampleEnv.live.ruscomtech.ru/api/v1/entity/infrastructure/custom/idOfmyCustomDevice \
  -H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
  -H 'Content-Type: application/json' \
  -d '{
  "tags": [
    "tag2"
  ],
  "type": "F5-Firewall",
  "properties" : {
    "Sample Property 2": "Sample value 2"
  },
  "series" : [
    {
      "timeseriesId" : "custom:firewall.connections.dropped",
      "dimensions" : {
        "nic" : "ethernetcard1"
      },
      "dataPoints" : [
        [ 1539860400000, 460 ],
        [ 1539860460000, 456 ]
       ]
    },
    {
      "timeseriesId" : "custom:firewall.connections.dropped",
      "dimensions" : {
        "nic" : "ethernetcard2"
      },
      "dataPoints" : [
        [ 1539860430000, 439 ],
        [ 1539860490000, 460 ]
       ]
    }
  ]
}'

URL-адрес запроса

https://mySampleEnv.live.ruscomtech.ru/api/v1/entity/infrastructure/custom/idOfmyCustomDevice

Тело запроса

{
  "tags": ["tag2"],
  "type": "F5-Firewall",
  "properties": {
    "Sample Property 2": "Sample value 2"
  },
  "series": [
    {
      "timeseriesId": "custom:firewall.connections.dropped",
      "dimensions": {
        "nic": "ethernetcard1"
      },
      "dataPoints": [
        [1539860400000, 460],
        [1539860460000, 456]
      ]
    },
    {
      "timeseriesId": "custom:firewall.connections.dropped",
      "dimensions": {
        "nic": "ethernetcard2"
      },
      "dataPoints": [
        [1539860430000, 439],
        [1539860490000, 460]
      ]
    }
  ]
}

Тело ответа

{
  "entityId": "CUSTOM_DEVICE-6A567B33AADC306E",
  "groupId": "CUSTOM_DEVICE_GROUP-FC2E2ABF54F513D8"
}

Код ответа

200

Результат

Custom-devices2.png

Источник — https://doc.ruscomtech.ru/index.php?title=Отчёт_о_метрике_пользовательского_устройства&oldid=1730