19. API

Огляд

Zabbix API дозволяє програмно отримувати та змінювати налаштування Zabbix і забезпечує доступ до історичних даних. Це є широко використовується для:

• Створення нові програми для роботи з Zabbix;
• Інтегрування Zabbix у стороннє програмне забезпечення;
• Автоматизації рутинних завдань.

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

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

Додаткову інформацію про протокол і JSON можна знайти в [специфікації JSON-RPC 2.0] (http://www.jsonrpc.org/specification) і на домашній сторінці формату JSON.

Щоб дізнатися більше про інтеграцію функцій Zabbix у ваші програми Python, перегляньте zabbix_utils - Python бібліотеку для Zabbix API.

Структура

API складається з кількох методів, номінально згрупованих у окремі API. Кожен із методів виконує одну певну задачу. Наприклад, метод host.create належить до API host і використовується для створення нових хостів. Історично так склалось, що API іноді називають "класами".

Виконання запитів

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

POST http://example.com/zabbix/api_jsonrpc.php HTTP/1.1
       Content-Type: application/json-rpc
       
       {
           "jsonrpc": "2.0",
           "method": "apiinfo.version",
           "id": 1,
           "auth": null,
           "params": {}
       }

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

Приклад робочого процесу

У наступному розділі ми розглянемо деякі приклади використання більш детально.

Автентифікація

Щоб отримати доступ до будь-яких даних у Zabbix, вам потрібно:

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

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

{
           "jsonrpc": "2.0",
           "method": "user.login",
           "params": {
               "username": "Admin",
               "password": "zabbix"
           },
           "id": 1,
           "auth": null
       }

Розглянемо докладніше об'єкт request. Він має наступні властивості:

• jsonrpc - версія протоколу JSON-RPC, що використовується API; Zabbix API реалізує JSON-RPC версії 2.0;
• method - метод API, що викликається;
• params - параметри, які будуть передані методу API;
• id - довільний ідентифікатор запиту;
• auth - токен автентифікації користувача; оскільки у нас його ще немає, він дорівнює нулю.

Якщо ви правильно вказали облікові дані, відповідь, яку поверне API, міститиме токен автентифікації користувача:

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

Об'єкт відповіді в свою чергу містить наступні властивості:

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

Отримання хостів

Тепер у вас є дійсний токен автентифікації користувача, який можна використовувати для доступу до даних у Zabbix. Наприклад, ви можете використовувати методhost.get для отримання ідентифікаторів, імен хостів та інтерфейсів всіх налаштованиххостів:

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

Об'єкт відповіді буде містити запитувані дані про хости:

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

Створення нового елемента

Тепер створіть новий item на хості "Zabbix server", використовуючи дані, які ви отримали з попереднього host.get-запиту. Це можна зробити за допомогою методу item.create:

{
           "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
           },
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 3
       }

Успішна відповідь міститиме ідентифікатор щойно створеного елемента, який можна використовувати для посилання на елемент у таких запитах:

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

Створення кількох тригерів

Таким чином, якщо методи створення приймають масиви, ви можете додати кілька тригерів, наприклад, цей:

{
           "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",
               }
           ],
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 4
       }

Успішна відповідь міститиме ідентифікатори новостворених тригерів:

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

Оновлення елемента даних

Увімкніть елемент, встановивши для нього статус "0":

{
           "jsonrpc": "2.0",
           "method": "item.update",
           "params": {
               "itemid": "10092",
               "status": 0
           },
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 5
       }

Успішна відповідь міститиме ідентифікатор оновленого елемента:

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

Оновлення кількох тригерів

Увімкніть кілька тригерів, встановивши для них статус "0":

{
           "jsonrpc": "2.0",
           "method": "trigger.update",
           "params": [
               {
                   "triggerid": "13938",
                   "status": 0
               },
               {
                   "triggerid": "13939",
                   "status": 0
               }
           ],
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 6
       }

Успішна відповідь міститиме ідентифікатори оновлених тригерів:

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

Обробка помилок

До цього моменту все, що ви спробували, працювало нормально. Але що станеться, якщо ви спробуєте зробити некоректний виклик API? Спробуйте створити інший хост, викликавши host.create, але опустивши обов'язковий параметр groups:

{
           "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,
           "auth": "0424bd59b807674191e7d77572075f33"
       }

Відповідь міститиме повідомлення про помилку:

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

Ми гарантуємо зворотну сумісність функцій всередині мажорної версії. При внесенні зворотно несумісних змін між мажорними випусками, ми зазвичай залишаємо старі функції застарілими(deprecated) в наступному випуску, і видаляємо їх лише
у подальших випусках. Іноді ми можемо видаляти можливості між мажорними випусками без забезпечення зворотної сумісності. Важливо, щоб ви ніколи не покладалися на застарілі функції і переходили на новіші альтернативи якомога швидше.

Більше інформації

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