[comment]: # ({6d056871-6d056871}) # Приложение 1. Справочные комментарии [comment]: # ({/6d056871-6d056871}) [comment]: # ({6594bdc4-6594bdc4}) ### Обозначение [comment]: # ({/6594bdc4-6594bdc4}) [comment]: # ({8c926b1a-2df08058}) #### Типы данных API Zabbix поддерживает следующие типы данных в качестве входных данных: |Type|Description| |--|--------| |ID|Уникальный идентификатор, используемый для ссылки на сущность.| |boolean|Логическое значение (либо `true`, либо `false`).| |flag|Значение, которое считается `true`, если оно передано и не равно `null`; в противном случае значение считается `false`.| |integer|Целое число.| |float|Число с плавающей точкой.| |string|Текстовая строка.| |text|Более длинная текстовая строка.| |timestamp|Метка времени Unix.| |array|Упорядоченная последовательность значений (обычный массив).| |object|Ассоциативный массив.| |query|Значение, определяющее, какие данные будут возвращены. Значение может быть задано как массив имен свойств (чтобы вернуть только определенные свойства) или как одно из предопределенных значений:
`extend` - возвращает все свойства объекта;
`count` - возвращает количество полученных записей, поддерживается только некоторыми подзапросами.| ::: noteimportant API Zabbix всегда возвращает значения только в виде строк или массивов. ::: [comment]: # ({/8c926b1a-2df08058}) [comment]: # ({8f68b338-a2c16a18}) #### Поведение свойства Некоторые свойства объектов помечены короткими метками, описывающими их поведение. Используются следующие обозначения: - ***только для чтения*** - значение свойства задаётся автоматически и не может быть определено или изменено пользователем, даже в особых случаях (например, *только для чтения* для наследуемых или обнаруженных объектов); - ***только для записи*** - значение свойства можно установить, но нельзя прочитать после; - ***постоянное*** -значение свойства можно задать при создании объекта, но нельзя изменить позже; - ***поддерживаемое*** - значение свойства не обязательно к установке, но может быть задано при определённых условиях (например, *поддерживаемое*, если `type` установлен в "Simple check", "External check", "SSH agent", "TELNET agent" или "HTTP agent"). Однако даже *поддерживаемое* свойства могут автоматически принимать значения по умолчанию независимо от условий; - ***обязательное*** значение свойства обязательно для указания при всех операциях (кроме get) или при определённых условиях (например, *обязательное* при создании объекта; *обязательное*, если `operationtype` имеет значение "global script", а `opcommand_hst` не задан). ::: noteclassic Для операций обновления свойство считается "установленным", если его значение задаётся в процессе выполнения операции обновления. ::: Свойства, не отмеченные метками, являются необязательными. [comment]: # ({/8f68b338-a2c16a18}) [comment]: # ({f960f4be-f255da9d}) #### Поведение параметров Некоторые параметры операции помечены короткими метками, описывающими их поведение для операции. Используются следующие метки: - ***read-only*** - значение параметра задается автоматически и не может быть определено или изменено пользователем, даже в некоторых конкретных случаях (например, *read-only* для унаследованных объектов или обнаруженных объектов); - ***write-only*** - значение параметра можно задать, но после этого к нему нельзя получить доступ; - ***supported*** - значение параметра не требуется задавать, но его можно задать в некоторых конкретных случаях (например, *supported*, если `operating_mode` объекта Proxy установлен в "passive proxy"); однако следует отметить, что параметры *supported* все равно могут быть установлены в значения по умолчанию независимо от условий; - ***required*** - значение параметра обязательно должно быть задано. Параметры, не помеченные метками, являются необязательными. [comment]: # ({/f960f4be-f255da9d}) [comment]: # ({cf59def4-5e99748d}) ### Зарезервированное значение ID равное "0" Зарезервированное значение ID "0" можно использовать для фильтрации элементов и удаления связанных объектов. Например, для удаления ссылки на прокси с узла сети, proxytid необходимо задать значением 0 ("proxyid": "0") или для фильтрации узлов сети наблюдаемых сервером, опция proxyids должна быть задана значением 0 ("proxyids": "0"). [comment]: # ({/cf59def4-5e99748d}) [comment]: # ({da9957c2-b4e0f5ab}) ### Общие параметры метода `get` Следующие параметры поддерживаются всеми методами `get`: |Parameter|[Type](#data-types)|Description| |-|-|-| |countOutput|boolean|Возвращать количество записей в результате вместо самих данных.| |editable|boolean|Если установлено в `true`, возвращать только объекты, для которых у пользователя есть права на запись.

По умолчанию: `false`.| |excludeSearch|boolean|Возвращать результаты, которые не соответствуют критериям, заданным в параметре `search`.| |filter|object|Возвращать только те результаты, которые точно соответствуют заданному фильтру.

Принимает объект, где ключи — это имена свойств (например, свойства объекта Host в `host.get`, свойства объекта Item в `item.get` и т. д.), а значения — либо одно значение, либо массив значений для сопоставления.

Не поддерживает свойства с [типом данных](#data-types) `text`.

Обратите внимание, что некоторые методы имеют специальную функциональность для этого параметра, которая описана на странице метода (например, параметр `filter` в [host.get](/manual/api/reference/host/get) также поддерживает свойства интерфейса узла сети).| |limit|integer|Ограничить количество возвращаемых записей.| |output|query|Свойства объекта, которые нужно вернуть.

Обратите внимание, что идентификатор объекта (то есть `hostid`, `itemid` и т. д.) всегда включается в ответ, даже если он не указан в параметре `output`.

По умолчанию: `extend`.| |preservekeys|boolean|Использовать идентификаторы в качестве ключей в результирующем массиве.| |search|object|Возвращать результаты, которые соответствуют заданному шаблону (без учета регистра).

Принимает объект, где ключи — это имена свойств (например, свойства объекта Host в `host.get`, свойства объекта Item в `item.get` и т. д.), а значения — строки для поиска. Если дополнительные параметры не заданы, будет выполнен поиск `LIKE "%…%"`.

Поддерживает только свойства с [типом данных](#data-types) `string` и `text`.

Обратите внимание, что некоторые методы имеют специальную функциональность для этого параметра, которая описана на странице метода (например, параметр `search` в [host.get](/manual/api/reference/host/get) также поддерживает свойства интерфейса узла сети).| |searchByAny|boolean|Если установлено в `true`, возвращать результаты, которые соответствуют любому из критериев, заданных в параметре `filter` или `search`, а не всем сразу.

По умолчанию: `false`.| |searchWildcardsEnabled|boolean|Если установлено в `true`, позволяет использовать `*` в качестве символа подстановки в параметре `search`.

По умолчанию: `false`.| |sortfield|string/array|Сортировать результат по заданным свойствам. Список свойств, которые можно использовать для сортировки, см. в описании конкретного метода API `get`. Макросы перед сортировкой не раскрываются.

Если значение не указано, данные будут возвращены без сортировки.| |sortorder|string/array|Порядок сортировки. Если передан массив, каждое значение будет сопоставлено соответствующему свойству, указанному в параметре `sortfield`.

Возможные значения:
`ASC` - *(по умолчанию)* по возрастанию;
`DESC` - по убыванию.| |startSearch|boolean|Параметр `search` будет сравнивать начало полей, то есть вместо этого выполнять поиск `LIKE "…%"`.

Игнорируется, если `searchWildcardsEnabled` установлено в `true`.| [comment]: # ({/da9957c2-b4e0f5ab}) [comment]: # ({1f52febe-4a0aeab6}) ### Флаги происхождения сущности Методы получения возвращают свойство `flags` для сущностей, связанных с низкоуровневым обнаружением (правило LLD/прототип правила LLD, элемент данных/прототип элемента данных и т. д.). Это свойство полезно для определения того, была ли сущность обнаружена, поскольку редактирование обнаруженных сущностей ограничено. Свойство `flags` возвращает результат на основе комбинации ("+" операция) следующих значений: |Value|Description| |--|--------| |0|Базовая сущность (элемент данных, триггер, график, узел сети)| |1|Правило низкоуровневого обнаружения| |2|Любой прототип (прототип элемента данных, прототип триггера, прототип правила LLD и т. д.)| |4|Обнаруженная сущность (обнаруженный элемент данных, триггер, график, узел сети, правило LLD)| **Комбинированное** значение, возвращаемое свойством `flags`, может быть следующим: |Value|Combination of|Description| |--|--|------| |**0**|0|Обычная сущность (элемент данных, триггер, график, узел сети).| |**2**|2|Прототип сущности (прототип элемента данных, прототип триггера и т. д.).| |**6**|2+4|Обнаруженный элемент данных, триггер, график, узел сети (преобразованный из прототипа).| |**1**|1|Правило низкоуровневого обнаружения.| |**3**|1+2|Прототип правила низкоуровневого обнаружения.| |**5**|1+4|Обнаруженное правило низкоуровневого обнаружения (преобразованное из прототипа).| |**7**|1+2+4|Обнаруженный прототип правила низкоуровневого обнаружения.| [comment]: # ({/1f52febe-4a0aeab6}) [comment]: # ({b41637d2-b41637d2}) ### Примеры [comment]: # ({/b41637d2-b41637d2}) [comment]: # ({7f8a25ac-7a121fac}) #### Проверка прав пользователя Имеет ли пользователь разрешение на запись на хосты, имена которых начинаются с "MySQL" или "Linux"? [Запрос](/manual/api#performing-requests): ```json { "jsonrpc": "2.0", "method": "host.get", "params": { "countOutput": true, "search": { "host": ["MySQL", "Linux"] }, "editable": true, "startSearch": true, "searchByAny": true }, "id": 1 } ``` Ответ: ```json { "jsonrpc": "2.0", "result": "0", "id": 1 } ``` ::: noteclassic Нулевой результат означает отсутствие хостов с разрешениями на чтение/запись. ::: [comment]: # ({/7f8a25ac-7a121fac}) [comment]: # ({b814e950-ea3cccd8}) #### Подсчет несоответствий Подсчитать количество хостов, имена которых не содержат подстроку "ubuntu" [Запрос](/manual/api#performing-requests): ```json { "jsonrpc": "2.0", "method": "host.get", "params": { "countOutput": true, "search": { "host": "ubuntu" }, "excludeSearch": true }, "id": 1 } ``` Ответ: ```json { "jsonrpc": "2.0", "result": "44", "id": 1 } ``` [comment]: # ({/b814e950-ea3cccd8}) [comment]: # ({a325f949-e911c08b}) #### Поиск хостов по подстановочным знакам Найти хосты, имя которых содержит слово «server» и имеют интерфейсные порты «10050» или «10071». Отсортировать результат по имени хоста в порядке убывания и ограничьте его до 5 хостов. [Запрос](/manual/api#performing-requests): ```json { "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 } ``` Ответ: ```json { "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 } ``` [comment]: # ({/a325f949-e911c08b}) [comment]: # ({8c8fa5f6-8ce6f554}) #### Поиск хостов с использованием подстановочных знаков с «preservekeys» Если к предыдущему запросу добавить параметр «preservekeys», то результат возвращается в виде ассоциативного массива, где ключами являются id объектов. [Запрос](/manual/api#performing-requests): ```json { "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 } ``` Ответ: ```json { "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 } ``` [comment]: # ({/8c8fa5f6-8ce6f554})