19. API

Огляд

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

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

Zabbix API — це API на основі HTTP, який постачається як частина веб-інтерфейсу. Він використовує протокол 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 іноді називають "класами".

Більшість 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, має виглядати так:

{
           "jsonrpc": "2.0",
           "result": "6.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'
За властивістю "auth".

Запит API може бути авторизований за допомогою властивості "auth".

Зауважте, що властивість "auth" застаріла. Її буде видалено в наступних релізах.

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"jsonrpc":"2.0","method":"host.get","params":{"output":["hostid"]},"auth":"0424bd59b807674191e7d77572075f33","id":1}'

Файл 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 – це файл, який містить запит JSON. Замість файлу ви можете передати запит в аргументі --data.

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
       }

З міркувань продуктивності завжди рекомендується перераховувати конкретні властивості об’єкта, які потрібно отримати. Таким чином, ви уникнете отримання одразу всіх властивостей.

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

Тепер створіть новий item на хості "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}'

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

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

Метод item.create, як і інші методи create, також може приймати масиви об'єктів і створювати декілька елементів одним викликом API.

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

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

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}'

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

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

Метод item.update, а також інші методи оновлення також може приймати масиви об’єктів і оновлювати кілька елементів одним викликом API.

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

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

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

До цього моменту все, що ви спробували, працювало нормально. Але що станеться, якщо ви спробуєте зробити некоректний виклик 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 гарантує зворотну сумісність функцій всередині мажорної версії. При внесенні зворотно несумісних змін між мажорними випусками, Zabbix зазвичай залишає старі функції застарілими(deprecated) в наступному випуску, і видаляє їх лише
у подальших випусках. Іноді Zabbix може видаляти можливості між мажорними випусками без забезпечення зворотної сумісності. Важливо, щоб ви ніколи не покладалися на застарілі функції і переходили на новіші альтернативи якомога швидше.

Ви можете стежити за всіма змінами, внесеними до API, у Журналі змін API.

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

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