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.0.0",
       "id": 1
       }

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

• jsonrpc - верзија ЈСОН-РПЦ протокола;
• 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'

SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

По својству 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}'

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

Успешан одговор ће содржати 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: 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, верзијa API-ја одговара верзији самог Zabbix-а. Можете користити apiinfo.version метод за проналажење верзијe API-ја са којом радите. Ово може бити корисно за прилагођавање ваше апликације да користи функције специфичне за верзију.

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

Даље читање

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