18 API

Обзор

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.

Структура

API состоит из ряда методов, которые условно сгруппированы в отдельные API. Каждый метод выполняет одну отдельную задачу. Например, метод host.create относится к API узла сети и используется для создания новых узлов сети. Исторически для 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 (созданный в веб-интерфейсе Zabbix или с помощью 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'

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

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

По cookie Zabbix

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

{
    "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
}

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

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

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}'

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

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

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

Активируйте элемент данных, указав для "status" значение "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
}

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

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

Дополнительная литература

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