ENetrebin: /* Результат */

2022-10-13T14:33:00Z

Результат

← Предыдущая		Версия 14:33, 13 октября 2022
Строка 361:		Строка 361:

	==== Результат ====		==== Результат ====
			[[Файл:custom-devices2.png]]

ENetrebin: Новая страница: «Конечная точка пользовательского устройства API топологии и Smartscape позволяет отправлять...»

2022-10-13T14:28:29Z

Новая страница: «Конечная точка пользовательского устройства API топологии и Smartscape позволяет отправлять...»

Новая страница

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

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

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

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

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

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

Запрос потребляет и создает <code>application/json</code>полезную нагрузку.
{| class="wikitable"
| rowspan="2" |POST
|Managed
|<code><nowiki>https://{your-domain}/e/{your-environment-id}/api/v1/entity/infrastructure/custom/{customDeviceId}</nowiki></code>
|-
|Cреда АктивногоШлюза
|<code><nowiki>https://{your-activegate-domain}/e/{your-environment-id}/api/v1/entity/infrastructure/custom/{customDeviceId}</nowiki></code>
|}

== Аутентификация ==
Чтобы выполнить этот запрос, вам нужен токен доступа с проблемой доступа и каналом событий, метриками и областью топологии ( <code>DataExport</code>) . Чтобы узнать, как его получить и использовать, см. раздел [[Токены и аутентификация (API)|Токены и аутентификация]] .

== Параметры ==
{| class="wikitable"
!Параметр
!Тип
!Описание
!In
!Необходимость
|-
|customDeviceId
|string
|Идентификатор пользовательского устройства.

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

Не используйте здесь идентификатор объекта Ключ-АСТРОМ.
|path
|требуется
|-
|body
|CustomDevicePushMessage
|Тело JSON запроса. Содержит параметры пользовательского устройства.
|body
|по желанию
|}

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

==== Объект <code>CustomDevicePushMessage</code> ====
Конфигурация пользовательского устройства.
{| class="wikitable"
!Элемент
!Тип
!Описание
!Необходимость
|-
|displayName
|string
|Имя пользовательского устройства, которое будет отображаться в пользовательском интерфейсе.
|по желанию
|-
|group
|string
|Определяемый пользователем идентификатор группы объекта.

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

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

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

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

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

Если вы отправите <code>null</code>или опустите это поле, существующие значения будут сохранены.
|по желанию
|-
|listenPorts
|integer []
|Список портов, которые прослушиваются пользовательскими устройствами.

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

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

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

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

Если вы отправите <code>null</code>, или пустое значение, или опустите это поле, существующие значения будут сохранены.
|по желанию
|-
|type
|string
|Определение типа технологии пользовательского устройства.

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

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

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

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

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

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

Если вы отправите <code>null</code>или опустите это поле, набор существующих значений не изменится.
|по желанию
|-
|hostNames
|string []
|Список имен хостов, связанных с пользовательским устройством.

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

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

Если вы отправляете <code>null</code>или пустое значение; или опустите это поле, существующие значения будут сохранены.
|по желанию
|}

==== Объект <code>EntityTimeseriesData</code> ====
Информация о метрике и ее точках данных.
{| class="wikitable"
!Элемент
!Тип
!Описание
!Необходимость
|-
|timeseriesId
|string
|Идентификатор метрики, в которую вы хотите опубликовать точки данных.
|требуется
|-
|dimensions
|object
|Размеры точек данных, которые вы публикуете.

Ключ измерения метрики должен быть определен ранее в определении метрики.
|по желанию
|-
|dataPoints
|array[]
|Список точек данных.

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

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

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

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

=== JSON-модель тела запроса ===
Это модель тела запроса, показывающая возможные элементы. Его необходимо настроить для использования в реальном запросе.
<code>{
"displayName": "coffeeMachine",
"group": "myCustomDeviceGroup",
"ipAddresses": [
"10.0.0.1"
],
"listenPorts": [
80
],
"favicon": "<nowiki>https://www.freefavicon.com/freefavicons/food/cup-of-coffee-152-78475.png</nowiki>",
"configUrl": "<nowiki>http://coffee-machine.ruscomtech.internal.com/coffeemachine/manage</nowiki>",
"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"
]
}</code>

== Ответ ==

=== Коды ответов ===
{| class="wikitable"
!Код
|Тип
!Описание
|-
|200
|CustomDevicePushResult
|Успех. Пользовательское устройство создано или обновлено.
|-
|400
|ErrorEnvelope
|Не удалось. Ввод недействителен.
|}

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

==== Объект _ <code>CustomDevicePushResult</code> ====
Результат пользовательского push-запроса устройства. Идентификатор объекта рассчитывается автоматически.
{| class="wikitable"
!Элемент
!Тип
!Описание
|-
|entityId
|string
|Идентификатор объекта Ключ-АСТРОМ пользовательского устройства.
|-
|groupId
|string
|Идентификатор объекта Ключ-АСТРОМ пользовательской группы устройств.
|}

=== JSON-модель тела ответа ===
<code>{
"entityId": "string",
"groupId": "string"
}</code>

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

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

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

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

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

==== Curl ====
<code>curl -X POST \
<nowiki>https://mySampleEnv.live.ruscomtech.ru/api/v1/entity/infrastructure/custom/idOfmyCustomDevice</nowiki> \
-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 ]
]
}
]
}'</code>

==== URL-адрес запроса ====
<code><nowiki>https://mySampleEnv.live.ruscomtech.ru/api/v1/entity/infrastructure/custom/idOfmyCustomDevice</nowiki></code>

==== Тело запроса ====
<code>{
"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]
]
}
]
}</code>

==== Тело ответа ====
<code>{
"entityId": "CUSTOM_DEVICE-6A567B33AADC306E",
"groupId": "CUSTOM_DEVICE_GROUP-FC2E2ABF54F513D8"
}</code>

==== Код ответа ====
200

==== Результат ====

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

ENetrebin: /* Результат */

ENetrebin: Новая страница: «Конечная точка пользовательского устройства API топологии и Smartscape позволяет отправлять...»