문서

원본 보기

20 API

개요

Zabbix API를 사용하면 Zabbix 구성을 프로그래밍 방식으로 검색 및 수정할 수 있으며 과거 데이터에 대한 액세스를 제공합니다. 다음과 같은 용도로 널리 사용됩니다:

Zabbix와 함께 작동하는 새로운 애플리케이션 생성;
Zabbix를 타사 소프트웨어에 통합;
일상적인 작업 자동화.

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

API는 별도의 메서드 집합으로 구성됩니다;
클라이언트와 API 간의 요청 및 응답은 JSON 형식을 사용하여 인코딩됩니다.

프로토콜 및 JSON에 대한 자세한 내용은 JSON-RPC 2.0 사양 및 JSON 형식 홈페이지를 참조하세요.

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

구성 및 과거 데이터를 포함한 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는 요청을 알림으로 처리함).

요청이 올바르다면, API에서 반환하는 응답은 다음과 같이 보여야 합니다:

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

응답 객체에는 다음 속성들이 포함됩니다:

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

예제 워크플로

다음 섹션에서는 사용법의 몇 가지 예제를 더 자세히 살펴보겠습니다.

인증

Zabbix의 데이터에 접근하려면 다음 중 하나를 사용해야 합니다:

기존 API 토큰 사용 (Zabbix 프론트엔드에서 생성하거나 Token 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 헤더 전달을 참조하세요.

Zabbix 7.0.7부터 Authorization 헤더가 교차 출처 요청(CORS)에서 지원됩니다. Zabbix 7.0.11부터 Zabbix API는 대소문자를 구분하지 않는 방식으로 헤더를 허용합니다(예: authorization, Authorization, AUTHORIZATION이 동일하게 처리됩니다).

`auth` 속성으로

API 요청은 auth 속성으로 인증할 수 있습니다.

auth 속성은 더 이상 사용되지 않습니다. 향후 릴리스에서 제거될 예정입니다.

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

"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 메서드와 다른 생성 메서드들은 객체 배열도 허용하여 하나의 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 메서드와 다른 업데이트 메서드들은 객체 배열도 받을 수 있어서 하나의 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를 잘못 호출하면 어떻게 될까요? host.create를 호출하여 다른 호스트를 생성해보되, 필수 매개변수인 groups를 생략해보겠습니다:

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는 일반적으로 다음 릴리스에서 기존 기능을 더 이상 사용되지 않는 것으로 남겨두고, 그 다음 릴리스에서만 제거합니다. 때때로 Zabbix는 하위 호환성을 제공하지 않고 주요 릴리스 간에 기능을 제거할 수 있습니다. 더 이상 사용되지 않는 기능에 의존하지 말고 가능한 한 빨리 새로운 대안으로 마이그레이션하는 것이 중요합니다.

API에 대한 모든 변경사항은 API 변경 로그에서 확인할 수 있습니다.

추가 읽을거리

이제 Zabbix API로 작업을 시작할 충분한 지식을 갖게 되었지만, 여기서 멈추지 마세요. 추가 읽을거리로 사용 가능한 API 목록을 살펴보는 것을 권장합니다.

문서