Documentation
Table of Contents
Приложение 1. Справочные комментарии
Обозначение
Типы данных
Zabbix API поддерживает следующие типы данных в качестве входных данных:
|Тип|Описание| |----------------------|---------------------------------------- -----------| |boolean|Логическое значение, принимает либо true, либо false.| |flag|Значение считается true, если оно передано, и не равным null и false в противном случае.| |integer|Целое число.| |float|Число с плавающей запятой.| |string|Текстовая строка.| |text|Более длинная текстовая строка.| |timestamp|Временная метка Unix.| |array|Упорядоченная последовательность значений, то есть обычный массив.| |object|Ассоциативный массив.| |query|Значение, которое определяет, какие данные должны быть возвращены.
Можно определить как массив имен свойств для возврата только определенных свойств или как одно из предопределенных значений:extend - возвращает все свойства объекта;count - возвращает количество извлеченных записей, поддерживаемых только определенными подвыборками.|
Zabbix API всегда возвращает значения в виде строк или массивов.
Характер свойств
Для некоторых свойств объектов указаны краткие подписи, описывающие их характер. Используются следующие подписи:
- только чтение - значение свойства устанавливается автоматически, и пользователь не может задать или изменить его, даже в некоторых конкретных условиях (напр., только чтение для унаследованных или обнаруженных объектов);
- только запись - значение свойства можно задать, но после этого оно не будет доступно;
- постоянное - значение свойства можно задать при создании объекта, но нельзя изменить позднее;
- поддерживается - значение свойства не требуется задавать, но его можно задать в некоторых конкретных условиях (напр., поддерживается, если для
typeзадано "Простая проверка", "Внешняя проверка", "SSH агент", "TELNET агент" или "HTTP агент"); - требуется - значение свойства должно быть задано для всех операций (кроме операций получения) или в некоторых конкретных условиях (напр., требуется для операций создания; требуется, если для
operationtypeзадано "глобальный скрипт" и не задано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
}Ответ:
Нулевой результат означает отсутствие хостов с разрешениями на чтение/запись.
Подсчет несоответствий
Подсчитать количество хостов, имена которых не содержат подстроку "ubuntu"
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"countOutput": true,
"search": {
"host": "ubuntu"
},
"excludeSearch": true
},
"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
}