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

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

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

Учтите, что свойство "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}'

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 - это файл, содержащий запрос JSON. Вместо использования файла запрос можно передать при помощи аргумента --data.

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
       }

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

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

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

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
       }

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

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

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