tags.php¶

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

Методы API¶

Метод	Действие	Описание
`add`	добавление тега	Добавляет новый тег или обновляет существующий для сервера или списка серверов. Поддерживает массовое добавление через id_list.
`clear`	очистка тегов	Очищает теги компонента. Клиенты очищают только не-essential теги, администраторы могут очистить всё (кроме preset).
`list`	получение списка тегов	Возвращает список всех тегов, назначенных серверу или компоненту.
`remove`	удаление тега	Удаляет конкретный тег с сервера. Поддерживает массовое удаление через id_list.
`search`	поиск по тегам	Ищет компоненты, соответствующие заданному тегу и значению.
`search_user`	поиск по пользователю	Ищет оборудование пользователя, имеющее теги с заданным значением.
`show`	показать теги	Метод не реализован (пустой)

tags/add¶

Добавляет новый тег или обновляет существующий для сервера или списка серверов. Поддерживает массовое добавление через id_list.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `add`
token	✅	string	Токен авторизации
id	❌	integer	Идентификатор компонента (сервера)
tag	✅	string	Название тега. Допустимые значения: hostname, server_contacts, preset, billing_cycle_changed, sla_level, ip_announce_limit, admin_lock.
value	✅	string	Значение тега
extra	❌	string	Дополнительная информация к тегу
id_list	❌	`array<integer>`	Список ID серверов для массового добавления тегов через запятую
no_log	❌	boolean	Флаг отключения записи события в системный журнал.

Пример запроса

curl -s "https://invapi.hostkey.ru/tags.php" -X POST \
--data "action=add" \
--data "token=HOSTKEY_TOKEN" \
--data "tag=hostname" \
--data "value=my-server.com"

Пример успешного ответа

{
"result": "OK",
"action": "add",
"id": 123,
"component": "eq",
"component_id": 45,
"tag": "hostname",
"value": "my-server.com",
"extra": "",
"internal": 0
}

Примеры ошибок

{
"code": -1,
"message": "DuplicateTagNameException: tag already exists"
}

tags/clear¶

Очищает теги компонента. Клиенты очищают только не-essential теги, администраторы могут очистить всё (кроме preset).

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `clear`
token	✅	string	Токен авторизации
id	✅	integer	Идентификатор сервера или компонента для очистки тегов
component	❌	string	Тип компонента (например, eq)
tag	❌	string	Дополнительный параметр: если значение 'all', то исключения не применяются

Пример запроса

curl -s "https://invapi.hostkey.ru/tags.php" -X POST \
--data "action=clear" \
--data "token=HOSTKEY_TOKEN" \
--data "id=45" \
--data "component=eq" \
--data "tag=all"

Пример успешного ответа

{
"result": "OK",
"action": "clear",
"id": 45,
"component": "eq",
"tags": [
{
"id": 10,
"tag": "example_tag"
}
]
}

Примеры ошибок

{
"code": -1,
"message": "$module/$action: invalid server id"
}

tags/list¶

Возвращает список всех тегов, назначенных серверу или компоненту.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `list`
token	✅	string	Токен авторизации
component	❌	string	Тип компонента (название таблицы или алиас)
id	❌	integer	Идентификатор сервера или компонента. Если 0 — возвращает все возможные теги/значения для данного компонента.

Пример запроса

curl -s "https://invapi.hostkey.ru/tags.php" -X POST \
--data "action=list" \
--data "token=HOSTKEY_TOKEN"

Пример успешного ответа

{
"result": "OK",
"action": "list",
"tags": [
{
"id": 1,
"tag": "hostname",
"value": "srv-01.net"
},
{
"id": 2,
"tag": "os_type",
"value": "ubuntu"
}
]
}

Примеры ошибок

{
"code": -1,
"message": "invalid server id"
}

tags/remove¶

Удаляет конкретный тег с сервера. Поддерживает массовое удаление через id_list.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `remove`
token	✅	string	Токен авторизации
tag	❌	string	Название тега для удаления.
component	❌	string	Компонент системы, к которому относится тег.
internal	❌	integer	Флаг внутреннего использования тега.
id_list	❌	string	Список идентификаторов через запятую для массового удаления тегов.

Пример запроса

curl -s "https://invapi.hostkey.ru/tags.php" -X POST \
--data "action=remove" \
--data "token=YOUR_TOKEN" \
--data "tag=old_tag"

Пример успешного ответа

{
"result": "OK",
"action": "remove",
"id": 105,
"tag": "old_tag",
"component": "eq",
"component_id": 45
}

Примеры ошибок

{
"code": -1,
"message": "tag old_tag not found for element 45 on eq"
}

tags/search¶

Ищет компоненты, соответствующие заданному тегу и значению.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `search`
token	✅	string	Токен авторизации
tag	✅	string	Название тега для поиска
value	✅	string\|array	Значение тега. Может быть строкой (поддерживает % для LIKE) или массивом [min, max] для поиска диапазона чисел.
internal	❌	integer	Флаг для фильтрации тегов по внутренним или внешним компонентам.

Пример запроса

curl -s "https://invapi.hostkey.ru/tags.php" -X POST \
--data "action=search" \
--data "token=HOSTKEY_TOKEN" \
--data "tag=os" \
--data "value=debian"

Пример успешного ответа

{
"result": "OK",
"action": "search",
"tags": [
{
"id": 1,
"tag": "os",
"value": "debian",
"component_id": 45
}
]
}

Примеры ошибок

{
"code": -2,
"message": "Invalid hash"
}

tags/search_user¶

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

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `search_user`
token	✅	string	Токен авторизации
value	✅	string	Значение тега для поиска по оборудованию пользователя

Пример запроса

curl -s "https://invapi.hostkey.ru/tags.php" -X POST \
--data "action=search_user" \
--data "token=HOSTKEY_TOKEN" \
--data "value=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "search_user",
"servers": [
{
"id": 10,
"name": "server-name"
},
{
"id": 11,
"name": "server-name-2"
}
]
}

Примеры ошибок

{
"code": -1,
"message": "Nothing found for value"
}

tags/show¶

Метод не реализован (пустой)

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `show`
token	✅	string	Токен авторизации

Пример запроса

curl -s "https://invapi.hostkey.ru/tags.php" -X POST \
--data "action=show" \
--data "token=HOSTKEY_TOKEN"

Пример успешного ответа

{
"result": "OK",
"action": "show",
"data": {}
}

Примеры ошибок

{
"code": -1,
"message": "Not implemented"
}