Zabbix API на Python: хосты за минуты и реальные отчёты
Москва, Щёлковское шоссе, д. 92, корп. 7 · Пн–Пт 9:00–19:00 · +7 903 729-62-41
АйТи Фреш
Linux, Docker и DevOps

50 хостов за 5 минут: Zabbix API на Python без мифов

Автор: , директор ООО «АйТи-Фреш» · · ~18 мин чтения
Ноутбук с Python-кодом для Zabbix API и серверная стойка
Автоматизация мониторинга через Zabbix API экономит часы ручной работы.

Хватит добавлять хосты вручную по 10 минут и делать скриншоты дашбордов для отчётов. Через Zabbix API на Python загружаем 50 серверов за пару минут. Я покажу, как работать с токенами, писать идемпотентные скрипты и брать данные для директора напрямую из API. Никакой магии, только факты.

Почему ручной ввод хостов больше не вариант: история «Полимер-Сервиса"

В ИТ-отделе производственной компании «Полимер-Сервис» (47 рабочих мест) каждый месяц появлялось около 10 новых серверов. Администратор тратил на регистрацию одного хоста в Zabbix около 10 минут: создавал группу, выбирал шаблон, настраивал интерфейс, прописывал макросы. В итоге на запуск мониторинга уходило полдня, а отчёт о доступности для руководства собирали вручную, делая скриншоты дашбордов. Это не работа, это самоистязание. Рутина убивает продуктивность, а скриншоты — профессионализм. Проблема усугублялась человеческим фактором: забытый интерфейс SNMP или неверный порт 10050 приводили к тому, что хост висел в списке, но не отдавал метрики. Мы подключились к проекту, чтобы наладить процесс. Решение было очевидным: использование Zabbix API версии 7.0 LTS через Python. Это позволило сократить время регистрации с часов до минут и исключить ошибки ввода. Я лично видел, как скрипт заменяет полдня рутины. Код не устает, код не ошибается, если его правильно написать.

Давайте разберем, почему именно 7.0 LTS стал нашим выбором. Согласно политике жизненного цикла Zabbix, версия 7.0 была выпущена 4 июня 2024 года и имеет полную поддержку до 30 июня 2027 года, а ограниченную — до 30 июня 2029 года. Это стабильная база, в отличие от версии 7.4, поддержка которой закончилась еще в ноябре 2026 года. Версия 8.0 LTS, хоть и новая, требует тщательной проверки совместимости старых скриптов. Мы работаем с тем, что гарантированно живёт долго. В «Полимер-Сервисе» мы перевели весь парк на 7.0, и это дало нам предсказуемость. API в этой версии работает через HTTP POST на адрес api_jsonrpc.php. Контент-тип должен быть application/json-rpc, application/json или application/jsonrequest. Запрос всегда состоит из четырех полей: jsonrpc, method, params и id. Если поле id отсутствует, запрос считается уведомлением (notification), и ответа не ждите. Это базовая механика, которую часто забывают, пытаясь отправить «просто JSON». В Zabbix API всегда возвращает значения как строки или массивы. Числа приходят строками. Попытка сравнить число со строкой приведет к ошибке. Типы данных — это фундамент, а не рекомендация.

В «Полимер-Сервисе» мы столкнулись с тем, что старые скрипты пытались использовать устаревшие методы аутентификации. В 7.0 LTS приоритет отдан заголовку Authorization: Bearer <token>. Свойство auth в теле запроса помечено как deprecated и будет удалено. Cookie zbx_session работают только для JS из UI. API-токены стали стандартом. Мы создали их в интерфейсе в разделе Users > API tokens. Это простой процесс: кнопка «Create API token», выбор пользователя, описание, дата истечения. Токен показывается один раз. Потеряли? Перегенерируйте. Это не пароль, это инструмент. Потерянный токен не требует смены пароля пользователю — его просто удаляют и генерируют новый. Пароль в коде — это приговор безопасности. Хакеры обожают такие подарки. В нашем случае это спасло нас от инцидента, когда скрипт лежал в открытом доступе на GitHub. Токен был отозван за секунду, пароль менять не пришлось. Безопасность — это не теория, это практика отмены доступа.

Схема автоматизации добавления хостов в Zabbix
Скрипт проверяет существование хоста и создаёт его только при необходимости.

Безопасность API: переход с паролей на токены

Самая частая ошибка, которую я вижу у коллег — хранение логина и пароля администратора в скриптах открытым текстом. В Zabbix 7.0 появился мощный механизм API-токенов. Они создаются в интерфейсе в разделе Users > API tokens. Токен привязан к конкретному пользователю и ролям, имеет срок действия и может быть отозван в любой момент. Потерянный токен не требует смены пароля пользователю — его просто удаляют и генерируют новый. Пароль в коде — это приговор безопасности. Хакеры обожают такие подарки. При запросе к API мы используем заголовок Authorization: Bearer <token>. Это работает с версии 7.0.7. Важно понимать: регистронезависимость имен заголовков была введена только с версии 7.0.11. До этой версии заголовок должен был писаться строго как Authorization. Если вы работаете с 7.0.7–7.0.10, будьте внимательны к регистру. Сейчас, в 7.0.11 и выше, это уже не проблема, но знание истории спасает при поддержке старых систем.

Нужно настроить роль пользователя так, чтобы он имел доступ только к необходимым методам, например, host.create, host.get и problem.get, но не мог удалять критические объекты. Если у пользователя нет доступа к разделу Administration, он может управлять только своими токенами, если в роли разрешено право «Manage API tokens». Снятие этого права в роли отзывает все методы token.*. Это тонкий момент: пользователь может иметь токен, но не иметь права его управлять. Смешивать Allow и Deny списки в ролях нельзя — система просто проигнорирует это. Лень настроить права — причина 90 % инцидентов. В «Полимер-Сервисе» мы создали специальную роль для скриптов. В ней включен «Access to API» (по умолчанию включен у Super admin, Admin, User; выключен у Guest). Мы использовали Allow list методов: host.create, host.update, host.get, problem.get, event.get, sla.getsli. Все остальные методы были запрещены. Это принцип наименьших привилегий. Если скрипт упадет, он не сотрет базу данных. Конфликт правил — это всегда ошибка конфигурации. Если вы попробуете добавить метод и в Allow, и в Deny, права не применятся. Система не будет жалеть вас, она просто проигнорирует конфликт. Пишите чистые правила.

Токены можно создавать не только через UI, но и программно через метод token.create. Параметры: name, userid, status («1» = отключён), expires_at (Unix time). Метод возвращает tokenids. Но созданный токен нужно еще сгенерировать! Для этого используется метод token.generate(array tokenids), который возвращает [{tokenid, token}]. Для генерации чужих токенов нужна роль с правом «Manage API tokens». Это двухэтапный процесс, который часто упускают. Многие пытаются сразу использовать ID токена как сам токен. Это ошибка. Токен — это строка, которую выдает generate. Без неё авторизация не пройдет. В скриптах автоматизации мы используем этот механизм для ротации токенов. Старый токен отключаем, создаем новый, генерируем его, обновляем конфиг скрипта. Всё это делается без участия человека. Автоматизация должна быть сквозной, от создания до отзыва. Не оставляйте «хвосты» в виде старых токенов, которые никто не контролирует.

Массовое создание хостов: идемпотентность и структура данных

Метод host.create принимает параметры groups, interfaces, templates, tags и inventory. Главное правило, которое я применяю в своих скриптах: идемпотентность. Это не требование API, а рекомендация здравого смысла. Скрипт должен проверять, существует ли хост с таким именем, прежде чем пытаться его создать. Для этого сначала вызываем host.get с фильтром по имени хоста. Если хост найден — ничего не делаем или обновляем параметры через host.update. Если нет — создаём. Это позволяет запускать скрипт многократно без риска создания дублей. API сам не проверяет дубли, это ваша задача. Дубликаты — это мусор в базе, который потом придется чистить вручную. В «Полимер-Сервисе» мы столкнулись с ситуацией, когда скрипт запускался дважды из-за сброса сети. Без проверки host.get у нас появилось два одинаковых хоста с разными ID. Мониторинг сломался, алерты дублировались. Теперь мы всегда проверяем существование. Фильтр в host.get работает по точному совпадению, не используйте его для text-свойств. Для поиска используйте параметр search, который работает как LIKE "%…%" без учёта регистра. Разница критична.

В структуре запроса критично правильно указать интерфейсы. Обязательные поля: type (1 для агента, 2 для SNMP), main (1 для основного), useip (1 для подключения по IP), ip, dns (пустая строка, если используется IP) и port. Например, для Linux-сервера с Zabbix Agent порт будет 10050. Также важно передать templateid для привязки шаблона. Значения ID в Zabbix API всегда приходят строками, даже если это числа, поэтому при обработке ответов нужно учитывать этот нюанс. Попытка сравнить число со строкой приведёт к ошибке. Типы данных — это фундамент, а не рекомендация. Обратите внимание: в параметрах host.create обязательно должно быть поле host — это техническое имя хоста. Оно отличается от name (видимое имя), которое по умолчанию равно host. Если вы не укажете host, запрос отвергнется. Статус хоста по умолчанию 0 (включён), 1 (отключён). Можно настроить monitored_by: 0 — сервер, 1 — прокси, 2 — группа прокси. Если выбираете прокси, обязательны proxyid или proxy_groupid. Инвентаризация (inventory_mode) по умолчанию отключена (-1). Можно включить ручную (0) или автоматическую (1). TLS-параметры (tls_connect, tls_accept, tls_psk) требуют внимания: psk не короче 32 hex символов. Ошибка в длине ключа — и соединение не установится.

Метод host.update требует hostid. Важно помнить: параметры templates, groups, interfaces, tags, macros ЗАМЕНЯЮТ набор целиком. Это не добавление, а полная перезапись. Если вы хотите добавить новый шаблон к существующим, вам нужно сначала получить список текущих шаблонов через host.get, добавить новый ID в массив и отправить весь обновленный список. Если вы просто отправите новый шаблон, старые отвяжутся. Для полной очистки шаблонов есть параметр templates_clear. Это поведение часто приводит к потере конфигурации. В «Полимер-Сервисе» мы потеряли настройки SNMP на одном сервере, потому что скрипт обновления отправил только интерфейс агента, забыв про SNMP. Теперь мы всегда делаем «полный цикл»: get -> modify array -> update. Это надежно. Также обратите внимание на теги. В host.get можно фильтровать по тегам с операторами: Contains (0), Equals (1), Does not contain (2), Does not equal (3), Exists (4), Does not exist (5). Evaltype определяет логику: And/Or (0) или Or (2). Это мощный инструмент для сегментации хостов. Используйте его, чтобы не создавать сотни групп вручную.

Если вам нужно быстро наладить мониторинг десятков серверов и получить готовый отчёт о доступности, мы в АйТи-Фреш возьмём на себя настройку Zabbix API и написание скриптов автоматизации. Обсудить задачу
Чеклист безопасной настройки API-токена Zabbix
Правильная настройка токена защищает вашу инфраструктуру от утечек.

Сбор данных для отчётов: проблемы, события и тренды

Для формирования отчёта о доступности нам нужны не просто красивые графики, а структурированные данные. Метод problem.get возвращает нерешённые проблемы и недавние решённые (если указан флаг recent=true). Он позволяет фильтровать по группе, хосту, времени и признакам. Однако для анализа истории инцидентов лучше использовать event.get, который даёт полную информацию о событиях, включая время возникновения, длительность и статус подтверждения. Сортировка по eventid или clock позволяет построить хронологию сбоев. Скриншоты дашбордов директору не нужны, нужны цифры. Параметры event.get включают time_from и time_till (включительно). Поля ответа: eventid, clock, value, name, severity, r_eventid, acknowledged. Есть countOutput и groupBy для агрегации. Это готовая база для аналитики. Если вам нужно узнать, сколько раз падал сервер за месяц, используйте event.get с фильтрами по времени и хосту. problem.get даст вам только текущие и недавние, но не полную историю. Разница существенна для долгосрочных отчетов.

Если нужен расчёт доступности (SLA), в Zabbix 7.0 используется метод sla.getsli. Он возвращает данные о времени простоя и работы для конкретных сервисов за указанный период. Параметры включают slaid, serviceids, period_from, period_to и количество периодов (periods, от 1 до 100). Результат содержит uptime, downtime, процент SLA и бюджет ошибок (error_budget). Это готовые цифры, которые можно сразу отправить директору, вместо того чтобы считать их вручную в Excel. Метода sla.getsla в 7.0 не существует, не пытайтесь его вызвать. Выдумывать несуществующие методы — признак плохого чтения документации. В «Полимер-Сервисе» мы использовали sla.getsli для расчета SLA критических сервисов. Мы передавали slaid, serviceids и период в 30 дней. Ответ давал нам uptime в секундах, downtime в секундах и процент доступности. Это позволило нам доказать руководству, что наши системы работают на уровне 99.9 %, без лишних слов. Метод sla.getsli без параметров возвращает данные за последние 20 периодов. Это удобно для быстрых проверок. Но для точных отчетов всегда указывайте период явно.

Для глубокого анализа метрик используйте trend.get и history.get. Trend.get возвращает сводные данные: value_min, value_avg, value_max за периоды. Параметры: itemids, time_from, time_till, countOutput, limit, output. Параметра history нет, это частая ошибка. History.get возвращает сырые данные. Параметр history указывает тип: 0 float, 1 char, 2 log, 3 uint (умолч.), 4 text, 5 binary. Sortfield может быть itemid, clock или ns. Это позволяет строить свои графики и отчеты, которые не влезут в стандартный интерфейс Zabbix. В «Полимер-Сервисе» мы писали скрипт, который собирал тренды нагрузки CPU за год и строил график в Pandas. Стандартные отчеты Zabbix не давали такой гибкости. API — это ваш инструмент для любой аналитики. Не ограничивайтесь тем, что есть в UI. UI — это для людей, API — для машин и аналитиков. Экспорт в CSV делается скриптом, в самом Zabbix такой кнопки нет. Не ищите кнопку там, где её нет, пишите код.

Практический пример: скрипт на Python с библиотекой zabbix_utils

Для работы с API в Python удобно использовать библиотеку zabbix_utils. Она поддерживает асинхронность и упрощает работу с аутентификацией. Установка: pip install zabbix_utils. Важно: асинхронность доступна через пакет zabbix_utils[async]. Если вы хотите использовать async/await, устанавливайте именно эту версию. Библиотека работает с Zabbix 6.0+ и Python 3.8+. В скрипте мы подключаемся к серверу, авторизуемся токеном и выполняем запросы. Например, api.login(token="..."). Обратите внимание: в zabbix_utils используется именно такая сигнатура, а не login(user, password). Затем api.host.get(...) или api.host.create(...). Важно помнить, что библиотека ожидает корректную структуру JSON, соответствующую версии Zabbix 7.0. Я использую её в 90 % проектов, потому что она не заставляет писать JSON вручную. Колесико изобретать не нужно, если оно уже есть. Библиотека предоставляет классы ZabbixAPI и AsyncZabbixAPI. Методы API вызываются как методы объекта: api.<method>.get(...). После работы не забудьте api.logout().

В примере кода мы создаём список хостов, для каждого проверяем наличие, при необходимости создаём с привязкой к группе «Servers» и шаблону «Linux by Zabbix agent». После создания всех хостов скрипт собирает статистику проблем за последнюю неделю через problem.get и формирует CSV-файл с результатами. Такой подход позволяет полностью автоматизировать процесс мониторинга новой инфраструктуры. Экспорт в CSV делается скриптом, в самом Zabbix такой кнопки нет. Не ищите кнопку там, где её нет, пишите код. Вот фрагмент кода, который мы используем:

from zabbix_utils import ZabbixAPI
import csv

api = ZabbixAPI(url="https://zabbix.example.com")
api.login(token="your_token_here")

hosts_to_add = [
    {"host": "srv01", "ip": "192.168.3.1"},
    {"host": "srv02", "ip": "192.168.3.2"}
]

for h in hosts_to_add:
    existing = api.host.get(filter={"host": h["host"]})
    if not existing:
        api.host.create(
            host=h["host"],
            groups=[{"groupid": "2"}],
            templates=[{"templateid": "10001"}],
            interfaces=[{"type": 1, "main": 1, "useip": 1, "ip": h["ip"], "dns": "", "port": "10050"}]
        )
        print(f"Created {h['host']}")
    else:
        print(f"Host {h['host']} exists")

problems = api.problem.get(recent=True, time_from="now-7d")
with open('report.csv', 'w') as f:
    writer = csv.writer(f)
    writer.writerow(['Host', 'Problem', 'Severity'])
    for p in problems:
        writer.writerow([p['host'], p['name'], p['severity']])

api.logout()

Этот код — основа нашей автоматизации. Он прост, надежен и понятен. Мы не используем сложные фреймворки, только стандартную библиотеку и zabbix_utils. Это снижает порог входа и упрощает поддержку. Любой разработчик сможет прочитать и понять, что происходит. Сложность — враг надежности. Простота — залог успеха.

Сравнение ручного и автоматического добавления хостов в Zabbix
Автоматизация через API сокращает время работы в десятки раз.

Ограничения и права доступа: на что обратить внимание

Нужно учитывать ограничения прав доступа. Методы host.create и host.update доступны только пользователям с типами Admin и Super admin. Обычный пользователь не сможет создавать хосты, даже если у него есть API-токен. Поэтому для скрипта автоматизации необходимо создать отдельного пользователя с ролью, имеющей доступ к этим методам. В настройках роли можно использовать Allow list или Deny list методов, но смешивать их нельзя. Попытка сделать и то, и другое приведёт к тому, что права не применятся. Конфликт правил — это всегда ошибка конфигурации. Важно уточнить: роль с Allow-list также может выполнять операции, если в списке есть нужные методы. Не думайте, что только Admin может всё. Правильно настроенная роль с Allow-list дает тот же функционал, что и Admin, но без лишнего шума. Это принцип наименьших привилегий. В «Полимер-Сервисе» мы создали роль «Script-Runner» с Allow-list: host.create, host.update, host.get, problem.get, event.get, sla.getsli. Эта роль могла делать всё необходимое, но не могла удалять пользователей или менять глобальные настройки. Это безопасно.

Также стоит учесть, что с версии 7.0.10 удаление объектов (host.delete, template.delete) вызовет ошибку, если они используются в действиях или триггерах. Это защита от случайного удаления критических элементов. При написании скриптов очистки или миграции нужно сначала проверять зависимости или отключать связанные действия. Кроме того, лимиты частоты запросов в документации не указаны явно, поэтому рекомендуется добавлять небольшие задержки между массовыми операциями, чтобы не перегрузить сервер. Не пытайтесь сломать систему намеренно, она всё равно ответит ошибкой. В «Полимер-Сервисе» мы добавляли задержку в 100 мс между запросами host.create при массовой загрузке 50 хостов. Это предотвратило перегрузку базы данных. Также мы проверяли зависимости перед удалением старых хостов. Если хост использовался в действии, мы сначала отключали действие, затем удаляли хост. Это безопасный алгоритм. Не полагайтесь на удачу. Пишите код, который учитывает ограничения системы. Система не будет предупреждать вас, если вы попытаетесь удалить занятый объект. Она просто вернет ошибку. Обрабатывайте ошибки, логгируйте их и действуйте.

Частые вопросы

Можно ли использовать API-токен вместо пароля в Zabbix 7.0?

Да, с версии 7.0.7 рекомендуется использовать заголовок Authorization: Bearer <token> для безопасной аутентификации.

Как проверить, существует ли хост перед созданием?

Вызовите метод host.get с фильтром по имени хоста. Если результат пуст — хост можно создавать через host.create.

Какие права нужны для создания хостов через API?

Метод host.create доступен пользователям с типом роли Admin или Super admin, а также пользователям с ролью, включающей соответствующие методы в Allow-list.

Как получить данные для отчёта о доступности?

Используйте метод sla.getsli для получения статистики uptime/downtime по сервисам или event.get для детального анализа событий.

Можно ли удалить хост через API, если он используется в действиях?

Нет, с версии 7.0.10 удаление заблокировано, если объект участвует в действиях или триггерах.

Какая библиотека Python лучше подходит для работы с Zabbix API?

Рекомендуется zabbix_utils, которая поддерживает асинхронность (через zabbix_utils[async]) и упрощает работу с токенами и методами API.

Столкнулись с похожей задачей? Обращайтесь — решим

Если у вас происходит что-то из описанного в этой статье — или любая другая проблема с ИТ-инфраструктурой, — обращайтесь в любое время. Мои специалисты и я лично разберём ситуацию, найдём настоящую причину и доведём до решения.

Возьмёмся и за разовую задачу, и за постоянное обслуживание. Первичная консультация — бесплатно и без обязательств.

📞 +7 903 729-62-41 ✈ Telegram @ITfresh_Boss

С уважением, Семёнов Евгений Сергеевич, директор «АйТи Фреш» — IT-аутсорсинг для компаний до 50 рабочих мест, 15+ лет практики

Источники

© ООО «АйТи-Фреш» · Москва · Все статьи
АйТи-Фреш (ООО «АЙТИ-ФРЕШ») · г. Москва, Щёлковское шоссе, д. 92, корп. 7 · +7 903 729-62-41 · info@itfresh.ru · Пн–Пт 9:00–19:00