20. API

Обзор

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

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

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

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

Более подробную информацию о протоколе и JSON можно найти в спецификации JSON-RPC 2.0 [en] и на домашней странице формата JSON [en].

Дополнительную информацию о встраивании функциональности Zabbix в ваши Python-приложения смотрите в библиотеке Python zabbix_utils [en] для работы с Zabbix API.

Структура

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 рассматривает запрос как уведомление [en]7.0.0).

Если запрос верен, ответ API должен быть примерно следующим:

{
           "jsonrpc": "2.0",
           "result": "7.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 7.0.7, заголовок Authorization поддерживается в запросах с другого источника (cross-origin requests, CORS). Начиная с версии Zabbix 7.0.11, Zabbix API принимает заголовки без учёта регистра букв в названии заголовка (например, authorization, Authorization и AUTHORIZATION воспринимаются одинаково).

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

Запрос API может быть авторизован при помощи свойства 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-файлам 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
       }

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

Активируйте несколько триггеров, указав для «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":"trigger.update","params":[{"triggerid":"13938","status":0},{"triggerid":"13939","status":0}],"id":6}'

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

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

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

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

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