Zabbix API 6.0

Zabbix API

all our microphones are muted

ask your questions in Q&A, not in the Chat

use Chat for discussion, networking or applause

Webinar

Introduction

Tasks

A datacenter was built a month ago and you need to add all new devices to Zabbix.

In order to increase the availability of business critical systems, you need to integrate Zabbix with an Incident

Management System.

The manager asked to send a report on the availability of key systems every day at 8 am.

In order to minimize manual work, you decided to create maintenance modes for network hosts automatically.

You need to compare the Host list in some CMDB and the Host list in Zabbix DB.

You need to create thousands hosts and items in Zabbix.

You need to fix $ 1 in all templates.

….. And more.

ZABBIX API

Solution

ZABBIX comes with an API that provides access to almost all

functions available in Zabbix.

Existence of a Zabbix API opens up a lot of opportunities for even

greater efficiency in monitoring:

easy two-way integration: set up a two-way integration with

popular issue-tracking systems;

third party software: integrate Zabbix with third party software

like automation and graphing tools, notification and ticketing

systems, configuration management, etc.

configuration management: integrate configuration management

systems with Zabbix API to add, remove or upgrade hardware or

software easily;

data retrieval: re-use information about organization’s

environment in other applications;

mobile applications: create new applications to work with Zabbix.

ZABBIX API

What is Zabbix API?

ZABBIX API

What is Zabbix API?

Interface is based on web server

Uses JSON RPC v2.0 specification:

API consists of a set of separate methods

requests and responses are encoded using JSON

Examples:

host.create - creates a new host

history.get - retrieves history data

item.update - updates existing items

ZABBIX API

What is Zabbix API?

More than 230 different methods

Each of the methods performs one

specific task

Structure of Zabbix API

ZABBIX API

Zabbix API is made of 3 building blocks: JSON, JSON-RPC and transport (e.g. HTTP)

JSON is a simple format used to send and receive data

JSON-RPC is a remote procedure call protocol encoded in JSON. JSON-RPC builds on top of JSON by adding a

few standard keys to track requests

The transport provides a real-time connection to API. The request/response/error is carried in the body of the

HTTP message. HTTP is a stateless protocol: not persisting sessions between requests

Structure of Zabbix API

ZABBIX API

API request must contain certain properties:

jsonrpc - version of the JSON-RPC protocol (must be 2.0)

method - name of the method to be invoked

params - Object or Array of values to be passed as parameters

id - value used to match the response with the request that it is replying to (must be a number)

auth - user authentication token or null

{

"jsonrpc": "2.0",

"method": "user.login",

"params": {

"username": "Admin",

"password": "zabbix"

"id": 1,

"auth": null

}

ZABBIX API

Structure of Zabbix API

You will get either a response with a result, or an error if the request was unsuccessful

The response object contains the following properties:

jsonrpc - version of the JSON-RPC protocol

result - the data returned by the method

id - identifier of the corresponding request

{

"jsonrpc":"2.0",

"result":"2f2ec4720863281c34cdd3c4c8a5de46",

"id":1

}

ZABBIX API

Structure of Zabbix API

When rpc call encounters an error, the response contains the following properties:

code - number that indicates the error type that occurred

message - string providing a short description of the error

data - value that contains additional information about the error

{

"jsonrpc":"2.0",

"error":{

"code":-32602,

"message":"Invalid params.",

"data":"Invalid parameter \"/\": unexpected parameter \"userr\"."

"id":1

}

ZABBIX API

Structure of Zabbix API

The rpc call error codes:

-32700 - invalid JSON. An error occurred on the server while parsing the JSON text (typo, wrong quotes,

etc.)

-32600 - received JSON is not a valid JSON-RPC Request

-32601 - requested remote-procedure does not exist

-32602 - invalid method parameters

-32603 - Internal JSON-RPC error

-32400 - System error

-32300 - Transport error

-32500 - Application error

How does API work?

INTRODUCTION

How does API work?

API Client API Server

Authentication

INTRODUCTION

How does API work?

API Client API Server

Authentication

ID sessions

INTRODUCTION

How does API work?

API Client API Server

Authentication

ID sessions

Method A

INTRODUCTION

How does API work?

API Client API Server

Authentication

ID sessions

Method A

Result A

INTRODUCTION

How does API work?

API Client API Server

Authentication

ID sessions

Method A

Result A

Method B

Result B

INTRODUCTION

How does API work?

WEB

JSON

API Client

Zabbix API

API Tokens

User based API Tokens

Expiration Time

User and Global managed

Available from 5.4 version

INTRODUCTION

API Tokens and User Role Restrictions

INTRODUCTION

How does API work?

API Client

with API Token:

7ecc990488f71a5a48eeeb1

4b7b281f7c4b1738e2169d41

1efe

API Server

Method A

Result A

Method B

Result B

API connection examples

Zabbix API

Various programming or scripting languages :

Use programming language you are familiar with

Control workflow using built-in operands

Some programming languages have Zabbix API plugins – community based, not supported by Zabbix

ZABBIX API

Zabbix API - Option 1. By using a client

Simple REST Client:

Response:

Zabbix API - Option 2. From command line

ZABBIX API

Request via curl:

$ curl -i -X POST -H 'Content-

Type:application/json' -d'

{"jsonrpc": "2.0",

"method":"user.login",

"params":{

"user":"Admin",

"password":"zabbix"},

"auth": null,"id":0}

' http://127.0.0.1/zabbix/api_jsonrpc.php

HTTP/1.1 200 OK

Date: Wed, 11 Nov 2015 09:32:41 GMT

Server: Apache/2.2.15 (CentOS)

X-Powered-By: PHP/5.3.3

Access-Control-Allow-Origin: *

Access-Control-Allow-Headers: Content-Type

Access-Control-Allow-Methods: POST

Access-Control-Max-Age: 1000

Content-Length: 68

Connection: close

Content-Type: application/json

{"jsonrpc":"2.0",

"result":"2f2ec4720863281c34cdd3c4c8a5de46","id":

Response:

Authentication

Credentials

URL including host,

port and API path

Response including

session ID

Zabbix API - Option 2. From command line

ZABBIX API

$ curl -i -X POST -H 'Content-Type:

application/json' -d '

{"jsonrpc":"2.0",

"method":"host.get",

"params":{

"filter":{

"host":"Zabbix server"

}

"auth":"2f2ec4720863281c34cdd3c4c8a5de46",

"id":1}

' http://127.0.0.1/zabbix/api_jsonrpc.php

{

"jsonrpc":"2.0",

"result":[

{

"hostid":"10126",

"proxy_hostid":"0",

"host":"Zabbix server",

"status":"0",

"disable_until":"0",

...

"name":"Zabbix server",

"flags":"0",

"templateid":"0",

"description":""

}

"id":1

}

Request via curl:

Response:

Filtering - Option 2. From command line

ZABBIX API

Use "filter" to return only those results that exactly match the given filter

Use "output" parameter to query specific object property:

$ curl -X POST -H 'Content-Type:

application/json' -d'

{"jsonrpc":"2.0",

"method":"host.get",

"params":{

"filter":{

"host":"Zabbix server"

"output": "hostid"

"auth":"2f2ec4720863281c34cdd3c4c8a5de46",

"id":1}

' http://192.168.7.105/zabbix/api_jsonrpc.php

{

"jsonrpc":"2.0",

"result":[

{"hostid":"10084"}

"id":1

}

Request via curl:

Response:

Filtering - Option 2. From command line

ZABBIX API

Parameters accept arrays (begins with [ and ends with ]):

$ curl -X POST -H 'Content-Type: application/json' -d'

{"jsonrpc":"2.0",

"method":"host.get",

"params":{

"filter":{

"host": [

"Zabbix server",

"MySQL 01"

]

"output": [

"hostid",

"status"

]

"auth":"2f2ec4720863281c34cdd3c4c8a5de46",

"id":1}

' http://192.168.7.105/zabbix/api_jsonrpc.php

{

"jsonrpc":"2.0",

"result":[

{"hostid":"10084","status":"0"},

{"hostid":"10627","status":"1"}

"id":1

}

Response:

Zabbix API – Option 3. From Python

ZABBIX API

Get auth & host via custom script:

#!/usr/bin/env python

from pyzabbix import ZabbixAPI

zapi = ZabbixAPI("http://127.0.0.1/zabbix")

zapi.login(”Admin", "z@hg*1aD")

result = zapi.host.get(filter={"host" : "Zabbix

server"})

for h in result:

for key in sorted(h):

print "%s: %s " % (key, h[key])

$ ./host_get.py

available: 1

description:

disable_until: 0

error:

errors_from: 0

flags: 0

host: Zabbix server

hostid: 10126

...

snmp_available: 0

snmp_disable_until: 0

snmp_error:

snmp_errors_from: 0

status: 0

templateid: 0

Install PyZabbix Python library using pip:

# yum install python-pip

# pip install pyzabbix

Zabbix API – Option 4. From Powershell

ZABBIX API

For ($i=1; $i -le 1000; $i++) {

$host_str = "TEST_API_" + $i;

$item = "Test_item." + $i;

$JsonItem ='{"jsonrpc": "2.0",

"method": "host.create",

"params": { "host": "' + $host_str +'",

"groups": [ { "groupid": "19" } ] },

"auth": "' + $auth + '",

"id": 1}'

Invoke-RestMethod $ZabbixServer -ContentType "application/json-rpc; charset=utf-8" -Method Post

-Body ([System.Text.Encoding]::UTF8.GetBytes($jsonItem))

Zabbix API – Option 5. From Javascript

ZABBIX API

var request = new HttpRequest(),

auth = "",

params = JSON.parse(value),

fields = {};

//Parse input params

apiToken = params.apiToken;

hostName = params.hostName;

Zabbix_URL = params.URL + "/api_jsonrpc.php";

hostID = params.ID;

json_request = '{ "jsonrpc": "2.0", "method": "hostinterface.get", \

"params": { "hostids":"' + hostId + '", "output": "extend", \

"filter" :{ "main":"1","type":"1"}\

}, "auth": "' + apiToken +'", "id": 1 }';

iface_result = request.post(Zabbix_URL,json_request);

return iface_Result;

Zabbix API

ZABBIX API

{

"jsonrpc":"2.0",

"result":[

{

"hostid":"10084",

"proxy_hostid":"0",

"host":"Zabbix server",

"status":"0",

"available":"1",

...

"name":"Zabbix server",

"flags":"0",

"templateid":"0",

"description":""

}

"id":1

}

Response:

What does "status: 0" or "available: 1" mean?

Use API Documentation:

API features

ZABBIX API

API vs DATABASE

Getting host from a database.

In SQL, it would look like this:

SELECT * FROM hosts WHERE host = 'Zabbix

server'\G

Great, but what should I use? API!

hostid: 10084

proxy_hostid: NULL

host: Zabbix server

status: 0

disable_until: 0

error:

available: 1

errors_from: 0

lastaccess: 0

ipmi_authtype: -1

ipmi_privilege: 2

ipmi_username:

jmx_disable_until: 0

jmx_available: 0

jmx_errors_from: 0

jmx_error:

…

name: Zabbix server

proxy_address:

ZABBIX API

ZABBIX API security

SSL

Password authentication, API Keys

Respects permissions

Audit

ZABBIX API

Zabbix API security

Backward compatibility

Rollback operation in case of

an error

WHY UPGRADE

ZABBIX API Performance

DB performance issues

Heavy requests / huge number of objects

Old Zabbix version

ZABBIX API

Documentation

Full list of API

methods is

available in

ZABBIX

documentation

https://www.zabbix.com/manuals

Questions?

ZABBIX API

Phone:

+420 800 244 442

Web:

https://www.initmax.cz

Email:

[email protected]

LinkedIn:

https://www.linkedin.com/company/initmax

Twitter:

https://twitter.com/initmax

Tomáš Heřmánek:

+420 732 447 184