19. API

Áttekintés

A Zabbix API lehetővé teszi, hogy programozottan lekérje és módosítsa a a Zabbix konfigurációját, és hozzáférést biztosít a korábbi adatokhoz. Ez széles körben használják:

• Hozzon létre új alkalmazásokat a Zabbix használatához;
• A Zabbix integrálása harmadik féltől származó szoftverekkel;
• Automatizálja a rutinfeladatokat.

A Zabbix API egy web alapú API, és a web részeként kerül szállításra frontend. A JSON-RPC 2.0 protokollt használja, ami két dolgot jelent:

• Az API különálló metódusokból áll;
• A kliensek és az API közötti kérések és válaszok kódolva vannak JSON formátum használatával.

További információ a protokollról és a JSON-ról a [JSON-RPC 2.0 specifikáció] (http://www.jsonrpc.org/specification) és a [JSON formátumú honlap] (http://json.org/).

Szerkezet

Az API számos metódusból áll, amelyek névlegesen csoportosítva vannak külön API-k. Mindegyik módszer egy meghatározott feladatot hajt végre. Mert Például a "host.create" metódus a host API-hoz tartozik, és használatban van új gazdagépek létrehozásához. A történelem során az API-kat néha úgy emlegették "osztályok".

Kérések végrehajtása

Miután beállította a kezelőfelületet, távoli HTTP-kéréseket használhat hívja az API-t. Ehhez HTTP POST kéréseket kell küldenie a api_jsonrpc.php fájl, amely a frontend könyvtárban található. Például, ha a Zabbix frontend a http://company.com/zabbix alatt van telepítve, az "apiinfo.version" metódus meghívására irányuló HTTP-kérés így nézhet ki ez:

POST http://company.com/zabbix/api_jsonrpc.php HTTP/1.1
       Tartalom típusa: application/json-rpc

       {"jsonrpc":"2.0","method":"apiinfo.version","id":1,"auth":null,"params":{}}

A kérelem „Content-Type” fejlécének ezek valamelyikére kell állítania értékek: application/json-rpc, application/json vagy application/jsonrequest.

Példa munkafolyamat

A következő rész néhány használati példát mutat be részletesebben Részlet.

Authentication

Before you can access any data inside of Zabbix you'll need to log in and obtain an authentication token. This can be done using the user.login method. Let us suppose that you want to log in as a standard Admin user. Then your JSON request will look like this:

{
           "jsonrpc": "2.0",
           "method": "user.login",
           "params": {
               "user": "Admin",
               "password": "zabbix"
           },
           "id": 1,
           "auth": null
       }

Let's take a closer look at the request object. It has the following properties:

• jsonrpc - the version of the JSON-RPC protocol used by the API; the Zabbix API implements JSON-RPC version 2.0;
• method - the API method being called;
• params - parameters that will be passed to the API method;
• id - an arbitrary identifier of the request;
• auth - a user authentication token; since we don't have one yet, it's set to null.

If you provided the credentials correctly, the response returned by the API will contain the user authentication token:

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

The response object in turn contains the following properties:

• jsonrpc - again, the version of the JSON-RPC protocol;
• result - the data returned by the method;
• id - identifier of the corresponding request.

Authorization methods

By "Authorization" header

All API requests require an authentication or an API token. You can provide the credentials by using the "Authorization" request header:

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

By "auth" property

An API request can be authorized by the "auth" property.

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

By Zabbix cookie

A "zbx_session" cookie is used to authorize an API request from Zabbix UI performed using JavaScript (from a module or a custom widget).

Retrieving hosts

We now have a valid user authentication token that can be used to access the data in Zabbix. For example, let's use the host.get method to retrieve the IDs, host names and interfaces of all configured hosts:

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

The response object will contain the requested data about the hosts:

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

Creating a new item

Let's create a new item on "Zabbix server" using the data we've obtained from the previous host.get request. This can be done by using the item.create method:

{
           "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
           },
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 3
       }

A successful response will contain the ID of the newly created item, which can be used to reference the item in the following requests:

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

Creating multiple triggers

So if create methods accept arrays, we can add multiple triggers like so:

{
           "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",
               }
           ],
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 4
       }

A successful response will contain the IDs of the newly created triggers:

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

Updating an item

Enable an item, that is, set its status to "0":

{
           "jsonrpc": "2.0",
           "method": "item.update",
           "params": {
               "itemid": "10092",
               "status": 0
           },
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 5
       }

A successful response will contain the ID of the updated item:

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

Updating multiple triggers

Enable multiple triggers, that is, set their status to 0:

{
           "jsonrpc": "2.0",
           "method": "trigger.update",
           "params": [
               {
                   "triggerid": "13938",
                   "status": 0
               },
               {
                   "triggerid": "13939",
                   "status": 0
               }
           ],
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 6
       }

A successful response will contain the IDs of the updated triggers:

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

Error handling

Up to that point everything we've tried has worked fine. But what happens if we try to make an incorrect call to the API? Let's try to create another host by calling host.create but omitting the mandatory groups parameter.

{
           "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,
           "auth": "0424bd59b807674191e7d77572075f33"
       }

The response will then contain an error message:

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

If an error occurred, instead of the result property, the response object will contain an error property with the following data:

• code - an error code;
• message - a short error summary;
• data - a more detailed error message.

Errors can occur in different cases, such as, using incorrect input values, a session timeout or trying to access unexisting objects. Your application should be able to gracefully handle these kinds of errors.

API-verziók

Az API verziózásának egyszerűsítése érdekében a Zabbix 2.0.4 óta az API verziója megfelel magának a Zabbix verziónak. Használhatja a apiinfo.version módszer a kereséshez ki az API verzióját, amellyel dolgozik. Ez hasznos lehet az alkalmazás beállítása a verzióspecifikus funkciók használatához.

Garantáljuk a funkciók visszafelé kompatibilitását a fő verziókon belül. Amikor visszafelé inkompatibilis változtatásokat hajtunk végre a főbb kiadások között, mi általában a régi funkciókat elavultként hagyják a következő kiadásban, és csak ezután távolítsa el őket a kiadásban. Esetenként eltávolíthatjuk funkciókat a főbb kiadások között anélkül, hogy visszamenőleg biztosítana kompatibilitás. Fontos, hogy soha ne hagyatkozzon semmiféle elavultra funkciókat, és a lehető leghamarabb térjen át újabb alternatívákra.

További irodalom

Most már eleget tud ahhoz, hogy elkezdjen dolgozni a Zabbix API-val, de ne hagyja abba itt. További olvasáshoz javasoljuk, hogy tekintse meg a list of elérhető API-k.