부록 1. 참고 해설

원본 보기

부록 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
}

다음 단계는?