19 API

Обзор

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

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

Zabbix API является API на веб-основе и поставляется как часть веб-интерфейса. Он использует протокол 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 установлен в http://example.com/zabbix, HTTP-запрос для вызова метода apiinfo.version может выглядеть так:

POST http://example.com/zabbix/api_jsonrpc.php HTTP/1.1
       Content-Type: application/json-rpc
       
       {
           "jsonrpc": "2.0",
           "method": "apiinfo.version",
           "id": 1,
           "auth": null,
           "params": {}
       }

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

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

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

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

Для доступа к любым данным в Zabbix необходимо:

• либо использовать существующий токен API (созданный в веб-интерфейсе Zabbix или с помощью Token API);
• либо использовать токен аутентификации, полученный методом user.login.

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

{
           "jsonrpc": "2.0",
           "method": "user.login",
           "params": {
               "username": "Admin",
               "password": "zabbix"
           },
           "id": 1,
           "auth": null
       }

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Активируйте элемент данных, то есть укажите для "status" значение "0":

{
           "jsonrpc": "2.0",
           "method": "item.update",
           "params": {
               "itemid": "10092",
               "status": 0
           },
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 5
       }

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

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

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

Активируйте несколько триггеров, то есть укажите для "status" значение "0":

{
           "jsonrpc": "2.0",
           "method": "trigger.update",
           "params": [
               {
                   "triggerid": "13938",
                   "status": 0
               },
               {
                   "triggerid": "13939",
                   "status": 0
               }
           ],
           "auth": "0424bd59b807674191e7d77572075f33",
           "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.