Это перевод страницы документации с английского языка. Помогите нам сделать его лучше.

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 иногда назывался как "классы".

Большинство API содержит по крайней мере четыре метода: get, create, update и delete для получения, создания, обновления и удаления данных соответственно, однако, некоторые 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.

Вы можете использовать любой клиент HTTP или утилиту тестирования JSON-RPC для выполнения API запросов вручную, но для разработки приложений мы предлагаем вам воспользоваться одной из библиотек, которые поддерживает сообщество.

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

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

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

Прежде чем вы сможете запросить любые данные с 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"
       }

Обратите внимание, что свойство auth теперь задано равным ключу аутентификации, который мы получили вызвав user.login.

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

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

Метод item.create, также как и другие методы создания, может также принимать массивы объектов и создавать несколько элементов данных за один запрос API.

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

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

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

Метод item.update, а так же и другие методы обновления могут также принимать массивы объектов и обновлять несколько элементов данных за один API запрос.

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

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

Обработка ошибок

До этого момента всё что мы пробовали работало прекрасно. Но что случится, если мы попробуем выполнить некорректный запрос к 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.

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

Вы можете следить за всеми изменениями, внесенными в API на странице журнала изменений API.

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

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