API

Zabbix v7.4번역일: 2026-09-09원본 보기

개요

Zabbix API를 사용하면 Zabbix의 설정을 프로그래밍 방식으로 조회하고 수정할 수 있으며, 과거 데이터에도 접근할 수 있습니다. 다음과 같은 용도로 널리 사용됩니다:

  • Zabbix와 연동하는 새로운 애플리케이션 개발.
  • Zabbix를 타사 소프트웨어에 통합.
  • 반복 작업 자동화.

Zabbix API는 HTTP 기반 API이며, 웹 프론트엔드의 일부로 제공됩니다. JSON-RPC 2.0 프로토콜을 사용하는데, 이는 다음 두 가지를 의미합니다:

  • API는 여러 개의 개별 메서드로 구성됩니다.
  • 클라이언트와 API 간의 요청과 응답은 JSON 형식으로 인코딩됩니다.

프로토콜과 JSON에 대한 자세한 내용은 JSON-RPC 2.0 명세와 JSON 형식 홈페이지를 참고하세요.

Python 애플리케이션에 Zabbix 기능을 통합하는 방법에 대한 자세한 내용은 Python library for Zabbix를 참고하세요.

Zabbix에서 설정 데이터와 과거 데이터를 포함한 사용자 접근 권한은 사용자 유형, 할당된 사용자 역할, 사용자 그룹에 따라 결정됩니다.

구조

API는 명목상 개별 API들로 그룹화된 여러 메서드로 구성됩니다. 각 메서드는 한 가지 특정 작업을 수행합니다. 예를 들어 host.create 메서드는 host API에 속하며 새 호스트를 생성하는 데 사용됩니다. 역사적으로 API는 종종 "클래스"라고 불리기도 했습니다.

대부분의 API는 데이터를 조회, 생성, 수정, 삭제하기 위한 get, create, update, delete 메서드를 최소한 네 개 포함하지만, 일부 API는 완전히 다른 메서드 집합을 제공하기도 합니다.

요청 수행

프론트엔드를 설정했다면, 원격 HTTP 요청을 사용하여 API를 호출할 수 있습니다. 이를 위해서는 프론트엔드 디렉토리에 있는 api_jsonrpc.php 파일로 HTTP POST 요청을 보내야 합니다.
예를 들어 Zabbix 프론트엔드가 https://example.com/zabbix에 설치되어 있다면, apiinfo.version 메서드를 호출하는 HTTP 요청은 다음과 같은 형태가 됩니다:

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

요청에는 Content-Type 헤더가 application/json-rpc, application/json, application/jsonrequest 중 하나로 설정되어 있어야 합니다.

요청 객체는 다음 속성을 포함해야 합니다:

  • jsonrpc - API에서 사용하는 JSON-RPC 프로토콜 버전(Zabbix API는 JSON-RPC 버전 2.0을 구현합니다);
  • method - 호출할 API 메서드;
  • params - API 메서드에 전달할 파라미터;
  • id - 요청을 식별하는 임의의 값(생략하면 API는 해당 요청을 알림(notification)으로 처리합니다).

요청이 올바르면, API가 반환하는 응답은 다음과 같은 형태가 됩니다:

{
    "jsonrpc": "2.0",
    "result": "7.4.0",
    "id": 1
}

응답 객체는 다음 속성을 포함합니다:

  • jsonrpc - JSON-RPC 프로토콜 버전;
  • result - 메서드가 반환한 데이터;
  • id - 해당 요청의 식별자.

인증

Zabbix의 데이터에 접근하려면 다음 중 하나가 필요합니다:

  • Zabbix 프론트엔드의 Users > API tokens 섹션에서 생성했거나 Token API로 생성한 기존 API 토큰 사용.
  • user.login 메서드로 얻은 인증 토큰 사용.

예를 들어 표준 Admin 사용자로 로그인하여 새 인증 토큰을 얻으려면 JSON 요청은 다음과 같은 형태가 됩니다:

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

자격 증명을 올바르게 제공했다면, API가 반환하는 응답에는 사용자 인증 토큰이 포함됩니다:

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

인증 방법

"Authorization" 헤더 사용

모든 API 요청에는 인증 토큰 또는 API 토큰이 필요합니다. 요청의 Authorization 헤더를 통해 자격 증명을 제공할 수 있습니다:

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

인증 관련 문제가 발생하는 경우 Authorization header forwarding을 참고하세요.

Zabbix API는 헤더 이름의 대소문자를 구분하지 않습니다(예: authorization, Authorization, AUTHORIZATION은 모두 동일하게 처리됩니다).

Authorization 헤더는 크로스 오리진 요청(CORS)에서도 지원됩니다.

"zbx_session" 쿠키는 (모듈이나 사용자 정의 위젯의) JavaScript를 통해 Zabbix UI에서 수행되는 API 요청을 인증하는 데 사용됩니다.

예제 워크플로

다음 섹션에서는 몇 가지 사용 예시를 더 자세히 살펴봅니다.

호스트 조회

이제 Zabbix의 데이터에 접근하는 데 사용할 수 있는 유효한 사용자 인증 토큰이 있습니다(아래 예제에서는 변수로 표현됩니다). 예를 들어 host.get 메서드를 사용하여 설정된 모든 호스트의 ID, 호스트 이름, 인터페이스를 조회할 수 있습니다:

요청:

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

data.json은 JSON 쿼리를 담은 파일입니다. 파일 대신 --data 인자에 직접 쿼리를 전달할 수도 있습니다.

data.json

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

응답 객체에는 요청한 호스트 데이터가 포함됩니다:

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

성능을 위해 조회하려는 객체 속성을 항상 명시적으로 나열하는 것이 권장됩니다. 이렇게 하면 모든 속성을 불필요하게 조회하는 것을 피할 수 있습니다.

새 아이템 생성

이제 이전 host.get 요청에서 얻은 데이터를 사용하여 호스트 "Zabbix server"에 새 아이템을 생성합니다. 이는 item.create 메서드로 수행할 수 있습니다:

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

성공한 응답에는 새로 생성된 아이템의 ID가 포함되며, 이후 요청에서 해당 아이템을 참조하는 데 사용할 수 있습니다:

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

item.create 메서드를 비롯한 다른 create 메서드들도 객체 배열을 받아 한 번의 API 호출로 여러 아이템을 생성할 수 있습니다.

여러 트리거 생성

이처럼 create 메서드가 배열을 받을 수 있으므로, 다음 예시와 같이 여러 트리거를 추가할 수 있습니다:

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":"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"}],"id":4}'

성공한 응답에는 새로 생성된 트리거의 ID가 포함됩니다:

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

아이템 수정

상태를 0으로 설정하여 아이템을 활성화합니다:

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

성공한 응답에는 수정된 아이템의 ID가 포함됩니다:

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

item.update 메서드를 비롯한 다른 update 메서드들도 객체 배열을 받아 한 번의 API 호출로 여러 아이템을 수정할 수 있습니다.

여러 트리거 수정

상태를 0으로 설정하여 여러 트리거를 활성화합니다:

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

성공한 응답에는 수정된 트리거의 ID가 포함됩니다:

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

이 방법이 권장되는 수정 방식입니다. host.massupdate와 같은 일부 API 메서드는 더 단순한 코드를 작성할 수 있게 해줍니다. 하지만 이러한 메서드들은 향후 릴리스에서 제거될 예정이므로 사용을 권장하지 않습니다.

오류 처리

지금까지는 모든 것이 정상적으로 작동했습니다. 하지만 API에 잘못된 호출을 시도하면 어떻게 될까요? 필수 파라미터인 groups를 생략한 채 host.create를 호출하여 다른 호스트를 생성해 보겠습니다:

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

그러면 응답에는 오류 메시지가 포함됩니다:

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

오류가 발생하면 응답 객체는 result 속성 대신 다음 데이터를 포함한 error 속성을 갖게 됩니다:

  • code - 오류 코드;
  • message - 간단한 오류 요약;
  • data - 더 자세한 오류 메시지.

잘못된 입력 값 사용, 세션 타임아웃, 존재하지 않는 객체 접근 시도 등 다양한 상황에서 오류가 발생할 수 있습니다. 애플리케이션은 이러한 오류를 우아하게 처리할 수 있어야 합니다.

API 버전

API 버전 관리를 단순화하기 위해 Zabbix 2.0.4부터 API 버전은 Zabbix 자체의 버전과 일치합니다. apiinfo.version 메서드를 사용하여 현재 사용 중인 API 버전을 확인할 수 있습니다. 이는 애플리케이션을 버전별 기능에 맞게 조정할 때 유용합니다.

Zabbix는 메이저 버전 내에서 기능의 하위 호환성을 보장합니다. 메이저 릴리스 간에 하위 호환성이 깨지는 변경이 이루어질 경우, Zabbix는 보통 다음 릴리스에서 기존 기능을 폐기 예정(deprecated)으로 남겨두고, 그다음 릴리스에서야 완전히 제거합니다. 간혹 Zabbix가 하위 호환성을 제공하지 않고 메이저 릴리스 사이에 기능을 제거하는 경우도 있습니다. 따라서 폐기 예정 기능에 절대 의존하지 말고 가능한 한 빨리 새로운 대안으로 마이그레이션하는 것이 중요합니다.

API changelog에서 API에 적용된 모든 변경 사항을 확인할 수 있습니다.

추가 자료

이제 Zabbix API 작업을 시작하는 데 필요한 충분한 지식을 갖추었지만, 여기서 멈추지 마세요. 더 자세히 알아보려면 사용 가능한 API 목록을 살펴보시기 바랍니다.