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 іноді називають "класами".

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

Після налаштування інтерфейсу ви можете використовувати віддалені 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".

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

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

Тепер створіть новий 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
       }
       
       ::: notetip
       Метод `item.create`, як і інші методи *create*, також може приймати масиви об'єктів і створювати декілька елементів одним викликом API.
       :::
       
       
       #### Створення кількох тригерів
       
       Таким чином, якщо *методи створення* приймають масиви, ви можете додати кілька
       [тригерів](/manual/api/reference/trigger/object), наприклад, цей:
       
       
       ```bash
       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
       }

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

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

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

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