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 всегда возвращает значения только в виде строк или массивов.
Поведение свойства
Некоторые свойства объекта отмечены короткими метками для описания их поведения. Используются следующие метки:
- read-only - значение свойства устанавливается автоматически и не может быть определено или изменено пользователем, даже в некоторых специфических условиях (например, свойство read-only для унаследованных или обнаруженных объектов);
- write-only - значение свойства можно установить, но после этого к нему нельзя получить доступ;
- constant - значение свойства можно установить при создании объекта, но после этого его нельзя изменить;
- supported - значение свойства не обязательно должно быть установлено, но его можно установить в некоторых специфических условиях (например, supported, если для
typeзадано "Простая проверка", "Внешняя проверка", "SSH агент", "TELNET агент" или "HTTP агент"); - required - значение свойства обязательно для установки во всех операциях (кроме операций получения) или в некоторых специфических условиях (например, required для операций создания; required, если для
operationtypeзадано "глобальный скрипт" и не заданоopcommand_hst).
Для операций обновления свойство считается "установленным", если оно устанавливается в ходе операции обновления.
Свойства, не отмеченные метками, являются необязательными.
Поведение параметра
Некоторые параметры операции помечены короткими метками для описания их поведения в рамках операции. Используются следующие метки:
- read-only - значение параметра устанавливается автоматически и не может быть определено или изменено пользователем, даже в некоторых специфических условиях (например, read-only для унаследованных или обнаруженных объектов);
- write-only - значение параметра можно установить, но после этого к нему нельзя получить доступ;
- supported - значение параметра не обязательно должно быть установлено, но его можно установить в некоторых специфических условиях (например, supported, если для
statusобъекта прокси задано "пассивный прокси"); - required - значение параметра обязательно для установки.
Параметры, не отмеченные метками, являются необязательными.
Зарезервированное значение 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
},
"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
}