Zabbix Documentation 2.4

3.04.04.24.4 (current)| In development:5.0 (devel)| Unsupported:1.82.02.22.43.23.4Guidelines

User Tools

Site Tools


manual:api

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
Last revision Both sides next revision
manual:api [2014/09/25 14:23]
sasha Page moved from 2.4:manual:api to manual:api
manual:api [2016/11/24 12:24]
iivs added examples on how to create and update multiple items and triggers
Line 40: Line 40:
 === Authentication === === 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 ''​[[2.4:manual:​api:​reference:​user:​login|user.login]]''​ method. Let us suppose that you want to log in as a standard Zabbix Admin user. Then your JSON request will look like this:+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 ''​[[manual:​api:​reference:​user:​login|user.login]]''​ method. Let us suppose that you want to log in as a standard Zabbix Admin user. Then your JSON request will look like this:
  
 <code js> <code js>
Line 79: Line 79:
 === Retrieving hosts === === 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 ''​[[2.4:manual:​api:​reference:​host:​get|host.get]]''​ method to retrieve the IDs, host names and interfaces of all configured [[2.4:manual:​api:​reference:​host:​object|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 ''​[[manual:​api:​reference:​host:​get|host.get]]''​ method to retrieve the IDs, host names and interfaces of all configured [[manual:​api:​reference:​host:​object|hosts]]:​
  
 <code js> <code js>
Line 126: Line 126:
 === Creating a new item === === Creating a new item ===
  
-Let's create a new [[2.4:manual:​api:​reference:​item:​object|item]] on "​Zabbix server"​ using the data we've obtained from the previous ''​host.get''​ request. This can be done by using the ''​[[2.4:manual:​api:​reference:​item:​create|item.create]]''​ method:+Let's create a new [[manual:​api:​reference:​item:​object|item]] on "​Zabbix server"​ using the data we've obtained from the previous ''​host.get''​ request. This can be done by using the ''​[[manual:​api:​reference:​item:​create|item.create]]''​ method:
  
 <code js> <code js>
Line 161: Line 161:
  
 <note tip>The ''​item.create''​ method as well as other create methods can also accept arrays of objects and create multiple items with one API call.</​note>​ <note tip>The ''​item.create''​ method as well as other create methods can also accept arrays of objects and create multiple items with one API call.</​note>​
 +
 +=== Creating multiple triggers ===
 +
 +So if create methods accept arrays, we can add multiple [[manual:​api:​reference:​trigger:​object|triggers]] like so:
 +
 +<code js>
 +{
 +    "​jsonrpc":​ "​2.0",​
 +    "​method":​ "​trigger.create",​
 +    "​params":​ [
 +        {
 +            "​description":​ "​Processor load is too high on {HOST.NAME}",​
 +            "​expression":​ "​{Linux server:​system.cpu.load[percpu,​avg1].last()}>​5",​
 +        },
 +        {
 +            "​description":​ "Too many processes on {HOST.NAME}",​
 +            "​expression":​ "​{Linux server:​proc.num[].avg(5m)}>​300",​
 +        }
 +    ],
 +    "​auth":​ "​0424bd59b807674191e7d77572075f33",​
 +    "​id":​ 4
 +}
 +</​code>​
 +
 +A successful response will contain the IDs of the newly created triggers:
 +<code js>
 +{
 +    "​jsonrpc":​ "​2.0",​
 +    "​result":​ {
 +        "​triggerids":​ [
 +            "​17369",​
 +            "​17370"​
 +        ]
 +    },
 +    "​id":​ 4
 +}
 +</​code>​
 +
 +=== Updating an item ===
 +
 +Enable an item, that is, set its status to "​0":​
 +
 +<code js>
 +{
 +    "​jsonrpc":​ "​2.0",​
 +    "​method":​ "​item.update",​
 +    "​params":​ {
 +        "​itemid":​ "​10092",​
 +        "​status":​ 0
 +    },
 +    "​auth":​ "​0424bd59b807674191e7d77572075f33",​
 +    "​id":​ 5
 +}
 +</​code>​
 +
 +A successful response will contain the ID of the updated item:
 +<code js>
 +{
 +    "​jsonrpc":​ "​2.0",​
 +    "​result":​ {
 +        "​itemids":​ [
 +            "​10092"​
 +        ]
 +    },
 +    "​id":​ 5
 +}
 +</​code>​
 +
 +<note tip>The ''​item.update''​ method as well as other update methods can also accept arrays of objects and update multiple items with one API call.</​note>​
 +
 +=== Updating multiple triggers ===
 +
 +Enable multiple triggers, that is, set their status to 0:
 +<code js>
 +{
 +    "​jsonrpc":​ "​2.0",​
 +    "​method":​ "​trigger.update",​
 +    "​params":​ [
 +        {
 +            "​triggerid":​ "​13938",​
 +            "​status":​ 0
 +        },
 +        {
 +            "​triggerid":​ "​13939",​
 +            "​status":​ 0
 +        }
 +    ],
 +    "​auth":​ "​0424bd59b807674191e7d77572075f33",​
 +    "​id":​ 6
 +}
 +</​code>​
 +
 +A successful response will contain the IDs of the updated triggers:
 +<code js>
 +{
 +    "​jsonrpc":​ "​2.0",​
 +    "​result":​ {
 +        "​triggerids":​ [
 +            "​13938",​
 +            "​13939"​
 +        ]
 +    },
 +    "​id":​ 6
 +}
 +</​code>​
 +
 +<note tip>This is the preferred method of updating. Some API methods like ''​host.massupdate''​ allow to write more simple code, but it's not recommended to use those methods, since they will be removed in the future releases.</​note>​
 +
 === Error handling === === 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 ''​[[2.4:manual:​api:​reference:​host:​create|host.create]]''​ but omitting the mandatory ''​groups''​ parameter. ​+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 ''​[[manual:​api:​reference:​host:​create|host.create]]''​ but omitting the mandatory ''​groups''​ parameter. ​
  
 <code js> <code js>
Line 182: Line 290:
         ]         ]
     },     },
-    "​id": ​3,+    "​id": ​7,
     "​auth":​ "​0424bd59b807674191e7d77572075f33"​     "​auth":​ "​0424bd59b807674191e7d77572075f33"​
 } }
Line 197: Line 305:
         "​data":​ "No groups for host \"​Linux server\"​."​         "​data":​ "No groups for host \"​Linux server\"​."​
     },     },
-    "​id": ​3+    "​id": ​7
 } }
 </​code>​ </​code>​
Line 210: Line 318:
 ==== API versions ==== ==== API versions ====
  
-To simplify API versioning, starting from Zabbix 2.0.4, the version of the API matches the version of Zabbix itself. You can use the ''​[[2.4:manual:​api:​reference:​apiinfo:​version|apiinfo.version]]''​ method to find out the version of the API you're working with. This can be useful for adjusting your application to use version-specific features.+To simplify API versioning, starting from Zabbix 2.0.4, the version of the API matches the version of Zabbix itself. You can use the ''​[[manual:​api:​reference:​apiinfo:​version|apiinfo.version]]''​ method to find out the version of the API you're working with. This can be useful for adjusting your application to use version-specific features.
  
 We guarantee feature backward compatibility inside of a major version. When making backward incompatible changes between major releases, we usually leave the old features as deprecated in the next release, and only remove them in the release after that. Occasionally,​ we may remove features between major releases without providing any backward compatibility. It is important that you never rely on any deprecated features and migrate to newer alternatives as soon as possible. We guarantee feature backward compatibility inside of a major version. When making backward incompatible changes between major releases, we usually leave the old features as deprecated in the next release, and only remove them in the release after that. Occasionally,​ we may remove features between major releases without providing any backward compatibility. It is important that you never rely on any deprecated features and migrate to newer alternatives as soon as possible.
  
-<note tip>You can follow all of the changes made to the API in the [[2.4:manual:​api:​changes_2.2_-_2.4|API changelog]].</​note>​+<note tip>You can follow all of the changes made to the API in the [[manual:​api:​changes_2.2_-_2.4|API changelog]].</​note>​
 ==== Further reading ==== ==== Further reading ====
  
-You now know enough to start working with the Zabbix API, but don't stop here. For further reading we suggest you have a look at the [[2.4:manual:​api:​reference|list of available APIs]].+You now know enough to start working with the Zabbix API, but don't stop here. For further reading we suggest you have a look at the [[manual:​api:​reference|list of available APIs]].