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

Обозначение

Типы данных

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

Тип Описание
boolean Логическое значение, принимает либо true, либо false.
flag Значение считается истинным, если оно передано и не равно нулю; в противном случае оно считается ложным.
integer Целое число.
float Число с плавающей запятой.
string Текстовая строка.
text Более длинная текстовая строка.
timestamp Временная метка Unix.
array Упорядоченная последовательность значений, то есть обычный массив.
object Ассоциативный массив.
query Значение, которое определяет, какие данные должны быть возвращены.

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

Zabbix API всегда возвращает значения в виде строк или массивов.

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

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

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

Зарезервированное значение ID равное "0"

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

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

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

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

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

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

Не поддерживает поля текстового типа данных.
limit integer Ограничить количество возвращаемых записей.
output query Свойства объекта, которые будут возвращены.

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

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

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

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

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

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

Возможные значения:
ASC - (по умолчанию) по возрастанию;
DESC - по убыванию.
startSearch boolean Параметр 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
       }
       }