19 API

Обзор

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

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

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

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

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

Структура

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 должен быть примерно следующим:

{
           "jsonrpc": "2.0",
           "result": "6.4.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'

По свойству "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}'

By Zabbix cookie

A "zbx_session" cookie is used to authorize an API request from Zabbix UI performed using JavaScript (from a module or a custom widget).

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

Теперь у вас есть валидный токен аутентификации пользователя, который можно использовать для доступа к данным в 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.

{
           "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,
           "auth": "0424bd59b807674191e7d77572075f33"
       }

Тогда ответ будет содержать сообщение об ошибке:

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