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установлен в "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
}Ответ:
Нулевой результат означает отсутствие хостов с разрешениями на чтение/запись.
Подсчет несоответствий
Подсчитать количество хостов, имена которых не содержат подстроку "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
}