20. API

Обзор

Zabbix API позволяет программно получать и изменять конфигурацию Zabbix, а также предоставляет доступ к историческим данным. Она широко используется для:

• создания новых приложений для работы с Zabbix;
• интеграции Zabbix в стороннее программное обеспечение;
• автоматизации рутинных задач.

Zabbix API — это API на основе HTTP, и оно поставляется как часть веб-интерфейса. Оно использует протокол JSON-RPC 2.0, что означает две вещи:

• API состоит из набора отдельных методов;
• запросы и ответы между клиентами и API кодируются с использованием формата JSON.

Дополнительные сведения о протоколе и JSON см. в спецификации JSON-RPC 2.0 и на главной странице формата JSON.

Дополнительные сведения об интеграции функциональности Zabbix в ваши приложения Python см. в библиотеке Python для Zabbix.

Структура

API состоит из ряда методов, которые условно сгруппированы в отдельные API. Каждый метод выполняет одну отдельную задачу. Например, метод host.create относится к API узла сети и используется для создания новых узлов сети. Исторически для API иногда используется название «классы».

Выполнение запросов

После настройки веб-интерфейса вы можете использовать удаленные HTTP-запросы для вызова API. Для этого нужно отправлять HTTP POST-запросы к файлу api_jsonrpc.php, расположенному в каталоге веб-интерфейса. Например, если ваш веб-интерфейс Zabbix установлен в https://example.com/zabbix, HTTP-запрос для вызова метода apiinfo.version может выглядеть так:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"apiinfo.version","params":{},"id":1}'

Запрос должен содержать заголовок Content-Type со значением application/json-rpc, application/json или application/jsonrequest.

Объект запроса должен содержать следующие свойства:

• jsonrpc - версия протокола JSON-RPC, используемая API (Zabbix API реализует версию JSON-RPC 2.0);
• method - вызываемый метод API;
• params - параметры, которые будут переданы методу API;
• id - произвольный идентификатор запроса (если не указан, API рассматривает запрос как уведомление).

Если запрос корректен, ответ, возвращаемый API, должен выглядеть так:

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

Объект ответа, в свою очередь, содержит следующие свойства:

• jsonrpc - версия протокола JSON-RPC;
• result - данные, возвращенные методом;
• id - идентификатор соответствующего запроса.

Пример рабочего процесса

В следующем разделе приведено несколько примеров использования более подробно.

Аутентификация

Для доступа к любым данным в Zabbix необходимо:

• либо использовать существующий токен API (созданный в веб-интерфейсе Zabbix или с помощью Token API);
• либо использовать токен аутентификации, полученный методом user.login.

Например, если вы хотите получить новый токен аутентификации, войдя в систему как стандартный пользователь Admin, запрос JSON будет наподобие следующего:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"user.login","params":{"username":"Admin","password":"zabbix"},"id":1}'

Если вы правильно указали учётные данные, ответ API должен содержать токен аутентификации пользователя:

{
    "jsonrpc": "2.0",
    "result": "0424bd59b807674191e7d77572075f33",
    "id": 1
}

Методы авторизации

Через заголовок "Authorization"

Все запросы к API требуют аутентификации или API-токена. Вы можете передать учетные данные, используя заголовок Authorization в запросе:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer 0424bd59b807674191e7d77572075f33'

API Zabbix принимает заголовки без учета регистра (например, authorization, Authorization и AUTHORIZATION обрабатываются одинаково).

Заголовок Authorization поддерживается в междоменных запросах (CORS).

По cookie-файлам Zabbix

Cookie "zbx_session" используется для авторизации запроса API из веб-интерфейса Zabbix, выполняемого при помощи JavaScript (из модуля или пользовательского виджета).

Получение узлов сети

Теперь у вас есть действительный токен аутентификации пользователя (в примерах ниже он представлен как переменная), который можно использовать для доступа к данным в Zabbix. Например, вы можете использовать метод host.get, чтобы получить идентификаторы, имена узлов сети и интерфейсы всех настроенных узлов сети:

Запрос:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data @data.json

data.json

{
    "jsonrpc": "2.0",
    "method": "host.get",
    "params": {
        "output": [
            "hostid",
            "host"
        ],
        "selectInterfaces": [
            "interfaceid",
            "ip"
        ]
    },
    "id": 2
}

Объект ответа будет содержать запрошенные данные об узлах сети:

{
    "jsonrpc": "2.0",
    "result": [
        {
            "hostid": "10084",
            "host": "Zabbix server",
            "interfaces": [
                {
                    "interfaceid": "1",
                    "ip": "127.0.0.1"
                }
            ]
        }
    ],
    "id": 2
}

Создание нового элемента данных

Создайте новый элемент данных на узле сети «Zabbix server», используя данные, полученные из предыдущего запросаhost.get. Это можно сделать при помощи метода item.create:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"item.create","params":{"name":"Free disk space on /home/joe/","key_":"vfs.fs.size[/home/joe/,free]","hostid":"10084","type":0,"value_type":3,"interfaceid":"1","delay":30},"id":3}'

Успешный ответ будет содержать ID только что созданного элемента данных, который можно использовать для обозначения этого элемента данных в последующих запросах:

{
    "jsonrpc": "2.0",
    "result": {
        "itemids": [
            "24759"
        ]
    },
    "id": 3
}

Создание нескольких триггеров

Соответственно, если методы создания принимают массивы, вы можете добавить несколько триггеров, например:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"trigger.create","params":[{"description":"Processor load is too high on {HOST.NAME}","expression":"last(/Linux server/system.cpu.load[percpu,avg1])>5",},{"description":"Too many processes on {HOST.NAME}","expression":"avg(/Linux server/proc.num[],5m)>300",}],"id":4}'

Успешный ответ будет содержать ID только что созданных триггеров:

{
    "jsonrpc": "2.0",
    "result": {
        "triggerids": [
            "17369",
            "17370"
        ]
    },
    "id": 4
}

Обновление элемента данных

Активируйте элемент данных, указав для «status» значение «0»:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"item.update","params":{"itemid":"10092","status":0},"id":5}'

Успешный ответ будет содержать ID обновлённого элемента данных:

{
    "jsonrpc": "2.0",
    "result": {
        "itemids": [
            "10092"
        ]
    },
    "id": 5
}

Обновление нескольких триггеров

Активируйте несколько триггеров, указав для «status» значение «0»:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"trigger.update","params":[{"triggerid":"13938","status":0},{"triggerid":"13939","status":0}],"id":6}'

Успешный ответ будет содержать ID обновлённых триггеров:

{
    "jsonrpc": "2.0",
    "result": {
        "triggerids": [
            "13938",
            "13939"
        ]
    },
    "id": 6
}

Обработка ошибок

До этого момента всё, что мы пробовали, работало прекрасно. Но что может случиться, если мы попробуем выполнить некорректный запрос к API? Давайте попробуем создать ещё один узел сети при помощи вызова host.create, но не станем указывать обязательный параметр groups:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"host.create","params":{"host":"Linux server","interfaces":[{"type":1,"main":1,"useip":1,"ip":"192.168.3.1","dns":"","port":"10050"}]},"id":7}'

Тогда ответ будет содержать сообщение об ошибке:

{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Invalid params.",
        "data": "No groups for host \"Linux server\"."
    },
    "id": 7
}

Если произошла ошибка, то вместо свойства result, объект ответа будет содержать свойство error со следующими данными:

• code — код ошибки;
• message — короткое описание ошибки;
• data — более подробное сообщение об ошибке.

Ошибки могут возникать в разных ситуациях, таких как некорректные входные значения, превышение времени ожидания сессии или попытка доступа к несуществующим объектам. Ваше приложение должно быть способно корректно обработать такие виды ошибок.

Версии API

Чтобы упростить версионность API, начиная с Zabbix 2.0.4, версия API совпадает с версией самого Zabbix. Вы можете использовать метод apiinfo.version, чтобы узнать версию API, с которой вы работаете. Знание версии может пригодиться для корректировки вашего приложения, чтобы использовать возможности конкретной версии API.

Zabbix гарантирует обратную совместимость в пределах одной мажорной версии. При выполнении несовместимых изменений между мажорными выпусками, Zabbix обычно оставляет старые функции как устаревшие в следующим выпуске, и удаляет их только в выпуске, следующим за этим. Иногда Zabbix может удалить функции между мажорными выпусками без предоставления какой-либо обратной совместимости. Очень важно никогда не полагаться на какие-либо устаревшие функции и мигрировать на новые альтернативы как можно скорее.

Дополнительная литература

Теперь вы знаете достаточно для начала работы с Zabbix API, но не останавливайтесь на данном этапе. Для дальнейшего чтения мы предлагаем вам взглянуть на список доступных API.