Zabbix API ir uz HTTP balstīts API, un tas tiek piegādāts kā daļa no tīmekļa lietotāja saskarnes. Tas izmanto JSON-RPC 2.0 protokolu, kas nozīmē divas lietas:

API sastāv no atsevišķu metožu kopas;
pieprasījumi un atbildes starp klientiem un API tiek kodēti, izmantojot JSON formātu.

Plašāku informāciju par protokolu un JSON skatiet JSON-RPC 2.0 specifikācijā un JSON formāta mājaslapā.

Plašāku informāciju par Zabbix funkcionalitātes integrēšanu jūsu Python lietojumprogrammās skatiet Python bibliotēka Zabbix.

Lietotāja piekļuve Zabbix, tostarp gan konfigurācijai, gan vēsturiskajiem datiem, ir atkarīga no lietotāja tipa, piešķirtās lietotāja lomas un lietotāju grupām.

Struktūra

API sastāv no vairākām metodēm, kas nosacīti ir sagrupētas atsevišķos API. Katra metode veic vienu konkrētu uzdevumu. Piemēram, metode host.create pieder host API un tiek izmantota jaunu hostu izveidei. Vēsturiski API dažkārt tiek dēvēti par "klasēm".

Lielākā daļa API satur vismaz četras metodes: get, create, update un delete, kas paredzētas attiecīgi datu iegūšanai, izveidei, atjaunināšanai un dzēšanai, taču daži API var nodrošināt pilnīgi atšķirīgu metožu kopu.

Pieprasījumu veikšana

Kad esat iestatījis lietotāja saskarne, varat izmantot attālinātus HTTP pieprasījumus, lai izsauktu API. Lai to izdarītu, jums ir jānosūta HTTP POST pieprasījumi uz api_jsonrpc.php failu, kas atrodas lietotāja saskarne direktorijā. Piemēram, ja jūsu Zabbix lietotāja saskarne ir instalēta vietnē https://example.com/zabbix, HTTP pieprasījums apiinfo.version metodes izsaukšanai var izskatīties šādi:

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

Pieprasījumam jābūt ar Content-Type galveni, kurai iestatīta viena no šīm vērtībām: application/json-rpc, application/json vai application/jsonrequest.

Pieprasījuma objektam jāsatur šādas īpašības:

jsonrpc - JSON-RPC protokola versija, ko izmanto API (Zabbix API īsteno JSON-RPC 2.0. versiju);
method - izsauktā API metode;
params - parametri, kas tiks nodoti API metodei;
id - patvaļīgs pieprasījuma identifikators (ja tas ir izlaists, API apstrādā pieprasījumu kā paziņojumu).

Ja pieprasījums ir pareizs, API atgrieztajai atbildei vajadzētu izskatīties šādi:

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

Savukārt atbildes objekts satur šādas īpašības:

jsonrpc - JSON-RPC protokola versija;
result - metodes atgrieztie dati;
id - atbilstošā pieprasījuma identifikators.

Darbplūsmas piemērs

Nākamajā sadaļā jūs iepazīstināsim ar dažiem lietošanas piemēriem sīkāk.

Autentifikācija

Lai piekļūtu jebkādiem datiem Zabbix, jums ir jāizmanto viens no šiem variantiem:

izmantot esošu API tokenu (izveidotu Zabbix lietotāja saskarnē vai izmantojot Token API);
izmantot autentifikācijas tokenu, kas iegūts ar user.login metodi.

Piemēram, ja vēlaties iegūt jaunu autentifikācijas tokenu, piesakoties kā standarta Admin lietotājs, tad JSON pieprasījums izskatītos šādi:

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

Ja norādījāt akreditācijas datus pareizi, API atgrieztajā atbildē jābūt lietotāja autentifikācijas tokenam:

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

Autorizācijas metodes

Ar "Authorization" galveni

Visiem API pieprasījumiem ir nepieciešama autentifikācija vai API marķieris. Jūs varat norādīt akreditācijas datus, izmantojot pieprasījumā galveni Authorization:

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

Ja rodas autentifikācijas problēmas, skatiet Authorization header forwarding.

Zabbix API pieņem galvenes neatkarīgi no burtu reģistra (piemēram, authorization, Authorization un AUTHORIZATION tiek apstrādātas vienādi).

Authorization galvene tiek atbalstīta starpizcelsmes pieprasījumos (CORS).

Ar Zabbix sīkdatni

Sīkdatne "zbx_session" tiek izmantota, lai autorizētu API pieprasījumu no Zabbix lietotāja saskarnes, kas izpildīts, izmantojot JavaScript (no moduļa vai pielāgota logrīka).

Hostu izgūšana

Tagad jums ir derīgs lietotāja autentifikācijas marķieris (attēlots kā mainīgais tālākajos piemēros), ko var izmantot, lai piekļūtu datiem Zabbix. Piemēram, varat izmantot metodi host.get, lai izgūtu visu konfigurēto hostu ID, hostu nosaukumus un saskarnes:

Pieprasījums:

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 ir fails, kas satur JSON vaicājumu. Faila vietā varat nodot vaicājumu argumentā --data.

data.json

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

Atbildes objekts saturēs pieprasītos datus par hostiem:

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

Veiktspējas apsvērumu dēļ vienmēr ir ieteicams norādīt objektu īpašības, kuras vēlaties izgūt. Tādējādi jūs izvairīsieties no visa izgūšanas.

Jauna vienuma izveide

Tagad izveidojiet jaunu vienumu hostā "Zabbix serveris", izmantojot datus, ko ieguvāt iepriekšējā host.get pieprasījumā. To var izdarīt, izmantojot item.create metodi:

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

Veiksmīgā atbildē būs ietverts jaunizveidotā vienuma ID, ko var izmantot, lai atsauktos uz vienumu turpmākajos pieprasījumos:

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

Metode item.create, kā arī citas izveides metodes, var pieņemt arī objektu masīvus un ar vienu API izsaukumu izveidot vairākus vienumus.

Vairāku trigeru izveide

Tādējādi, ja izveides metodes pieņem masīvus, varat pievienot vairākus trigerus, piemēram, šos:

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":"Procesora slodze ir pārāk augsta uz {HOST.NAME}","expression":"last(/Linux server/system.cpu.load[percpu,avg1])>5"},{"description":"Pārāk daudz procesu uz {HOST.NAME}","expression":"avg(/Linux server/proc.num[],5m)>300"}],"id":4}'

Veiksmīgā atbilde saturēs jaunizveidoto trigeru ID:

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

Vienuma atjaunināšana

Iespējojiet vienumu, iestatot tā statusu uz "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}'

Veiksmīgā atbildē būs atjauninātā vienuma ID:

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

Metode item.update, kā arī citas atjaunināšanas metodes, var pieņemt arī objektu masīvus un atjaunināt vairākus vienumus ar vienu API izsaukumu.

Vairāku trigeru atjaunināšana

Iespējojiet vairākus trigerus, iestatot to statusu uz "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}'

Veiksmīgā atbilde saturēs atjaunināto trigeru ID:

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

Kļūdu apstrāde

Līdz šim brīdim viss, ko esat mēģinājis, ir darbojies labi. Bet kas notiktu, ja mēģinātu veikt nepareizu API izsaukumu? Mēģiniet izveidot vēl vienu hostu, izsaucot host.create, bet izlaižot obligāto parametru 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}'

Tad atbildē būs ietverts kļūdas ziņojums:

{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Invalid params.",
        "data": "No groups for host \"Linux server\"."
    },
    "id": 7
}

Ja ir radusies kļūda, tad īpašības result vietā atbildes objekts saturēs īpašību error ar šādiem datiem:

code - kļūdas kods;
message - īss kļūdas kopsavilkums;
data - detalizētāks kļūdas ziņojums.

Kļūdas var rasties dažādos gadījumos, piemēram, izmantojot nepareizas ievades vērtības, sesijas noildzes gadījumā vai mēģinot piekļūt neeksistējošiem objektiem. Jūsu lietojumprogrammai jāspēj korekti apstrādāt šāda veida kļūdas.

API versijas

Lai vienkāršotu API versiju pārvaldību, начиная ar Zabbix 2.0.4, API versija atbilst pašas Zabbix versijai. Varat izmantot apiinfo.version metodi, lai noskaidrotu API versiju, ar kuru strādājat. Tas var būt noderīgi, lai pielāgotu savu lietotni versijai specifisku iespēju izmantošanai.

Zabbix garantē funkcionalitātes atpakaļsaderību vienas galvenās versijas ietvaros. Veicot atpakaļnesaderīgas izmaiņas starp galvenajiem laidieniem, Zabbix parasti atstāj vecās iespējas kā novecojušas nākamajā laidienā un tās noņem tikai vēlākajā laidienā pēc tā. Reizēm Zabbix var noņemt iespējas starp galvenajiem laidieniem, nenodrošinot nekādu atpakaļsaderību. Ir svarīgi nekad nepaļauties uz novecojušām iespējām un pēc iespējas ātrāk pāriet uz jaunākām alternatīvām.

Visām API veiktajām izmaiņām varat sekot API izmaiņu žurnālā.

Papildu lasāmviela

Tagad jums ir pietiekami daudz zināšanu, lai sāktu strādāt ar Zabbix API, tomēr neapstājieties šeit. Tālākai lasīšanai ieteicams apskatīt pieejamo API sarakstu.

What’s next?

1. pielikums. Atsauces komentāri

Docs

18 API

Pārskats