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 апликације, погледајте [zabbix_utils] (https://github.com/zabbix/python-zabbix-utils) Python апликацију за Zabbix API.

Структура

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 би требало да изгледа овако:

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

Објект одговора, заузврат, садржи следећа својства:

• jsonrpc - верзија JSON-RPC протокола;
• result - подаци враћени методом;
• id - идентификатор одговарајућег захтева.

Пример тока посла

Следећа секција ће вас провести кроз неке примере употребе детаљније.

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

Да бисте приступили било којим подацима у Zabbix-у, морате:

• користите постојећи API токен (направљен у Zabbix корисничком интерфејсу или помоћу API токена);
• користите токен за аутентификацију добијен методом user.login.

На пример, ако желите да добијете нови токен за потврду идентитета тако што ћете се пријавити као стандардним Админ корисником, 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
       }

Методе ауторизације

По заглављу "Овлашћење".

Сви API захтеви захтевају аутентификацију или API токен. Можете да унесете акредитиве користећи заглавље овлашћења у захтеву:

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

Од Zabbix-а 7.2.1, заглавље Authorization је подржано у захтевима из различитих извора (CORS). Од Zabbix-а 7.2.5, Zabbix API прихвата заглавља без разликовања великих и малих слова (нпр., authorization, Authorization и AUTHORIZATION се третирају исто).

Од Zabbix колачића

Колачић "zbx_session" се користи за ауторизацију API захтева са Zabbix корисничког интерфејса који се обавља помоћу JavaScript-а (из модула или прилагођеног виџета).

Преузимање домаћина

Сада имате важећи токен за аутентификацију корисника који се може користити за приступ подаци у Zabbix-у. На пример, можете користити host.get метода за преузимање ID-јева, имена домаћина и интерфејса свих конфигурисаних домаћини:

Захтев:

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 сервер" користећи податке које сте добили од претходног 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":"Слободан простор на диску укључен /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
       }

Ажурирање ставке

Омогућите ставку тако што ћете поставити њен статус на "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}'

Успешан одговор ће садржати 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_TOKEN}' \
            --header 'Тип садржаја: application/json-rpc' \
            --data '{"jsonrpc":"2.0","method":"host.create","params":{"host":"Linux сервер","interfaces":[{"type":1,"main":1,"useip":1,"ip":"192.168.3.1","dns":"","port":"10050"}]},"id":7}

Одговор ће тада садржати грешку порука:

{
            "jsonrpc": "2.0",
            "error": {
            "code": -32602,
            "message": "Неважећи параметри.",
            "data": "Нема група за хост \"Linux сервер\"."
            },
            "id": 7
       }

Ако је дошло до грешке, уместо својства result, објекат responseobject ће садржати својство error са следећим подацима:

• code - код грешке;
• message- кратак резиме грешке;
• data - детаљнија порука о грешци.

Грешке се могу јавити у различитим случајевима, као што су коришћење нетачних улазних вредности, истека времена сесије или покушај приступа непостојећим објектима. Ваша апликација би требало да буде у стању да грациозно обрађује ове врсте грешака.

API верзије

Да би се поједноставило управљање верзијама API-ја, од Zabbix-а 2.0.4, верзијa API-ја одговара верзији самог Zabbix-а. Можете користити apiinfo.version метод за проналажење верзијe API-ја са којом радите. Ово може бити корисно за прилагођавање ваше апликације да користи функције специфичне за верзију.

Zabbix гарантује повратну компатибилност функција унутар главне верзије. Када правите уназад некомпатибилне промене између главних издања, Zabbix обично оставља старе функције као застареле у следећем издању, и уклања их само у издању након тога. Повремено, Zabbix може да уклони функције између главних издања без давања компатибилности уназад. Важно је да се никада не ослањате на застареле карактеристике и пређете на новије алтернативе што је пре могуће.

Даље читање

Сада имате довољно знања да почнете да радите са Zabbix API-јем, али немојте стати овде. За даље читање саветујемо вам да погледате листу доступних API-ја.