20 API

원본 보기

20 API

개요

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

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

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

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

프로토콜과 JSON에 대한 자세한 정보는 JSON-RPC 2.0 specification과 JSON format homepage를 참조하세요.

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는 요청을 알림으로 처리함).

요청이 올바르다면, 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 호출로 여러 아이템을 생성할 수 있습니다.

여러 트리거 생성

따라서 생성 메서드가 배열을 허용한다면, 여러 개의 트리거를 추가할 수 있습니다. 예를 들어 다음과 같습니다:

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를 잘못 호출하면 어떻게 될까요? 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 자체 버전과 일치합니다. 작업 중인 API 버전을 확인하려면 apiinfo.version 메소드를 사용할 수 있습니다. 이는 버전별 기능을 사용하도록 애플리케이션을 조정하는 데 유용할 수 있습니다.

Zabbix는 주요 버전 내에서 기능의 하위 호환성을 보장합니다. 주요 릴리스 간에 하위 호환되지 않는 변경사항을 만들 때, Zabbix는 보통 다음 릴리스에서 기존 기능을 사용 중단(deprecated)으로 남겨두고, 그 다음 릴리스에서만 제거합니다. 때로는 Zabbix가 하위 호환성을 제공하지 않고 주요 릴리스 간에 기능을 제거할 수 있습니다. 사용 중단된 기능에 절대 의존하지 말고 가능한 한 빨리 새로운 대안으로 마이그레이션하는 것이 중요합니다.

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

추가 자료

이제 Zabbix API로 작업을 시작할 충분한 지식을 갖추셨습니다. 하지만 여기서 멈추지 마세요. 추가 자료로 사용 가능한 API 목록을 살펴보시길 권합니다.

다음 단계는?