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

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

Zabbix API — это 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": "8.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.

API Zabbix принимает заголовки без учета регистра (например, authorization, Authorization и AUTHORIZATION обрабатываются одинаково).

Заголовок Authorization поддерживается в кросс-доменных запросах (CORS).

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

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

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

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

What’s next?

Справочник методов

Docs

API

Обзор