ru:manual:api:reference_commentary

Differences

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

Link to this comparison view

Next revision
Previous revision
ru:manual:api:reference_commentary [2015/12/26 23:25]
dotneft created
ru:manual:api:reference_commentary [2019/11/25 05:09] (current)
dotneft
Line 8: Line 8:
  
 ^ Тип ^ Описание ^ ^ Тип ^ Описание ^
-bool | Логическое значение,​ принимает либо ''​true'',​ либо ''​false''​. | +логический ​| Логическое значение,​ принимает либо ''​true'',​ либо ''​false''​. | 
-flag | Значение считается ''​true'',​ если оно указано и не равно ''​null''​ и ''​false'',​ в противном случае. | +флаг ​| Значение считается ''​true'',​ если оно указано и не равно ''​null''​ и ''​false'',​ в противном случае. | 
-integer ​| Целое число. | +целое число ​| Целое число. | 
-float | Число с плавающей точкой. | +дробное число ​| Число с плавающей точкой. | 
-string ​| Текстовая строка. | +строка ​| Текстовая строка. | 
-text | Более длинная строка текста. | +текст ​| Более длинная строка текста. | 
-timestamp ​| Штамп времени в формате Unix. | +штамп времени ​| Штамп времени в формате Unix. | 
-array | Упорядоченная последовательность значения,​ то есть, простой массив. | +массив ​| Упорядоченная последовательность значения,​ то есть, простой массив. | 
-object ​| Ассоциативный массив. | +объект ​| Ассоциативный массив. | 
-query | Значение,​ которое определяет какие данные необходимо вернуть. \\ \\ Может быть задано массивом имен свойств,​ чтобы возвращались только указанные свойства или, в том числе, одно из предопределенных значений:​ \\ ''​extend''​ - возвращает все свойства объекта;​ \\ ''​count''​ - возвращает количество полученных записей,​ поддерживается только некоторыми подзапросами. |+запрос ​| Значение,​ которое определяет какие данные необходимо вернуть. \\ \\ Может быть задано массивом имен свойств,​ чтобы возвращались только указанные свойства или, в том числе, одно из предопределенных значений:​ \\ ''​extend''​ - возвращает все свойства объекта;​ \\ ''​count''​ - возвращает количество полученных записей,​ поддерживается только некоторыми подзапросами. |
  
 === Подписи к свойствам === === Подписи к свойствам ===
Line 24: Line 24:
   * //​только чтение//​ - значение этого свойства устанавливается автоматически не может быть определено или изменено клиентом;​   * //​только чтение//​ - значение этого свойства устанавливается автоматически не может быть определено или изменено клиентом;​
   * //​константа//​ - значение этого свойства можно устанавливать при создании объекта,​ но нельзя менять после.   * //​константа//​ - значение этого свойства можно устанавливать при создании объекта,​ но нельзя менять после.
 +
 +==== Удаление ссылки на объект через API ====
 +
 +Зарезервированное значение ID %%"​0"​%% можно использовать для удаления ссылок на объекты. Например,​ для удаления ссылки на прокси с узла сети, proxy_hostid необходимо задать значением 0 (%%"​proxy_hostid":​ "​0"​%%).
  
 ==== Общие параметры "​get"​ метода ==== ==== Общие параметры "​get"​ метода ====
Line 30: Line 34:
  
 ^  Параметр ​ ^  Тип ​ ^  Описание ​ ^  ^  Параметр ​ ^  Тип ​ ^  Описание ​ ^ 
-|countOutput ​ |flag |Возвращает в результате количество записей вместо актуальных данных. ​ | +|countOutput ​ |флаг ​|Возвращает в результате количество записей вместо актуальных данных. ​ | 
-|editable | boolean ​| Если задано равным ''​true'',​ возвращает только те объекты на которые у пользователя есть права на запись. \\ \\ По умолчанию:​ ''​false''​. | +|editable | логический ​| Если задано равным ''​true'',​ возвращает только те объекты на которые у пользователя есть права на запись. \\ \\ По умолчанию:​ ''​false''​. | 
-|excludeSearch ​ |flag |Возвращает результаты,​ которые не совпадают с заданным критерием ''​search''​ параметре.|  +|excludeSearch ​ |флаг ​|Возвращает результаты,​ которые не совпадают с заданным критерием ''​search''​ параметре.|  
-|filter ​ |object ​|Возвращать только те результаты,​ которые в точности совпадают с заданным фильтром.\\ \\ Принимает массив,​ где ключи являются именами свойств и значения,​ либо одно значение,​ либо массив значений соответствий. \\ \\ Не работает с ''​text''​ полями. | +|filter ​ |объект ​|Возвращать только те результаты,​ которые в точности совпадают с заданным фильтром.\\ \\ Принимает массив,​ где ключи являются именами свойств и значения,​ либо одно значение,​ либо массив значений соответствий. \\ \\ Не работает с ''​text''​ полями. | 
-|limit ​ |integer ​|Ограничение количества возвращаемых записей. ​ | +|limit ​ |целое число ​|Ограничение количества возвращаемых записей. ​ | 
-|output ​ |query |Свойства возвращаемых объектов. \\ \\ Default: ''​extend''​. ​ | +|output ​ |запрос ​|Свойства возвращаемых объектов. \\ \\ По умолчанию: ''​extend''​. ​ | 
-|preservekeys ​ |flag |Использование ID как ключей в результирующем массиве. ​ | +|preservekeys ​ |флаг ​|Использование ID как ключей в результирующем массиве. ​ | 
-|search ​ |object ​|Возвращаемые результаты,​ которые соответствуют заданному шаблону поиска.\\ \\ Принимает массив,​ где ключами являются имена свойств и строковые значения для поиска. Если не заданы дополнительные опции, эта опция выполнит ''​LIKE "​%…%"''​ поиск.\\ \\ Работает только с ''​string''​ и ''​text''​ полями. | +|search ​ |объект ​|Возвращаемые результаты,​ которые соответствуют заданному шаблону поиска ​(регистрозависимый).\\ \\ Принимает массив,​ где ключами являются имена свойств и строковые значения для поиска. Если не заданы дополнительные опции, эта опция выполнит ''​LIKE "​%…%"''​ поиск.\\ \\ Работает только с ''​string''​ и ''​text''​ полями. | 
-|searchByAny ​ |boolean ​| Если задано равным ''​true'',​ возвращает результаты которые совпадают с любым из заданных критериев в ''​filter''​ или ''​search''​ параметрах вместо соответствия по всем. ​ \\ \\ По умолчанию:​ ''​false''​. ​ | +|searchByAny ​ |логический ​| Если задано равным ''​true'',​ возвращает результаты которые совпадают с любым из заданных критериев в ''​filter''​ или ''​search''​ параметрах вместо соответствия по всем. ​ \\ \\ По умолчанию:​ ''​false''​. ​ | 
-|searchWildcardsEnabled ​ |boolean ​| Если задано равным ''​true'',​ включает использование "​*"​ символом шаблона в ''​search''​ параметре. ​ \\ \\ По умолчанию:​ ''​false''​. | +|searchWildcardsEnabled ​ |логический ​| Если задано равным ''​true'',​ включает использование "​*"​ символом шаблона в ''​search''​ параметре. ​ \\ \\ По умолчанию:​ ''​false''​. | 
-|sortfield ​ |string/array |Сортировка результата по заданным свойствам. Обратитесь к отдельным описаниям get методов API для получения списка свойств,​ которые можно использовать при сортировке. | +|sortfield ​ |строка/массив ​|Сортировка результата по заданным свойствам. Обратитесь к отдельным описаниям get методов API для получения списка свойств,​ которые можно использовать при сортировке. Макросы не раскрываются до сортировки.\\ \\ Если никакое значение не задано,​ данные будут возвращены не отсортированными. | 
-|sortorder ​ |string/array |Порядок сортировки. Если передан массив,​ каждое значение будет сопоставляться соответствующему свойству из ''​sortfield''​ параметра.\\ \\ Возможные значения:​ \\ ''​ASC''​ - по возрастанию;​ \\ ''​DESC''​ - по убыванию. ​ | +|sortorder ​ |строка/массив ​|Порядок сортировки. Если передан массив,​ каждое значение будет сопоставляться соответствующему свойству из ''​sortfield''​ параметра.\\ \\ Возможные значения:​ \\ ''​ASC''​ - //(по умолчанию)// ​по возрастанию;​ \\ ''​DESC''​ - по убыванию. ​ | 
-|startSearch ​ |flag |''​search''​ параметр будет сравнивать начало полей, то есть, выполнять ''​LIKE "​…%"''​ поиск. ​ |+|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>​