문서

원본 보기

부록 1. 참조 주석

표기법

데이터 타입

Zabbix API는 다음과 같은 데이터 타입을 입력으로 지원합니다:

타입 설명
ID 엔티티를 참조하는 데 사용되는 고유 식별자입니다.
boolean 불린 값입니다(true 또는 false).
flag 전달되고 null과 같지 않으면 true로 간주되는 값이며, 그렇지 않으면 false로 간주됩니다.
integer 정수입니다.
float 부동소수점 숫자입니다.
string 텍스트 문자열입니다.
text 더 긴 텍스트 문자열입니다.
timestamp Unix 타임스탬프입니다.
array 순서가 있는 값들의 시퀀스입니다(일반 배열).
object 연관 배열입니다.
query 반환할 데이터를 정의하는 값입니다. 이 값은 속성 이름들의 배열(특정 속성만 반환)로 정의하거나 다음과 같은 미리 정의된 값 중 하나로 정의할 수 있습니다:
extend - 모든 객체 속성을 반환합니다;
count - 검색된 레코드 수를 반환하며, 특정 서브셀렉트에서만 지원됩니다.

Zabbix API는 항상 문자열이나 배열로만 값을 반환합니다.

속성 동작

일부 객체 속성은 동작을 설명하는 짧은 레이블로 표시됩니다. 다음 레이블이 사용됩니다:

  • read-only - 속성 값은 자동으로 설정되며 특정 조건에서도 사용자가 정의하거나 변경할 수 없습니다 (예: 상속된 객체 또는 발견된 객체의 경우 read-only);
  • write-only - 속성 값을 설정할 수 있지만, 설정 후에는 접근할 수 없습니다;
  • constant - 속성 값은 객체 생성 시에 설정할 수 있지만, 생성 후에는 변경할 수 없습니다;
  • supported - 속성 값을 반드시 설정할 필요는 없지만, 특정 조건에서 설정이 허용됩니다 (예: type이 "Simple check", "External check", "SSH agent", "TELNET agent", 또는 "HTTP agent"로 설정된 경우 supported); 단, supported 속성은 조건에 관계없이 기본값으로 설정될 수 있음을 주의하세요;
  • required - 속성 값은 모든 작업(get 작업 제외) 또는 특정 조건에서 반드시 설정되어야 합니다 (예: 생성 작업에서 required; operationtype이 "global script"로 설정되고 opcommand_hst가 설정되지 않은 경우 required).

업데이트 작업의 경우, 속성은 업데이트 작업 중에 설정할 때 "설정됨"으로 간주됩니다.

레이블로 표시되지 않은 속성은 선택 사항입니다.

매개변수 동작

일부 작업 매개변수는 해당 작업에서의 동작을 설명하는 짧은 라벨로 표시됩니다. 다음 라벨들이 사용됩니다:

  • read-only - 매개변수의 값은 자동으로 설정되며 특정 조건에서도 사용자가 정의하거나 변경할 수 없습니다 (예: 상속된 객체나 발견된 객체의 경우 read-only);
  • write-only - 매개변수의 값은 설정할 수 있지만 이후에는 접근할 수 없습니다;
  • supported - 매개변수의 값은 반드시 설정할 필요는 없지만 특정 조건에서 설정할 수 있습니다 (예: Proxy 객체의 operating_mode가 "passive proxy"로 설정된 경우 supported); 단, supported 매개변수는 조건과 관계없이 기본값으로 설정될 수 있습니다;
  • required - 매개변수의 값은 반드시 설정되어야 합니다.

라벨로 표시되지 않은 매개변수는 선택사항입니다.

예약된 ID 값 "0"

예약된 ID 값 "0"은 요소를 필터링하고 참조된 객체를 제거하는 데 사용할 수 있습니다. 예를 들어, 호스트에서 참조된 프록시를 제거하려면 proxyid를 0으로 설정해야 합니다 ("proxyid": "0"). 또는 서버에서 모니터링되는 호스트를 필터링하려면 proxyids 옵션을 0으로 설정해야 합니다 ("proxyids": "0").

공통 "get" 메서드 매개변수

다음 매개변수는 모든 get 메서드에서 지원됩니다:

매개변수 타입 설명
countOutput boolean 실제 데이터 대신 결과의 레코드 수를 반환합니다.
editable boolean true로 설정하면 사용자가 쓰기 권한을 가진 객체만 반환합니다.

기본값: false.
excludeSearch boolean search 매개변수에 주어진 조건과 일치하지 않는 결과를 반환합니다.
filter object 주어진 필터와 정확히 일치하는 결과만 반환합니다.

키가 속성 이름이고(예: host.get의 Host 객체 속성, item.get의 Item 객체 속성 등), 값이 일치시킬 단일 값 또는 값 배열인 객체를 받습니다.

text 데이터 타입의 속성은 지원하지 않습니다.

일부 메서드는 이 매개변수에 대한 특정 기능을 가지고 있으며, 이는 메서드 페이지에 설명되어 있습니다(예: host.get의 filter 매개변수는 Host 인터페이스 속성도 지원합니다).
limit integer 반환되는 레코드 수를 제한합니다.
output query 반환될 객체 속성.

객체 ID(즉, hostid, itemid 등)는 output 매개변수에 지정되지 않더라도 항상 응답에 포함됩니다.

기본값: extend.
preservekeys boolean 결과 배열에서 ID를 키로 사용합니다.
search object 주어진 패턴과 일치하는 결과를 반환합니다(대소문자 구분 안함).

키가 속성 이름이고(예: host.get의 Host 객체 속성, item.get의 Item 객체 속성 등), 값이 검색할 문자열인 객체를 받습니다. 추가 옵션이 주어지지 않으면 LIKE "%…%" 검색을 수행합니다.

string 및 text 데이터 타입의 속성만 지원합니다.

일부 메서드는 이 매개변수에 대한 특정 기능을 가지고 있으며, 이는 메서드 페이지에 설명되어 있습니다(예: host.get의 search 매개변수는 Host 인터페이스 속성도 지원합니다).
searchByAny boolean true로 설정하면 filter 또는 search 매개변수의 모든 조건이 아닌 임의의 조건과 일치하는 결과를 반환합니다.

기본값: false.
searchWildcardsEnabled boolean true로 설정하면 search 매개변수에서 "*"를 와일드카드 문자로 사용할 수 있습니다.

기본값: false.
sortfield string/array 주어진 속성으로 결과를 정렬합니다. 정렬에 사용할 수 있는 속성 목록은 특정 API get 메서드 설명을 참조하세요. 매크로는 정렬 전에 확장되지 않습니다.

값이 지정되지 않으면 데이터는 정렬되지 않은 상태로 반환됩니다.
sortorder string/array 정렬 순서. 배열이 전달되면 각 값은 sortfield 매개변수에 주어진 해당 속성과 매칭됩니다.

가능한 값:
ASC - (기본값) 오름차순;
DESC - 내림차순.
startSearch boolean search 매개변수가 필드의 시작 부분을 비교하여 LIKE "…%" 검색을 수행합니다.

searchWildcardsEnabled가 true로 설정되면 무시됩니다.

예제

사용자 권한 확인

사용자가 이름이 "MySQL" 또는 "Linux"로 시작하는 호스트에 대한 쓰기 권한을 가지고 있나요?

요청:

{
    "jsonrpc": "2.0",
    "method": "host.get",
    "params": {
        "countOutput": true,
        "search": {
            "host": ["MySQL", "Linux"]
        },
        "editable": true,
        "startSearch": true,
        "searchByAny": true
    },
    "id": 1
}

응답:

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

결과가 0이라는 것은 읽기/쓰기 권한이 있는 호스트가 없다는 의미입니다.

불일치 개수 계산

이름에 "ubuntu" 부분 문자열이 포함되지 않은 호스트의 수를 계산합니다

요청:

{
    "jsonrpc": "2.0",
    "method": "host.get",
    "params": {
        "countOutput": true,
        "search": {
            "host": "ubuntu"
        },
        "excludeSearch": true
    },
    "id": 1
}

응답:

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

와일드카드를 사용한 호스트 검색

이름에 "server"라는 단어가 포함되고 인터페이스 포트가 "10050" 또는 "10071"인 호스트를 찾습니다. 결과를 호스트명으로 내림차순 정렬하고 5개 호스트로 제한합니다.

요청:

{
    "jsonrpc": "2.0",
    "method": "host.get",
    "params": {
        "output": ["hostid", "host"],
        "selectInterfaces": ["port"],
        "filter": {
            "port": ["10050", "10071"]
        },
        "search": {
            "host": "*server*"
        },
        "searchWildcardsEnabled": true,
        "searchByAny": true,
        "sortfield": "host",
        "sortorder": "DESC",
        "limit": 5
    },
    "id": 1
}

응답:

{
    "jsonrpc": "2.0",
    "result": [
        {
            "hostid": "50003",
            "host": "WebServer-Tomcat02",
            "interfaces": [
                {
                    "port": "10071"
                }
            ]
        },
        {
            "hostid": "50005",
            "host": "WebServer-Tomcat01",
            "interfaces": [
                {
                    "port": "10071"
                }
            ]
        },
        {
            "hostid": "50004",
            "host": "WebServer-Nginx",
            "interfaces": [
                {
                    "port": "10071"
                }
            ]
        },
        {
            "hostid": "99032",
            "host": "MySQL server 01",
            "interfaces": [
                {
                    "port": "10050"
                }
            ]
        },
        {
            "hostid": "99061",
            "host": "Linux server 01",
            "interfaces": [
                {
                    "port": "10050"
                }
            ]
        }
    ],
    "id": 1
}

"preservekeys"와 함께 와일드카드를 사용하여 호스트 검색

이전 요청에 "preservekeys" 매개변수를 추가하면, 결과가 연관 배열로 반환되며, 키는 객체의 id가 됩니다.

요청:

{
    "jsonrpc": "2.0",
    "method": "host.get",
    "params": {
        "output": ["hostid", "host"],
        "selectInterfaces": ["port"],
        "filter": {
            "port": ["10050", "10071"]
        },
        "search": {
            "host": "*server*"
        },
        "searchWildcardsEnabled": true,
        "searchByAny": true,
        "sortfield": "host",
        "sortorder": "DESC",
        "limit": 5,
        "preservekeys": true
    },
    "id": 1
}

응답:

{
    "jsonrpc": "2.0",
    "result": {
        "50003": {
            "hostid": "50003",
            "host": "WebServer-Tomcat02",
            "interfaces": [
                {
                    "port": "10071"
                }
            ]
        },
        "50005": {
            "hostid": "50005",
            "host": "WebServer-Tomcat01",
            "interfaces": [
                {
                    "port": "10071"
                }
            ]
        },
        "50004": {
            "hostid": "50004",
            "host": "WebServer-Nginx",
            "interfaces": [
                {
                    "port": "10071"
                }
            ]
        },
        "99032": {
            "hostid": "99032",
            "host": "MySQL server 01",
            "interfaces": [
                {
                    "port": "10050"
                }
            ]
        },
        "99061": {
            "hostid": "99061",
            "host": "Linux server 01",
            "interfaces": [
                {
                    "port": "10050"
                }
            ]
        }
    },
    "id": 1
}