Создание пользовательского устройства: различия между версиями
ENetrebin (обсуждение | вклад) Метки: визуальный редактор ручная отмена |
ENetrebin (обсуждение | вклад) |
||
| Строка 323: | Строка 323: | ||
==== Результат ==== | ==== Результат ==== | ||
<nowiki>[[Custom-device-smartscape-1103-ba9b69e490.png]]</nowiki> | |||
[[Файл:Custom-device-658-bb2295e42c.png]] | [[Файл:Custom-device-658-bb2295e42c.png]] | ||
Версия 13:34, 13 октября 2022
Конечная точка пользовательского устройства API топологии и Smartscape позволяет создать пользовательское устройство с указанным именем в вашей среде Ключ-АСТРОМ.
На этой странице описывается, как создать пользовательское устройство без отправки на него каких-либо данных.
Чтобы узнать, как передавать данные на пользовательское устройство, см. статью Отчет о метрике пользовательского устройства через REST API .
Запрос потребляет и создает application/jsonполезную нагрузку.
| POST | Managed | https://{your-domain}/e/{your-environment-id}/api/v1/entity/infrastructure/custom/{customDeviceId}
|
| Среда АктивногоШлюза | 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. Если вы отправите значение (включая пустое значение), существующие значения будут перезаписаны. Если вы отправите |
по желанию |
| listenPorts | integer [] | Список портов, которые прослушиваются пользовательскими устройствами.
Эти порты используются для обнаружения горизонтальных коммуникационных отношений между этим компонентом и всеми другими наблюдаемыми компонентами в Smartscape. Как только соединение обнаружено, оно автоматически отображается и отображается в Smartscape. Если порты указаны, вы также должны добавить по крайней мере один IP-адрес или имя хоста для пользовательского устройства. Если вы отправите значение, существующие значения будут перезаписаны. Если вы отправите |
по желанию |
| type | string | Определение типа технологии пользовательского устройства.
Это должен быть тот же тип технологии, что и показатель, о котором вы сообщаете. Если вы отправите значение, существующее значение будет перезаписано. Если вы отправите |
по желанию |
| favicon | string | Значок, который будет отображаться для вашего пользовательского компонента в Smartscape. Укажите полный URL-адрес файла значка. | по желанию |
| configUrl | string | URL-адрес веб-страницы конфигурации пользовательского устройства, например страницы входа в брандмауэр или маршрутизатор. | по желанию |
| properties | object | Список свойств пары "ключ-значение", которые будут отображаться под инфографикой вашего пользовательского устройства. | по желанию |
| tags | string [] | Список пользовательских тегов, которые вы хотите прикрепить к своему пользовательскому устройству. | по желанию |
| series | EntityTimeseriesData[] | Список значений метрик, о которых сообщается для пользовательского устройства.
Метрика, о которой вы сообщаете, уже должна существовать в Ключ-АСТРОМ. Чтобы узнать, как создать пользовательскую метрику, см. статью Timeseries API v1 — ВСТАВКА пользовательской метрики . Ключ-АСТРОМ объединяет все значения, которые вы сообщаете для пользовательского устройства. Если вы отправите значение (включая пустое значение), оно будет добавлено к набору существующих значений. Если вы отправите |
по желанию |
| hostNames | string [] | Список имен хостов, связанных с пользовательским устройством.
Эти имена используются для автоматического обнаружения горизонтальных коммуникационных отношений между этим компонентом и всеми другими наблюдаемыми компонентами в Smartscape. Как только соединение обнаружено, оно автоматически отображается и отображается в Smartscape. Если вы отправите значение, существующие значения будут перезаписаны. Если вы отправляете |
по желанию |
Объект EntityTimeseriesData
Информация о метрике и ее точках данных.
| Элемент | Тип | Описание | Необходимость |
|---|---|---|---|
| timeseriesId | string | Идентификатор метрики, в которую вы хотите опубликовать точки данных. | требуется |
| dimensions | object | Размеры точек данных, которые вы публикуете.
Ключ измерения метрики должен быть определен ранее в определении метрики. |
по желанию |
| dataPoints | array[] | Список точек данных.
Каждая точка данных представляет собой массив, содержащий метку времени и значение. Отметка времени — это миллисекунды UTC, представленные в виде числа, например: У вас есть гарантированный таймфрейм на 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"
}
Пример
В этом примере запрос создает пользовательское устройство idOfmyCustomDeviceтипа F5-Firewall, с IP-адресом 172.16.115.211и портом прослушивания 9999. В запросе также указываются некоторые дополнительные параметры.
См. раздел Отчет о метрике пользовательского устройства через API Ключ-АСТРОМ, чтобы узнать, как отправлять данные на вновь созданное пользовательское устройство.
Маркер 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 '{
"displayName" : "F5 Firewall 24",
"ipAddresses" : ["172.16.115.211"],
"listenPorts" : ["9999"],
"type" : "F5-Firewall",
"favicon" : "http://assets.ruscomtech.ru/global/icons/f5.png",
"configUrl" : "http://192.128.0.1:8080",
"tags": [
"REST example"
],
"properties" : {
"Sample Property 1": "Sample value 1"
}
}'
URL-адрес запроса
https://mySampleEnv.live.ruscomtech.ru/api/v1/entity/infrastructure/custom/idOfmyCustomDevice
Тело запроса
{
"displayName": "F5 Firewall 24",
"ipAddresses": ["172.16.115.211"],
"listenPorts": ["9999"],
"type": "F5-Firewall",
"favicon": "http://assets.ruscomtech.ru/global/icons/f5.png",
"configUrl": ""http://192.128.0.1:8080",
"tags": ["REST example"],
"properties": {
"Sample Property 1": "Sample value 1"
}
}
Тело ответа
{
"entityId": "CUSTOM_DEVICE-6A567B33AADC306E",
"groupId": "CUSTOM_DEVICE_GROUP-FC2E2ABF54F513D8"
}
Код ответа
200
Результат
[[Custom-device-smartscape-1103-ba9b69e490.png]]
