[comment]: # ({7cef99ec-92f30379})
# 20 API

[comment]: # ({/7cef99ec-92f30379})

[comment]: # ({d9e959c3-13405b49})
### Pārskats

Zabbix API ļauj programmatiski izgūt un mainī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šo pušu programmatūrā;
-   automatizētu ikdienas uzdevumus.

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ā](http://www.jsonrpc.org/specification) un [JSON formāta mājaslapā](http://json.org/).

Plašāku informāciju par Zabbix funkcionalitātes integrēšanu jūsu Python lietojumprogrammās skatiet [Python bibliotēka Zabbix](/devel/python).

::: noteclassic
Lietotāja piekļuve Zabbix, tostarp gan konfigurācijai, gan vēsturiskajiem datiem, ir atkarīga no [lietotāja tipa](/manual/config/users_and_usergroups/permissions#user-types), piešķirtās [lietotāja lomas](/manual/config/users_and_usergroups/permissions#user-roles) un [lietotāju grupām](/manual/config/users_and_usergroups/usergroup).
:::

[comment]: # ({/d9e959c3-13405b49})

[comment]: # ({76e2a1dd-9cb56d09})
### 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".

::: notetip
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.
:::

[comment]: # ({/76e2a1dd-9cb56d09})

[comment]: # ({d3a7ab69-9cb2f5ca})
### 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:

```bash
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` - JSON-RPC protokola versija, ko izmanto API (Zabbix API ievieš JSON-RPC 2.0 versiju);
-   `method` - API metode, kas tiek izsaukta;
-   `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](https://www.jsonrpc.org/specification#notification)).

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

```json
{
    "jsonrpc": "2.0",
    "result": "7.4.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.

[comment]: # ({/d3a7ab69-9cb2f5ca})

[comment]: # ({c36376e5-ec5a9f60})
### Darbplūsmas piemērs

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

[comment]: # ({/c36376e5-ec5a9f60})

[comment]: # ({17ec6118-ef3f5841})
#### Autentifikācija

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

-   izmantot esošu [API tokenu](/manual/web_interface/frontend_sections/users/api_tokens) (izveidotu Zabbix lietotāja saskarnē vai izmantojot [Token API](/manual/api/reference/token));
-   izmantot autentifikācijas tokenu, kas iegūts ar [user.login](/manual/api/reference/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:

```bash
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:

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

[comment]: # ({/17ec6118-ef3f5841})

[comment]: # ({d920bab8-37011a71})
#### Autorizācijas metodes

[comment]: # ({/d920bab8-37011a71})

[comment]: # ({78bcb6bc-130188f5})
##### 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:

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

::: noteimportant
Ja rodas autentifikācijas problēmas, skatiet [Authorization header forwarding](/manual/installation/known_issues#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](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)).

[comment]: # ({/78bcb6bc-130188f5})

[comment]: # ({8a583b03-8950965e})
##### 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).

[comment]: # ({/8a583b03-8950965e})

[comment]: # ({7f924528-f572ecc2})
#### 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](/manual/api/reference/host/get), lai izgūtu visu konfigurēto [hostu](/manual/api/reference/host/object) ID, hostu nosaukumus un saskarnes:

Pieprasījums:

```bash
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
```

::: notetip
`data.json` ir fails, kas satur JSON vaicājumu. Faila vietā varat nodot vaicājumu argumentā `--data`.
:::

data.json

```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:

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

::: notetip
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.
:::

[comment]: # ({/7f924528-f572ecc2})

[comment]: # ({c9fda4ae-ee2c324f})
#### Jauna vienuma izveide

Tagad izveidojiet jaunu [vienumu](/manual/api/reference/item/object) hostā "Zabbix
serveris", izmantojot datus, ko ieguvāt iepriekšējā `host.get`
pieprasījumā. To var izdarīt, izmantojot
[item.create](/manual/api/reference/item/create) metodi:

```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":"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:

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

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

[comment]: # ({/c9fda4ae-ee2c324f})

[comment]: # ({49a2cbe1-5ed44978})
#### Vairāku trigeru izveide

Tādējādi, ja *izveides metodes* pieņem masīvus, varat pievienot vairākus
[trigerus](/manual/api/reference/trigger/object), piemēram, šos:


```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":"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:

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

[comment]: # ({/49a2cbe1-5ed44978})

[comment]: # ({07f914b6-aa174634})
#### Vienuma atjaunināšana

Iespējojiet vienumu, iestatot tā statusu uz "0":

```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":"item.update","params":{"itemid":"10092","status":0},"id":5}'
```

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

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

::: notetip
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.
:::

[comment]: # ({/07f914b6-aa174634})

[comment]: # ({bfbd84bd-e217b4a2})
#### Vairāku trigeru atjaunināšana

Iespējojiet vairākus trigerus, iestatot to statusu uz "0":

```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.update","params":[{"triggerid":"13938","status":0},{"triggerid":"13939","status":0}],"id":6}'
```

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

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

::: notetip
Šī ir ieteicamā atjaunināšanas metode. Dažas API metodes, piemēram, `host.massupdate`, ļauj rakstīt vienkāršāku kodu.
Tomēr nav ieteicams izmantot šīs metodes, jo tās tiks noņemtas nākamajos laidienos.
:::

[comment]: # ({/bfbd84bd-e217b4a2})

[comment]: # ({a9952ff9-7665e280})
#### 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](/manual/api/reference/host/create), bet izlaižot
obligāto parametru `groups`:

```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":"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:

```json
{
    "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.

[comment]: # ({/a9952ff9-7665e280})

[comment]: # ({0de672ce-c1074d48})
### 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](/manual/api/reference/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.

::: notetip
Visām API veiktajām izmaiņām varat sekot
[API izmaiņu žurnālā](/manual/api/changes).
:::

[comment]: # ({/0de672ce-c1074d48})

[comment]: # ({77690bd2-dfd7315f})
### 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](/manual/api/reference).

[comment]: # ({/77690bd2-dfd7315f})