17. 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://company.com/zabbix, HTTP запрос для вызова метода apiinfo.version может выглядеть примерно так:

POST http://company.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 вам необходимо выполнить вход и получить ключ аутентификации. Это можно сделать, используя метод user.login. Давайте предположим, что вы хотите выполнить вход с использованием стандартного пользователя Zabbix Администратора. Тогда ваш JSON запрос может выглядеть следующим образом:

{
           "jsonrpc": "2.0",
           "method": "user.login",
           "params": {
               "user": "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, чтобы получить ID, имена узлов сети и интерфейсы всех настроенных узлов сети:

{
           "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 $1",
               "key_": "vfs.fs.size[/home/joe/,free]",
               "hostid": "10084",
               "type": 0,
               "value_type": 3,
               "interfaceid": "1",
               "delay": 30
           },
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 3
       }

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

{
           "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": "{Linux server:system.cpu.load[percpu,avg1].last()}>5",
               },
               {
                   "description": "Too many processes on {HOST.NAME}",
                   "expression": "{Linux server:proc.num[].avg(5m)}>300",
               }
           ],
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 4
       }

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

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

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

Активируем элемент данных, то есть, укажем ему состояние "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
       }

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

Активируем несколько триггеров, то есть, укажем им состояние 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.