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

Создания новых приложений для работы с Zabbix.
Интеграции Zabbix со сторонним программным обеспечением.
Автоматизации рутинных задач.

API Zabbix — это API на основе HTTP, и оно поставляется как часть веб-интерфейса. Оно использует протокол JSON-RPC 2.0, что означает две вещи:

API состоит из набора отдельных методов.
Запросы и ответы между клиентами и API кодируются с использованием формата JSON.

Дополнительные сведения о протоколе и JSON см. в спецификации JSON-RPC 2.0 и на главной странице формата JSON.

Дополнительные сведения об интеграции функциональности Zabbix в ваши приложения Python см. в библиотеке Python для Zabbix.

Доступ пользователей в Zabbix, включая как конфигурацию, так и исторические данные, зависит от типа пользователя, назначенной роли пользователя и групп пользователей.

Структура

API состоит из ряда методов, которые формально сгруппированы в отдельные API. Каждый из методов выполняет одну конкретную задачу. Например, метод host.create относится к host API и используется для создания новых узлов сети. Исторически API иногда называют "классами".

Большинство API содержат как минимум четыре метода: get, create, update и delete для получения, создания, обновления и удаления данных соответственно, однако некоторые API могут предоставлять совершенно иной набор методов.

Выполнение запросов

После настройки веб-интерфейса вы можете использовать удаленные HTTP-запросы для вызова API. Для этого необходимо отправлять HTTP POST-запросы к файлу api_jsonrpc.php, расположенному в каталоге веб-интерфейса.
Например, если ваш веб-интерфейс Zabbix установлен в https://example.com/zabbix, HTTP-запрос для вызова метода apiinfo.version может выглядеть так:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"apiinfo.version","params":{},"id":1}'

Запрос должен содержать заголовок Content-Type, установленный в одно из следующих значений: application/json-rpc, application/json или application/jsonrequest.

Объект запроса должен содержать следующие свойства:

jsonrpc - версия протокола JSON-RPC, используемого API (Zabbix API реализует JSON-RPC версии 2.0);
method - вызываемый метод API;
params - параметры, которые будут переданы методу API;
id - произвольный идентификатор запроса (если не указан, API рассматривает запрос как уведомление).

Если запрос корректен, ответ, возвращаемый API, должен выглядеть так:

{
    "jsonrpc": "2.0",
    "result": "7.0.0",
    "id": 1
}

Объект ответа, в свою очередь, содержит следующие свойства:

jsonrpc - версия протокола JSON-RPC;
result - данные, возвращенные методом;
id - идентификатор соответствующего запроса.

Аутентификация

Чтобы получить доступ к любым данным в Zabbix, необходимо либо:

Использовать существующий API token, созданный в веб-интерфейсе Zabbix, в разделе Users > API tokens, либо созданный с помощью Token API.
Использовать токен аутентификации, полученный с помощью метода user.login.

Например, если вы хотите получить новый токен аутентификации, выполнив вход как обычный пользователь Admin, JSON-запрос будет выглядеть так:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"user.login","params":{"username":"Admin","password":"zabbix"},"id":1}'

Если учетные данные указаны верно, ответ, возвращаемый API, должен содержать токен аутентификации пользователя:

{
    "jsonrpc": "2.0",
    "result": "0424bd59b807674191e7d77572075f33",
    "id": 1
}

Методы авторизации

По заголовку «Authorization»

Для всех запросов API требуется аутентификация или токен API. Вы можете указать учётные данные при помощи заголовка «Authorization» в запросе:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer 0424bd59b807674191e7d77572075f33'

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

Начиная с версии Zabbix 7.0.7, заголовок Authorization поддерживается в запросах с другого источника (cross-origin requests, CORS). Начиная с версии Zabbix 7.0.11, Zabbix API принимает заголовки без учёта регистра букв в названии заголовка (например, authorization, Authorization и AUTHORIZATION воспринимаются одинаково).

По свойству «auth»

Запрос API может быть авторизован при помощи свойства auth.

Учтите, что свойство auth является к устаревшим. Оно будет удалено в будущих релизах.

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"host.get","params":{"output":["hostid"]},"auth":"0424bd59b807674191e7d77572075f33","id":1}'

Cookie "zbx_session" используется для авторизации запроса API из веб-интерфейса Zabbix, выполняемого при помощи JavaScript (из модуля или пользовательского виджета).

Пример рабочего процесса

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

Получение узлов сети

Теперь у вас есть действительный токен аутентификации пользователя (представленный в следующих примерах как переменная), который можно использовать для доступа к данным в Zabbix. Например, вы можете использовать метод host.get, чтобы получить идентификаторы, имена узлов сети и интерфейсы всех настроенных узлов сети:

Запрос:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data @data.json

data.json — это файл, содержащий JSON-запрос. Вместо файла вы можете передать запрос в аргументе --data.

data.json

{
    "jsonrpc": "2.0",
    "method": "host.get",
    "params": {
        "output": [
            "hostid",
            "host"
        ],
        "selectInterfaces": [
            "interfaceid",
            "ip"
        ]
    },
    "id": 2
}

Объект ответа будет содержать запрошенные данные об узлах сети:

{
    "jsonrpc": "2.0",
    "result": [
        {
            "hostid": "10084",
            "host": "Zabbix server",
            "interfaces": [
                {
                    "interfaceid": "1",
                    "ip": "127.0.0.1"
                }
            ]
        }
    ],
    "id": 2
}

По соображениям производительности всегда рекомендуется перечислять свойства объекта, которые вы хотите получить. Так вы избежите получения всех данных.

Создание нового элемента данных

Теперь создайте новый элемент данных на узле сети "Zabbix server", используя данные, полученные из предыдущего запроса host.get. Это можно сделать с помощью метода item.create:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"item.create","params":{"name":"Free disk space on /home/joe/","key_":"vfs.fs.size[/home/joe/,free]","hostid":"10084","type":0,"value_type":3,"interfaceid":"1","delay":30},"id":3}'

Успешный ответ будет содержать ID вновь созданного элемента данных, который можно использовать для ссылки на элемент данных в следующих запросах:

{
    "jsonrpc": "2.0",
    "result": {
        "itemids": [
            "24759"
        ]
    },
    "id": 3
}

Метод item.create, как и другие методы создания, также может принимать массивы объектов и создавать несколько элементов данных за один вызов API.

Создание нескольких триггеров

Таким образом, если методы создания принимают массивы, вы можете добавить несколько триггеров, например, вот так:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"trigger.create","params":[{"description":"Processor load is too high on {HOST.NAME}","expression":"last(/Linux server/system.cpu.load[percpu,avg1])>5"},{"description":"Too many processes on {HOST.NAME}","expression":"avg(/Linux server/proc.num[],5m)>300"}],"id":4}'

Успешный ответ будет содержать идентификаторы вновь созданных триггеров:

{
    "jsonrpc": "2.0",
    "result": {
        "triggerids": [
            "17369",
            "17370"
        ]
    },
    "id": 4
}

Обновление элемента данных

Включите элемент данных, установив для его статуса значение 0:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"item.update","params":{"itemid":"10092","status":0},"id":5}'

Успешный ответ будет содержать ID обновленного элемента данных:

{
    "jsonrpc": "2.0",
    "result": {
        "itemids": [
            "10092"
        ]
    },
    "id": 5
}

Метод item.update, как и другие методы обновления, также может принимать массивы объектов и обновлять несколько элементов данных одним вызовом API.

Обновление нескольких триггеров

Включите несколько триггеров, установив для их статуса значение 0:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"trigger.update","params":[{"triggerid":"13938","status":0},{"triggerid":"13939","status":0}],"id":6}'

Успешный ответ будет содержать идентификаторы обновленных триггеров:

{
    "jsonrpc": "2.0",
    "result": {
        "triggerids": [
            "13938",
            "13939"
        ]
    },
    "id": 6
}

Это предпочтительный способ обновления. Некоторые методы API, такие как host.massupdate, позволяют написать более простой код. Однако не рекомендуется использовать эти методы, так как в будущих выпусках они будут удалены.

Обработка ошибок

До настоящего момента все, что вы пробовали, работало без проблем. Но что произойдет, если вы попробуете выполнить некорректный вызов API? Попробуйте создать еще один узел сети, вызвав host.create, но не указывая обязательный параметр groups:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"host.create","params":{"host":"Linux server","interfaces":[{"type":1,"main":1,"useip":1,"ip":"192.168.3.1","dns":"","port":"10050"}]},"id":7}'

В ответе будет сообщение об ошибке:

{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Invalid params.",
        "data": "No groups for host \"Linux server\"."
    },
    "id": 7
}

Если произошла ошибка, вместо свойства result объект ответа будет содержать свойство error со следующими данными:

code - код ошибки;
message - краткое описание ошибки;
data - более подробное сообщение об ошибке.

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

Версии API

Чтобы упростить версионирование API, начиная с Zabbix 2.0.4, версия API совпадает с версией самого Zabbix. Вы можете использовать метод apiinfo.version, чтобы узнать версию API, с которой вы работаете. Это может быть полезно для настройки вашего приложения с учетом функций, зависящих от версии.

Zabbix гарантирует обратную совместимость функций в пределах одной major-версии. При внесении обратно несовместимых изменений между major-релизами Zabbix обычно оставляет старые функции как устаревшие в следующем релизе и удаляет их только в релизе после него. Иногда Zabbix может удалять функции между major-релизами без предоставления какой-либо обратной совместимости. Важно никогда не полагаться на устаревшие функции и как можно скорее переходить на более новые альтернативы.

Вы можете отслеживать все изменения, внесенные в API, в журнале изменений API.

Дополнительное чтение

Теперь у вас достаточно знаний, чтобы начать работать с Zabbix API, однако не останавливайтесь на этом. Для дальнейшего изучения рекомендуем ознакомиться со списком доступных API.

What’s next?

Приложение 1. Справочные комментарии

Docs

20. API

Обзор