20. API

Обзор

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

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

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

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

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

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

Структура

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

Большинство API содержат как минимум четыре метода: get, create, update и delete для получения, создания, обновления и удаления данных соответственно, однако некоторые 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 token, созданный в веб-интерфейсе Zabbix, в разделе Users > API tokens, либо созданный с помощью 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}'

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

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

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

Включите элемент данных, установив для его статуса значение 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
}

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

Включите несколько триггеров, установив для них статус 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}'

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

{
    "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 вы работаете. Это может быть полезно для настройки вашего приложения с учетом функций, зависящих от версии.

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

Дополнительное чтение

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