Приложение 1. Справочные комментарии

Обозначение

Типы данных

Zabbix API поддерживает следующие типы данных:

Тип Описание
логический Логическое значение, принимает либо true, либо false.
флаг Значение считается true, если оно указано и не равно null и false, в противном случае.
целое число Целое число.
дробное число Число с плавающей точкой.
строка Текстовая строка.
текст Более длинная строка текста.
штамп времени Штамп времени в формате Unix.
массив Упорядоченная последовательность значения, то есть, простой массив.
объект Ассоциативный массив.
запрос Значение, которое определяет какие данные необходимо вернуть.

Может быть задано массивом имен свойств, чтобы возвращались только указанные свойства или, в том числе, одно из предопределенных значений:
extend - возвращает все свойства объекта;
count - возвращает количество полученных записей, поддерживается только некоторыми подзапросами.

Подписи к свойствам

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

  • только чтение - значение этого свойства устанавливается автоматически не может быть определено или изменено клиентом;
  • константа - значение этого свойства можно устанавливать при создании объекта, но нельзя менять после.

Удаление ссылки на объект через API

Зарезервированное значение ID "0" можно использовать для удаления ссылок на объекты. Например, для удаления ссылки на прокси с узла сети, proxy_hostid необходимо задать значением 0 ("proxy_hostid": "0").

Общие параметры "get" метода

Следующие параметры поддерживаются всеми get методами:

Параметр Тип Описание
countOutput флаг Возвращает в результате количество записей вместо актуальных данных.
editable логический Если задано равным true, возвращает только те объекты на которые у пользователя есть права на запись.

По умолчанию: false.
excludeSearch флаг Возвращает результаты, которые не совпадают с заданным критерием search параметре.
filter объект Возвращать только те результаты, которые в точности совпадают с заданным фильтром.

Принимает массив, где ключи являются именами свойств и значения, либо одно значение, либо массив значений соответствий.

Не работает с text полями.
limit целое число Ограничение количества возвращаемых записей.
output запрос Свойства возвращаемых объектов.

По умолчанию: extend.
preservekeys флаг Использование ID как ключей в результирующем массиве.
search объект Возвращаемые результаты, которые соответствуют заданному шаблону поиска (регистрозависимый).

Принимает массив, где ключами являются имена свойств и строковые значения для поиска. Если не заданы дополнительные опции, эта опция выполнит LIKE "%…%" поиск.

Работает только с string и text полями.
searchByAny логический Если задано равным true, возвращает результаты которые совпадают с любым из заданных критериев в filter или search параметрах вместо соответствия по всем.

По умолчанию: false.
searchWildcardsEnabled логический Если задано равным true, включает использование "*" символом шаблона в search параметре.

По умолчанию: false.
sortfield строка/массив Сортировка результата по заданным свойствам. Обратитесь к отдельным описаниям get методов API для получения списка свойств, которые можно использовать при сортировке. Макросы не раскрываются до сортировки.

Если никакое значение не задано, данные будут возвращены не отсортированными.
sortorder строка/массив Порядок сортировки. Если передан массив, каждое значение будет сопоставляться соответствующему свойству из sortfield параметра.

Возможные значения:
ASC - (по умолчанию) по возрастанию;
DESC - по убыванию.
startSearch флаг search параметр будет сравнивать начало полей, то есть, выполнять LIKE "…%" поиск.

Игнорируется, если searchWildcardsEnabled задан равным true.

Примеры

Проверка прав доступа пользователя

Имеет ли пользовать права доступа на запись к узлам сети чьи имена начинаются с "MySQL" или "Linux" ?

Запрос:

{
           "jsonrpc": "2.0",
           "method": "host.get",
           "params": {
               "countOutput": true,
               "search": {
                   "host": ["MySQL", "Linux"]
               },
               "editable": true,
               "startSearch": true,
               "searchByAny": true
           },
           "auth": "766b71ee543230a1182ca5c44d353e36",
           "id": 1
       }

Ответ:

{
           "jsonrpc": "2.0",
           "result": "0",
           "id": 1
       }

Нулевой результат означает, что узлы сети с правами чтения/записи отсутствуют.

Подсчёт негативных данных

Подсчёт количества узлов сети чьи имена не содержат подстроку "ubuntu"

Запрос:

{
           "jsonrpc": "2.0",
           "method": "host.get",
           "params": {
               "countOutput": true,
               "search": {
                   "host": "ubuntu"
               },
               "excludeSearch": true
           },
           "auth": "766b71ee543230a1182ca5c44d353e36",
           "id": 1
       }

Ответ:

{
           "jsonrpc": "2.0",
           "result": "44",
           "id": 1
       }

Поиск узлов сети по шаблону имени

Поиск узлов сети чьи имена содержат слово "server" и имеют порты интерфейсов "10050" или "10071". Сортировка результата по имени узла сети в порядке убывания с ограничением вывода до 5 узлов сети.

Запрос:

{
           "jsonrpc": "2.0",
           "method": "host.get",
           "params": {
               "output": ["hostid", "host"],
               "selectInterfaces": ["port"],
               "filter": {
                   "port": ["10050", "10071"]
               },
               "search": {
                   "host": "*server*"
               },
               "searchWildcardsEnabled": true,
               "searchByAny": true,
               "sortfield": "host",
               "sortorder": "DESC",
               "limit": 5
           },
           "auth": "766b71ee543230a1182ca5c44d353e36",
           "id": 1
       }

Ответ:

{
           "jsonrpc": "2.0",
           "result": [
               {
                   "hostid": "50003",
                   "host": "WebServer-Tomcat02",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               {
                   "hostid": "50005",
                   "host": "WebServer-Tomcat01",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               {
                   "hostid": "50004",
                   "host": "WebServer-Nginx",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               {
                   "hostid": "99032",
                   "host": "MySQL server 01",
                   "interfaces": [
                       {
                           "port": "10050"
                       }
                   ]
               },
               {
                   "hostid": "99061",
                   "host": "Linux server 01",
                   "interfaces": [
                       {
                           "port": "10050"
                       }
                   ]
               }
           ],
           "id": 1
       }

Поиск узлов сети по шаблону имени с "preservekeys"

Если вы добавите параметр "preservekeys" к предыдущему запросу, результат вернётся как именованный массив, где ключами будут id объектов.

Запрос:

{
           "jsonrpc": "2.0",
           "method": "host.get",
           "params": {
               "output": ["hostid", "host"],
               "selectInterfaces": ["port"],
               "filter": {
                   "port": ["10050", "10071"]
               },
               "search": {
                   "host": "*server*"
               },
               "searchWildcardsEnabled": true,
               "searchByAny": true,
               "sortfield": "host",
               "sortorder": "DESC",
               "limit": 5,
               "preservekeys": true
           },
           "auth": "766b71ee543230a1182ca5c44d353e36",
           "id": 1
       }

Ответ:

{
           "jsonrpc": "2.0",
           "result": {
               "50003": {
                   "hostid": "50003",
                   "host": "WebServer-Tomcat02",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               "50005": {
                   "hostid": "50005",
                   "host": "WebServer-Tomcat01",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },        
               "50004": {
                   "hostid": "50004",
                   "host": "WebServer-Nginx",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               "99032": {
                   "hostid": "99032",
                   "host": "MySQL server 01",
                   "interfaces": [
                       {
                           "port": "10050"
                       }
                   ]
               },
               "99061": {
                   "hostid": "99061",
                   "host": "Linux server 01",
                   "interfaces": [
                       {
                           "port": "10050"
                       }
                   ]
               }
           },
           "id": 1
       }