20 API

Pārskats

Zabbix API ļauj programmatiski izgūt un modificēt Zabbix konfigurāciju, kā arī nodrošina piekļuvi vēsturiskajiem datiem. To plaši izmanto, lai:

• Izveidotu jaunas lietojumprogrammas darbam ar Zabbix.
• Integrētu Zabbix trešās puses programmatūrā.
• Automatizētu rutīnas uzdevumus.

Zabbix API ir uz HTTP balstīts API, un tas tiek piegādāts kā daļa no 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.

Papildinformāciju par protokolu un JSON skatiet JSON-RPC 2.0 specifikācijā un JSON formāta sākumlapā.

Papildinformāciju par Zabbix funkcionalitātes integrēšanu jūsu Python lietojumprogrammās skatiet Python bibliotēkā Zabbix.

Struktūra

API sastāv no vairākiem metodēm, kas nomināli ir grupētas atsevišķās API. Katra no metodēm veic vienu konkrētu uzdevumu. Piemēram, host.create metode pieder pie host API un tiek izmantota jaunu hosts izveidei. Vēsturiski API dažkārt tiek dēvētas par "klasēm".

Lielākajā daļā API ir vismaz četras metodes: get, create, update un delete, kas attiecīgi tiek izmantotas datu izgūšanai, izveidei, atjaunināšanai un dzēšanai, taču dažas API var nodrošināt pilnīgi atšķirīgu metožu kopu.

Pieprasījumu veikšana

Kad esat iestatījis lietotāja saskarni, varat izmantot attālinātus HTTP pieprasījumus, lai izsauktu API. Lai to izdarītu, jums jānosūta HTTP POST pieprasījumi uz api_jsonrpc.php failu, kas atrodas lietotāja saskarnes direktorijā.
Piemēram, ja jūsu Zabbix lietotāja saskarne ir instalēta zem https://example.com/zabbix, HTTP pieprasījums, lai izsauktu apiinfo.version metodi, varētu 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, kas iestatīta uz vienu no šīm vērtībām: application/json-rpc, application/json vai application/jsonrequest.

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

• jsonrpc - API izmantotā JSON-RPC protokola versija (Zabbix API ievieš JSON-RPC 2.0 versiju);
• method - izsaucamā API metode;
• params - parametri, kas tiks nodoti API metodei;
• id - patvaļīgs pieprasījuma identifikators (ja tas nav norādīts, API pieprasījumu apstrādā kā paziņojumu).

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

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

Savukārt atbildes objektā ir šādas īpašības:

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

Autentifikācija

Lai piekļūtu jebkuriem datiem Zabbix, jums ir jāizmanto viens no šiem veidiem:

• Izmantojiet esošu API tokenu, kas izveidots Zabbix lietotāja saskarnē, sadaļā Users > API tokens, vai izveidots, izmantojot Token API.
• Izmantojiet autentifikācijas tokenu, kas iegūts ar user.login metodi.

Piemēram, ja jūs vēlētos iegūt jaunu autentifikācijas tokenu, piesakoties kā standarta Admin lietotājs, 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 jūs 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 header

Visi API pieprasījumi prasa autentifikāciju vai API tokenu. Akreditācijas datus varat norādīt, izmantojot Authorization header pieprasījumā:

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

Kopš Zabbix 7.0.7 Authorization header tiek atbalstīts starpizcelsmes pieprasījumos (CORS). Kopš Zabbix 7.0.11 Zabbix API pieņem galvenes, neņemot vērā burtu reģistru (piem., authorization, Authorization un AUTHORIZATION tiek apstrādāti vienādi).

Ar auth īpašību

API pieprasījumu var autorizēt, izmantojot auth īpašību.

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

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).

Piemēra darbplūsma

Nākamā sadaļa detalizētāk iepazīstina ar vairākiem lietošanas piemēriem.

Hosts izgūšana

Tagad jums ir derīgs lietotāja autentifikācijas tokens (turpmākajos piemēros attēlots kā mainīgais), ko var izmantot, lai piekļūtu datiem Zabbix. Piemēram, varat izmantot metodi host.get, lai izgūtu visu konfigurēto hosts 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

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

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

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

Jauna vienuma izveide

Tagad izveidojiet jaunu vienumu hostā "Zabbix server", izmantojot datus, ko ieguvāt no iepriekšējā host.get pieprasījuma. 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īga atbilde saturēs jaunizveidotā vienuma ID, ko var izmantot, lai atsauktos uz vienumu turpmākajos pieprasījumos:

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

Vairāku trigeru izveide

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

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

Veiksmīga 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īga atbilde saturēs atjauninātā vienuma ID:

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

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īga atbilde saturēs atjaunināto trigeru ID:

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

Kļūdu apstrāde

Līdz šim viss, ko jūs mēģinājāt, darbojās pareizi. Bet kas notiktu, ja jūs mēģinātu veikt nepareizu API izsaukumu? Mēģiniet izveidot vēl vienu hostu, izsaucot host.create, bet izlaižot obligāto groups parametru:

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

Atbilde tad saturēs kļūdas ziņojumu:

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

Ja ir notikusi kļūda, atbildes objektā result īpašības vietā būs error īpašība 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 šāda veida kļūdas apstrādāt korekti.

API versijas

Lai vienkāršotu API versiju pārvaldību, kopš Zabbix 2.0.4 API versija sakrīt ar paša Zabbix versiju. Varat izmantot metodi apiinfo.version, lai uzzinātu, ar kuru API versiju strādājat. Tas var būt noderīgi, pielāgojot savu lietojumprogrammu konkrētai versijai raksturīgu funkciju izmantošanai.

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

Papildu lasīšanai

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