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

Обозначение

Типы данных

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

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

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

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

Поведение свойства

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

  • только для чтения - значение свойства задаётся автоматически и не может быть определено или изменено пользователем, даже в особых случаях (например, только для чтения для наследуемых или обнаруженных объектов);
  • только для записи - значение свойства можно установить, но нельзя прочитать после;
  • постоянное -значение свойства можно задать при создании объекта, но нельзя изменить позже;
  • поддерживаемое - значение свойства не обязательно к установке, но может быть задано при определённых условиях (например, поддерживаемое, если type установлен в "Simple check", "External check", "SSH agent", "TELNET agent" или "HTTP agent"). Однако даже поддерживаемое свойства могут автоматически принимать значения по умолчанию независимо от условий;
  • обязательное значение свойства обязательно для указания при всех операциях (кроме get) или при определённых условиях (например, обязательное при создании объекта; обязательное, если operationtype имеет значение "global script", а opcommand_hst не задан).

Для операций обновления свойство считается "установленным", если его значение задаётся в процессе выполнения операции обновления.

Свойства, не отмеченные метками, являются необязательными.

Характер параметров

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

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

Параметры, для которых не указаны подписи, являются необязательными.

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

Зарезервированное значение ID "0" можно использовать для фильтрации элементов и удаления связанных объектов. Например, для удаления ссылки на прокси с узла сети, proxytid необходимо задать значением 0 ("proxyid": "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
    },
    "id": 1
}

Ответ:

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

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

Подсчет несоответствий

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

Запрос:

{
    "jsonrpc": "2.0",
    "method": "host.get",
    "params": {
        "countOutput": true,
        "search": {
            "host": "ubuntu"
        },
        "excludeSearch": true
    },
    "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
    },
    "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
    },
    "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
}