ru:manual:api:reference_commentary

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
ru:manual:api:reference_commentary [2018/06/13 11:55]
ru:manual:api:reference_commentary [2021/11/13 16:59] (current)
Line 1: Line 1:
 +===== Приложение 1. Справочные комментарии =====
 +
 +==== Обозначение ====
 +
 +=== Типы данных ===
 +
 +Zabbix API поддерживает следующие типы данных:​
 +
 +^ Тип ^ Описание ^
 +| логический | Логическое значение,​ принимает либо ''​true'',​ либо ''​false''​. |
 +| флаг | Значение считается ''​true'',​ если оно указано и не равно ''​null''​ и ''​false'',​ в противном случае. |
 +| целое число | Целое число. |
 +| дробное число | Число с плавающей точкой. |
 +| строка | Текстовая строка. |
 +| текст | Более длинная строка текста. |
 +| штамп времени | Штамп времени в формате Unix. |
 +| массив | Упорядоченная последовательность значения,​ то есть, простой массив. |
 +| объект | Ассоциативный массив. |
 +| запрос | Значение,​ которое определяет какие данные необходимо вернуть. \\ \\ Может быть задано массивом имен свойств,​ чтобы возвращались только указанные свойства или, в том числе, одно из предопределенных значений:​ \\ ''​extend''​ - возвращает все свойства объекта;​ \\ ''​count''​ - возвращает количество полученных записей,​ поддерживается только некоторыми подзапросами. |
 +
 +=== Подписи к свойствам ===
 +
 +Некоторые из свойств объектов маркируются короткими подписями,​ чтобы описать их поведение. Используются следующие подписи:​
 +  * //​только чтение//​ - значение этого свойства устанавливается автоматически не может быть определено или изменено клиентом;​
 +  * //​константа//​ - значение этого свойства можно устанавливать при создании объекта,​ но нельзя менять после.
 +
 +==== Зарезервированное значение ID равное "​0"​ ====
 +
 +Зарезервированное значение ID %%"​0"​%% можно использовать для фильтрации элементов и удаления связанных объектов. Например,​ для удаления ссылки на прокси с узла сети, proxy_hostid необходимо задать значением 0 (%%"​proxy_hostid":​ "​0"​%%) или для фильтрации узлов сети наблюдаемых сервером,​ опция proxyids должна быть задана значением 0 (%%"​proxyids":​ "​0"​%%).
 +
 +==== Общие параметры "​get"​ метода ====
 +
 +Следующие параметры поддерживаются всеми ''​get''​ методами:​
 +
 +^  Параметр ​ ^  Тип ​ ^  Описание ​ ^ 
 +|countOutput ​ |логический |Возвращает в результате количество записей вместо актуальных данных. ​ |
 +|editable | логический | Если задано равным ''​true'',​ возвращает только те объекты на которые у пользователя есть права на запись. \\ \\ По умолчанию:​ ''​false''​. |
 +|excludeSearch ​ |логический |Возвращает результаты,​ которые не совпадают с заданным критерием ''​search''​ параметре.| ​
 +|filter ​ |объект |Возвращать только те результаты,​ которые в точности совпадают с заданным фильтром.\\ \\ Принимает массив,​ где ключи являются именами свойств и значения,​ либо одно значение,​ либо массив значений соответствий. \\ \\ Не работает с ''​text''​ полями. |
 +|limit ​ |целое число |Ограничение количества возвращаемых записей. ​ |
 +|output ​ |запрос |Свойства возвращаемых объектов. \\ \\ По умолчанию:​ ''​extend''​. ​ |
 +|preservekeys ​ |логический |Использование ID как ключей в результирующем массиве. ​ |
 +|search ​ |объект |Возвращаемые результаты,​ которые соответствуют заданному шаблону поиска (регистрозависимый).\\ \\ Принимает массив,​ где ключами являются имена свойств и строковые значения для поиска. Если не заданы дополнительные опции, эта опция выполнит ''​LIKE "​%…%"''​ поиск.\\ \\ Работает только с ''​string''​ и ''​text''​ полями. |
 +|searchByAny ​ |логический | Если задано равным ''​true'',​ возвращает результаты которые совпадают с любым из заданных критериев в ''​filter''​ или ''​search''​ параметрах вместо соответствия по всем. ​ \\ \\ По умолчанию:​ ''​false''​. ​ |
 +|searchWildcardsEnabled ​ |логический | Если задано равным ''​true'',​ включает использование "​*"​ символом шаблона в ''​search''​ параметре. ​ \\ \\ По умолчанию:​ ''​false''​. |
 +|sortfield ​ |строка/​массив |Сортировка результата по заданным свойствам. Обратитесь к отдельным описаниям get методов API для получения списка свойств,​ которые можно использовать при сортировке. Макросы не раскрываются до сортировки.\\ \\ Если никакое значение не задано,​ данные будут возвращены не отсортированными. |
 +|sortorder ​ |строка/​массив |Порядок сортировки. Если передан массив,​ каждое значение будет сопоставляться соответствующему свойству из ''​sortfield''​ параметра.\\ \\ Возможные значения:​ \\ ''​ASC''​ //(по умолчанию)//​ - по возрастанию;​ \\ ''​DESC''​ - по убыванию. ​ |
 +|startSearch ​ |логический |''​search''​ параметр будет сравнивать начало полей, то есть, выполнять ''​LIKE "​…%"''​ поиск.\\ \\ Игнорируется,​ если ''​searchWildcardsEnabled''​ задан равным ''​true''​. ​ |
 +
 +==== Примеры ====
 +
 +=== Проверка прав доступа пользователя ===
 +
 +Имеет ли пользовать права доступа на запись к узлам сети чьи имена начинаются с "​MySQL"​ или "​Linux"​ ?
 +
 +Запрос:​
 +<code java>
 +{
 +    "​jsonrpc":​ "​2.0",​
 +    "​method":​ "​host.get",​
 +    "​params":​ {
 +        "​countOutput":​ true,
 +        "​search":​ {
 +            "​host":​ ["​MySQL",​ "​Linux"​]
 +        },
 +        "​editable":​ true,
 +        "​startSearch":​ true,
 +        "​searchByAny":​ true
 +    },
 +    "​auth":​ "​766b71ee543230a1182ca5c44d353e36",​
 +    "​id":​ 1
 +}
 +</​code>​
 +
 +Ответ:
 +<code java>
 +{
 +    "​jsonrpc":​ "​2.0",​
 +    "​result":​ "​0",​
 +    "​id":​ 1
 +}
 +</​code>​
 +
 +<​note>​Нулевой результат означает,​ что узлы сети с правами чтения/​записи отсутствуют.</​note>​
 +
 +=== Подсчёт негативных данных ===
 +
 +Подсчёт количества узлов сети чьи имена не содержат подстроку "​ubuntu"​
 +
 +Запрос:​
 +<code java>
 +{
 +    "​jsonrpc":​ "​2.0",​
 +    "​method":​ "​host.get",​
 +    "​params":​ {
 +        "​countOutput":​ true,
 +        "​search":​ {
 +            "​host":​ "​ubuntu"​
 +        },
 +        "​excludeSearch":​ true
 +    },
 +    "​auth":​ "​766b71ee543230a1182ca5c44d353e36",​
 +    "​id":​ 1
 +}
 +</​code>​
 +
 +Ответ:
 +<code java>
 +{
 +    "​jsonrpc":​ "​2.0",​
 +    "​result":​ "​44",​
 +    "​id":​ 1
 +}
 +</​code>​
 +
 +=== Поиск узлов сети по шаблону имени ===
 +
 +Поиск узлов сети чьи имена содержат слово "​server"​ и имеют порты интерфейсов "​10050"​ или "​10071"​. Сортировка результата по имени узла сети в порядке убывания с ограничением вывода до 5 узлов сети.
 +
 +Запрос:​
 +<code java>
 +{
 +    "​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
 +}
 +</​code>​
 +
 +Ответ:
 +<code java>
 +{
 +    "​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
 +}</​code>​
 +
 +=== Поиск узлов сети по шаблону имени с "​preservekeys"​ ===
 +
 +Если вы добавите параметр "​preservekeys"​ к предыдущему запросу,​ результат вернётся как именованный массив,​ где ключами будут id объектов.
 +
 +Запрос:​
 +<code java>
 +{
 +    "​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
 +}
 +</​code>​
 +
 +Ответ:
 +<code java>
 +{
 +    "​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
 +}
 +</​code>​