Tìm hiểu về zabbix (phần 4)

Trong bài này, chúng ta sẽ tìm hiểu qua về API trên zabbix.

1. Tổng quan

Zabbix API cho phép bạn lập trình để truy xuất và thay đổi cấu hình của zabbix, cung cấp quyền truy cập vào dữ liệu lịch sử của nó. API được sử dụng rộng rãi để:

• Tạo các ứng dụng mới để làm việc với zabbix
• Tích hợp zabbix với phần mềm thứ ba
• Tự động hóa các nhiệm vụ

Zabbix API là một trang web dựa trên API và được vận chuyển như là frontend của web. Nó sử dụng giao thúc JSON-RPC 2.0. Điều này có 2 ý nghĩa:

• Các API bao gồm một tập hợp các phương pháp riêng biệt
• Các yêu cầu và trả lời giữa client và API được mã hóa bằng cách sử dụng JSON.

2. Cấu trúc

Các API bao gồm một số phương pháp được nhóm lại thành các API riêng biệt. Mỗi phương thức thực hiện một nhiệm vụ cụ thể. Ví dụ phương thức: host.create phụ thuộc vào host API và sử dụng để tạo những hosts mới. Các API thỉnh thoảng được gọi là class.

3. Thực thi các request

Một khi bạn đã thiết lập frontend, bạn có thể sử dụng các request HTTP từ xa để gọi đến các API. Để làm được điều đó, bạn cần phải gửi request HTTP POST tới các tập tin api_jsonrpc.php đặt trong thư mục frontend. Ví dụ: nếu zabbix frontend của bạn cài đặt dưới http://yourdomain/zabbix, các HTTP request sẽ gọi tới phương thức apiinfo.version:

POST http://yourdomain/zabbix/api_jsonrpc.php HTTP/1.1 Content-Type: application/json-rpc

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

Request buộc phải có Content-Type header được set bởi 1 trong số các giá trị sau: application/json-rpc, application/json, application/jsonrequest

4. Ví dụ

4.1 Authentication

Trước khi bạn truy cập bất kỳ dữ liệu nào của Zabbix, bạn cần đăng nhập và sẽ có 1 mã xác thực. Điều này có thể được thực hiện bằng phương thức user.login. Chúng ta ví dụ rằng bạn muốn đăng nhập với user Admin. Request JSON của bạn sẽ là:

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

Có các thuộc tính:

• jsonrpc: version của JSON-RPC được sử dụng bởi API
• method: phương thức được API gọi
• params: tham số truyền cho phương thức API
• id: một định danh tùy biến
• auth: một mã xác thực người dùng. vì không có lịch sử nào nên được thiết lập là null.

Nếu thiết lập thông tin chính xác, các phản hồi từ API chứa mã xác thực như sau:

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

Trong đó:

• result: kết quả trả về bởi phương thức
• id: định danh

4.2 Retrieving hosts

Bây giờ ta đã có mã xác thwucj người dùng hợp lệ được truy phép dữ liệu của zabbix. Ta sử dụng phương thức host.get để lấy IDs, hostname và interface của các host được cấu hình:

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

Dữ liệu trả về của host:

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

4.3 Tạo mới 1 item

Để tạo mới item trên zabbix server, sử dụng dữ liệu chúng ta thu thập được từ request host.get trước. Nó được sử dụng bởi phương thức item.create

{
"jsonrpc": "2.0",
"method": "item.create",
"params": {
    "name": "Free disk space on $1",
    "key_": "vfs.fs.size[/home/joe/,free]",
    "hostid": "10084",
    "type": 0,
    "value_type": 3,
    "interfaceid": "1",
    "delay": 30
},
"auth": "0424bd59b807674191e7d77572075f33",
"id": 3
}

Phản hồi thành công sẽ chứa ID của mục item mới:

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

4.4 Xử lý lỗi

Nếu chúng ta cố gắng gọi lỗi tới API bằng cách tạo một request host.create nhưng bỏ qua tham số groups

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

Kết quả sẽ chứa lỗi trong message:

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

Nếu có lỗi xảy ra. thay vì kết quả result bình thường, object sẽ chứa error:

• code: mã lỗi
• message: bản tóm tắt lỗi
• data: một thông báo lỗi chi tiết

Lỗi có thể xảy ra trong nhiều trường hợp khác nhau như gán các giá trị đầu vào không đúng hoặc một session timeout, hay cố gắng truy cập các object không tồn tại.

Kể từ zabbix 2.0.4, các version của API đều phù hợp với phiên bản của zabbix. Bạn có thể sử dụng phương thức appiinfo.version để xem version của API bạn đang làm việc. Điều này rất hữu ích cho bạn điều chỉnh ứng dụng để dùng các tính năng phù hợp với phiên bản cụ thể.