hardware.php¶

В этой статье

Методы API

hardware/add

hardware/add_barcodes

hardware/clone

hardware/delete_barcodes

hardware/eval_hw

hardware/history

hardware/list

hardware/list_barcodes

hardware/list_storage

hardware/merge

hardware/racks_report

hardware/remove

hardware/search

hardware/show

hardware/show_barcodes

hardware/update

hardware/update_barcodes

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

Методы API¶

Метод	Действие	Описание
`add`	добавление компонента	Создает новый аппаратный компонент в системе.
`add_barcodes`	добавление штрих-кодов	Добавляет новые записи штрих-кодов для сущностей.
`clone`	клонирование	Создает клон компонента на основе существующего ID.
`delete_barcodes`	удаление штрих-кодов	Удаляет запись штрих-кода по его ID.
`eval_hw`	переоценка компонентов	Обновляет стоимость (cost_buy) и тег ru_cost для списка аппаратных компонентов.
`history`	получение истории	Возвращает историю изменений (логи) для указанных компонентов.
`list`	список компонентов	Возвращает список доступных аппаратных компонентов с фильтрацией по типу.
`list_barcodes`	получение списка штрих-кодов	Возвращает список всех зарегистрированных штрих-кодов с применением фильтров.
`list_storage`	получение складских остатков	Возвращает список доступных компонентов на складе с учетом фильтров по типу и локации.
`merge`	объединение элементов	Объединяет несколько компонентов в один (мастер-элемент).
`racks_report`	отчет по стойкам	Генерирует отчет по стоимости и конфигурации серверов внутри стоек дата-центра.
`remove`	удаление компонента	Удаляет компонент из базы данных по его ID.
`search`	поиск серверов	Поиск серверов, содержащих компоненты с определенными характеристиками.
`show`	показ компонента	Возвращает детальную информацию о конкретном аппаратном компоненте.
`show_barcodes`	получение информации о штрих-коде	Возвращает данные штрих-кода по его идентификатору.
`update`	обновление компонента	Обновляет данные аппаратного компонента.
`update_barcodes`	обновление штрих-кода	Обновляет данные записи штрих-кода.

hardware/add¶

Создает новый аппаратный компонент в системе.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `add`
token	✅	string	Токен авторизации
name	✅	string	Название компонента
type	✅	string	Тип аппаратного компонента
cost_buy	❌	number	Себестоимость закупки.
cost_sale	❌	number	Цена продажи.
cost_saleNL	❌	number	Цена продажи в NL (Нидерланды).
cost_saleUS	❌	number	Цена продажи в US (США).
Kpd	❌	number	Коэффициент KPD.
CpuLink	❌	string	Связь процессора (CpuLink).

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

curl -s "https://invapi.hostkey.ru/hardware.php" -X POST \
--data "action=add" \
--data "token=HOSTKEY_TOKEN" \
--data "name=Intel Xeon Gold" \
--data "type=CPU" \
--data "cost_buy=100" \
--data "cost_sale=150" \
--data "Kpd=1.5" \
--data "CpuLink=UPI"

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

{
"result": "OK",
"module": "hardware",
"action": "add",
"id": 123,
"name": "Intel Xeon Gold",
"tags": []
}

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

{
"-1": "Component named '...' already exists",
"Exception: cost_buy $cost_buy should be a number": "hardware/add: cost_buy $cost_buy should be a number",
"Exception: cost_sale $cost_sale should be a number": "hardware/add: cost_sale $cost_sale should be a number",
"Exception: cost_saleNL $cost_saleNL should be a number": "hardware/add: cost_saleNL $cost_saleNL should be a number",
"Exception: cost_saleUS $cost_saleUS should be a number": "hardware/add: cost_saleUS $cost_saleUS should be a number",
"Exception: Kpd $Kpd should be a number": "hardware/add: Kpd $Kpd should be a number",
"Exception: failed to create component $name": "hardware/add: failed to create component $name"
}

hardware/add_barcodes¶

Добавляет новые записи штрих-кодов для сущностей.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `add_barcodes`
token	✅	string	Токен авторизации
hardware_id	❌	integer	null
barcode	✅	string	Значение штрих-кода
comment	❌	string	null

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

curl -s "https://invapi.hostkey.ru/hardware.php" -X POST \
--data "action=add_barcodes" \
--data "token=HOSTKEY_TOKEN" \
--data "barcode=ABC-123"

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

{
"result": "OK",
"module": "hardware",
"action": "add_barcodes",
"barcode": {
"id": 1,
"hardware_id": null,
"barcode": "ABC-123",
"comment": null,
"login": "admin@example.com",
"date_added": "2023-10-27 12:00"
}
}

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

{
"RuntimeException": {
"code": -1,
"message": "Missing required keys: barcode"
}
}

hardware/clone¶

Создает клон компонента на основе существующего ID.

HTTP-метод: POST

Параметры:

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

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

curl -s "https://invapi.hostkey.ru/hardware.php" -X POST \
--data "action=clone" \
--data "id=VALUE"

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

{
"result": "OK",
"module": "hardware",
"action": "clone",
"report": {}
}

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

{
"code": 400,
"message": "Please provide ID"
}

hardware/delete_barcodes¶

Удаляет запись штрих-кода по его ID.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `delete_barcodes`
token	✅	string	Токен авторизации
id	❌	integer	ID штрих-кода для удаления.

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

curl -s "https://invapi.hostkey.ru/hardware.php" -X POST \
--data "action=delete_barcodes" \
--data "token=HOSTKEY_TOKEN" \
--data "id=123"

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

{
"result": "OK",
"module": "hardware",
"action": "delete_barcodes",
"barcode": 123
}

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

{
"code": -1,
"message": "$module/$action: authentication required"
}

hardware/eval_hw¶

Обновляет стоимость (cost_buy) и тег ru_cost для списка аппаратных компонентов.

HTTP-метод: POST

Параметры:

action	✅	string	Идентификатор метода: `eval_hw`
token	✅	string	Токен авторизации
update_data	❌	`array<integer\|object>`	Массив данных для обновления. Ключи — ID компонентов, значения в формате 'cost_buy;ru_cost'. Если не передан, используется -1.

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

curl -s "https://invapi.hostkey.ru/hardware.php" -X POST \
--data "action=eval_hw" \
--data "token=HOSTKEY_TOKEN" \
--data "update_data[123]=500;450" \
--data "update_data[124]=1000;900"

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

{
"result": "OK",
"action": "eval_hw",
"log": [
"string (сообщение об изменении стоимости)"
]
}

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

{
"SqlQueryException": {
"code": -1,
"message": "Ошибка при выполнении SQL-запроса в функциях tags_insert или hw_update"
}
}

hardware/history¶

Возвращает историю изменений (логи) для указанных компонентов.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `history`
token	✅	string	Токен авторизации
id	❌	`array<integer>`	Идентификатор или массив идентификаторов записей для фильтрации истории.
type	❌	`array<string>`	Типы записей истории. Принимает несколько значений: type[]=val1&type[]=val2.
date_from	❌	string	Дата начала истории (ISO-дата).
location	❌	string	Фильтрация по локации.

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

curl -s "https://invapi.hostkey.ru/hardware.php" -X POST \
--data "action=history" \
--data "token=HOSTKEY_TOKEN" \
--data "id[]=123" \
--data "type[]=ALERT" \
--data "type[]=INFO"

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

{
"result": "OK",
"module": "hardware",
"action": "history",
"history": [
{
"id": 0,
"date": "2024-01-15T10:30:00Z",
"type": "ALERT",
"message": "--- End of log ---",
"login": "SYSTEM"
}
]
}

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

{
"code": -1,
"message": "Ошибка получения истории"
}

hardware/list¶

Возвращает список доступных аппаратных компонентов с фильтрацией по типу.

HTTP-метод: POST

Параметры:

action	✅	string	Идентификатор метода: `list`
token	❌	string	Токен авторизации (если не пустой, проверяется разрешение)
hw_type	❌	string	Тип оборудования. Допустимые значения: CPU, Platform, HDD, RAM, Other, motherboard.

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

curl -s "https://invapi.hostkey.ru/hardware.php" -X POST \
--data "action=list" \
--data "token=your_token_here" \
--data "hw_type=HDD"

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

{
"result": "OK",
"module": "hardware",
"action": "list",
"list": [
{
"id": 1,
"name": "Samsung SSD 870",
"type": "HDD",
"tags": [],
"in_use": [],
"location": null,
"status": null
}
]
}

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

{
"-2": {
"message": "Invalid hash",
"code": "INVALID_HASH"
},
"-1": {
"message": "Permission denied",
"code": "PERMISSION_DENIED"
}
}

hardware/list_barcodes¶

Возвращает список всех зарегистрированных штрих-кодов с применением фильтров.

HTTP-метод: POST

Параметры:

action	✅	string	Идентификатор метода: `list_barcodes`
token	✅	string	Токен авторизации
hardware_id	❌	`array<integer>`	ID оборудования для фильтрации штрих-кодов (через hw_barcodes_entity_filter)
barcode	❌	`array<string>`	Значение штрих-кода для поиска (через hw_barcodes_entity_filter)

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

curl -s "https://invapi.hostkey.ru/hardware.php" -X POST \
--data "action=list_barcodes" \
--data "token=HOSTKEY_TOKEN" \
--data "hardware_id[]=5" \
--data "barcode[]=ABC-12345"

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

{
"result": "OK",
"action": "list_barcodes",
"barcodes": [
{
"id": 1,
"hardware_id": 5,
"barcode": "ABC-12345",
"comment": "test",
"date_added": "2023-01-01"
}
]
}

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

{
"code": -1,
"message": "Empty search parameters disallowed"
}

hardware/list_storage¶

Возвращает список доступных компонентов на складе с учетом фильтров по типу и локации.

HTTP-метод: POST

Параметры:

action	✅	string	Идентификатор метода: `list_storage`
token	✅	string	Токен авторизации
class	❌	string	Тип склада. Допустимые значения: bm (по умолчанию), vm.
hw_id	❌	`array<integer>`	Уникальный идентификатор оборудования для фильтрации списка хранилищ.
type	❌	`array<string>`	Тип устройства или категории оборудования в системе.

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

curl -s "https://invapi.hostkey.ru/hardware.php" -X POST \
--data "action=list_storage" \
--data "token=HOSTKEY_TOKEN" \
--data "class=bm" \
--data "hw_id[]=5" \
--data "type[]=CPU"

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

{
"result": "OK",
"module": "hardware",
"action": "list_storage",
"components": [
{
"eq_id": 10,
"hw_id": 5,
"id": 123,
"name": "Intel Xeon E5-2680v4",
"type": "CPU",
"tags": {},
"location": "Warehouse A"
}
]
}

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

{
"code": -1,
"message": "Action is not recognized"
}

hardware/merge¶

Объединяет несколько компонентов в один (мастер-элемент).

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `merge`
token	✅	string	Токен авторизации
id	✅	integer	ID мастер-элемента (тот, в который объединяют)
group	❌	string	Строка с ID элементов через запятую для объединения

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

curl -s "https://invapi.hostkey.ru/hardware.php" -X POST \
--data "action=merge" \
--data "token=HOSTKEY_TOKEN" \
--data "id=123" \
--data "group=456,789"

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

{
"result": "OK",
"module": "hardware",
"action": "merge"
}

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

{
"code": -1,
"message": "hardware/merge: invalid group data $group"
}

hardware/racks_report¶

Генерирует отчет по стоимости и конфигурации серверов внутри стоек дата-центра.

HTTP-метод: POST

Параметры:

action	✅	string	Идентификатор метода: `racks_report`
token	✅	string	Токен авторизации
id	✅	integer	ID дата-центра для построения отчета

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

curl -s "https://invapi.hostkey.ru/hardware.php" -X POST \
--data "action=racks_report" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE"

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

{
"result": "OK",
"action": "racks_report",
"data": [
{
"id": 501,
"hwconfig": "Intel Xeon E5-2680v4, 64GB RAM, 2x1TB SSD",
"price": 1250.5,
"sale_price": 1800.0
}
]
}

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

{
"400": "Please provide ID"
}

hardware/remove¶

Удаляет компонент из базы данных по его ID.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `remove`
token	✅	string	Токен авторизации
id	❌	integer	ID удаляемого компонента (по умолчанию 0)

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

curl -s "https://invapi.hostkey.ru/hardware.php" -X POST \
--data "action=remove" \
--data "token=HOSTKEY_TOKEN" \
--data "id=123"

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

{
"result": "OK",
"module": "hardware",
"action": "remove",
"id": 123
}

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

{
"code": -1,
"message": "hardware/remove: failed to remove component [id] - it is in use."
}

hardware/search¶

Поиск серверов, содержащих компоненты с определенными характеристиками.

HTTP-метод: POST

Параметры:

action	✅	string	Идентификатор метода: `search`
token	✅	string	Токен авторизации
id	❌	integer	ID компонента для поиска (hw_id)
location	❌	string	Фильтр по локации. Допустимые значения: All или код локации из dataCenterLocation.Code
status	❌	string	Статус сервера. Можно передать список через запятую

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

curl -s "https://invapi.hostkey.ru/hardware.php" -X POST \
--data "action=search" \
--data "token=HOSTKEY_TOKEN" \
--data "id=123" \
--data "location=AMS" \
--data "status=active,pending"

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

{
"result": "OK",
"module": "hardware",
"action": "search",
"servers": [
{
"id": 10,
"type": "string",
"owner": "string",
"status": "string",
"ip": "string",
"location": "string",
"config": "string",
"full_location": "string",
"preset": "string",
"hostname": "string",
"role": "string",
"rate": "string",
"amount": 5,
"days_left": 45,
"due_date": "2024-12-31"
}
]
}

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

{
"code": -1,
"message": "Ошибка поиска серверов (hw_search возвращает -1 при отсутствии результатов)"
}

hardware/show¶

Возвращает детальную информацию о конкретном аппаратном компоненте.

HTTP-метод: POST

Параметры:

action	✅	string	Идентификатор метода: `show`
token	✅	string	Токен авторизации
id	❌	integer	ID компонента
name	❌	string	Имя компонента для поиска

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

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

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

{
"result": "OK",
"module": "hardware",
"action": "show",
"part": {
"id": 1,
"name": "Example CPU",
"tags": [],
"servers_count": 0,
"total": 0,
"status": null,
"location": null,
"in_use": []
}
}

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

{
"errors": [
{
"code": -1,
"message": "Component ID $id not found"
}
]
}

hardware/show_barcodes¶

Возвращает данные штрих-кода по его идентификатору.

HTTP-метод: POST

Параметры:

action	✅	string	Идентификатор метода: `show_barcodes`
id	❌	integer	ID записи штрих-кода.
token	❌	string	Уникальный идентификатор сессии или ключ доступа для авторизации запроса.

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

curl -s "https://invapi.hostkey.ru/hardware.php" -X POST \
--data "action=show_barcodes" \
--data "id=123" \
--data "token=your_token_here"

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

{
"result": "OK",
"module": "hardware",
"action": "show_barcodes",
"barcode": {
"id": 123,
"hardware_id": 456,
"barcode": "ABC-12345",
"comment": "some comment",
"date_added": "2023-01-01"
}
}

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

{
"code": -1,
"message": "Barcode record hwb:ID not found"
}

hardware/update¶

Обновляет данные аппаратного компонента.

HTTP-метод: POST

Параметры:

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

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

curl -s "https://invapi.hostkey.ru/hardware.php" -X POST \
--data "action=update" \
--data "id=123" \
--data "token=your_session_token"

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

{
"result": "OK",
"module": "hardware",
"action": "update",
"data": {
"id": 123,
"type": "string|null",
"name": "string|null",
"cost_buy": 100,
"cost_sale": 200,
"cost_saleNL": 150,
"cost_saleUS": 180,
"Kpd": 10,
"CpuLink": "string|null",
"servers_count": 5,
"total": 1000,
"status": "string|null",
"location": "string|null",
"tags": []
}
}

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

{
"RuntimeException": [
{
"code": -1,
"message": "Unable to update imaginary component"
},
{
"code": -1,
"message": "Unable to update nonexistent component"
}
],
"Exception": [
{
"code": null,
"message": "hardware/update: failed to update component {name}"
}
]
}

hardware/update_barcodes¶

Обновляет данные записи штрих-кода.

HTTP-метод: POST

Параметры:

action	✅	string	Идентификатор метода: `update_barcodes`
id	❌	integer	ID записи штрих-кода.
token	❌	string	Уникальный идентификатор сессии для авторизации запроса.
barcode	✅	string	Штрих-код (обязателен согласно hw_barcodes_validate)

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

curl -s "https://invapi.hostkey.ru/hardware.php" -X POST \
--data "action=update_barcodes" \
--data "id=123" \
--data "token=your_session_token" \
--data "barcode=ABC-12345"

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

{
"result": "OK",
"module": "hardware",
"action": "update_barcodes",
"barcode": {}
}

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

{
"errors": [
{
"code": -1,
"message": "Missing required keys: barcode"
}
]
}