Приложение 1. Справочные комментарии

Обозначение

Типы данных

API Zabbix поддерживает следующие типы данных в качестве входных данных:

Поведение свойства

Некоторые свойства объектов помечены короткими метками, описывающими их поведение. Используются следующие обозначения:

• только для чтения - значение свойства задаётся автоматически и не может быть определено или изменено пользователем, даже в особых случаях (например, только для чтения для наследуемых или обнаруженных объектов);
• только для записи - значение свойства можно установить, но нельзя прочитать после;
• постоянное -значение свойства можно задать при создании объекта, но нельзя изменить позже;
• поддерживаемое - значение свойства не обязательно к установке, но может быть задано при определённых условиях (например, поддерживаемое, если type установлен в "Simple check", "External check", "SSH agent", "TELNET agent" или "HTTP agent"). Однако даже поддерживаемое свойства могут автоматически принимать значения по умолчанию независимо от условий;
• обязательное значение свойства обязательно для указания при всех операциях (кроме get) или при определённых условиях (например, обязательное при создании объекта; обязательное, если operationtype имеет значение "global script", а opcommand_hst не задан).

Свойства, не отмеченные метками, являются необязательными.

Поведение параметров

Некоторые параметры операции помечены короткими метками, описывающими их поведение для операции. Используются следующие метки:

• read-only - значение параметра задается автоматически и не может быть определено или изменено пользователем, даже в некоторых конкретных случаях (например, read-only для унаследованных объектов или обнаруженных объектов);
• write-only - значение параметра можно задать, но после этого к нему нельзя получить доступ;
• supported - значение параметра не требуется задавать, но его можно задать в некоторых конкретных случаях (например, supported, если operating_mode объекта Proxy установлен в "passive proxy"); однако следует отметить, что параметры supported все равно могут быть установлены в значения по умолчанию независимо от условий;
• required - значение параметра обязательно должно быть задано.

Параметры, не помеченные метками, являются необязательными.

Зарезервированное значение ID равное "0"

Зарезервированное значение ID "0" можно использовать для фильтрации элементов и удаления связанных объектов. Например, для удаления ссылки на прокси с узла сети, proxytid необходимо задать значением 0 ("proxyid": "0") или для фильтрации узлов сети наблюдаемых сервером, опция proxyids должна быть задана значением 0 ("proxyids": "0").

Общие параметры метода get

Следующие параметры поддерживаются всеми методами get:

Флаги происхождения сущности

Методы получения возвращают свойство flags для сущностей, связанных с низкоуровневым обнаружением (правило LLD/прототип правила LLD, элемент данных/прототип элемента данных и т. д.). Это свойство полезно для определения того, была ли сущность обнаружена, поскольку редактирование обнаруженных сущностей ограничено.

Свойство flags возвращает результат на основе комбинации ("+" операция) следующих значений:

Комбинированное значение, возвращаемое свойством flags, может быть следующим:

Примеры

Проверка прав пользователя

Имеет ли пользователь разрешение на запись на хосты, имена которых начинаются с "MySQL" или "Linux"?

Запрос:

{
    "jsonrpc": "2.0",
    "method": "host.get",
    "params": {
        "countOutput": true,
        "search": {
            "host": ["MySQL", "Linux"]
        },
        "editable": true,
        "startSearch": true,
        "searchByAny": true
    },
    "id": 1
}

Ответ:

{
    "jsonrpc": "2.0",
    "result": "0",
    "id": 1
}

Подсчет несоответствий

Подсчитать количество хостов, имена которых не содержат подстроку "ubuntu"

Запрос:

{
    "jsonrpc": "2.0",
    "method": "host.get",
    "params": {
        "countOutput": true,
        "search": {
            "host": "ubuntu"
        },
        "excludeSearch": true
    },
    "id": 1
}

Ответ:

{
    "jsonrpc": "2.0",
    "result": "44",
    "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
}