Documentation
Table of Contents
付録1. 参考文献の解説
表記法
データ型
Zabbix APIは、以下のデータ型を入力としてサポートしています。
| 型 | 説明 |
|---|---|
| ID | エンティティを参照するために使用される一意の識別子。 |
| boolean | ブール値 (trueまたはfalse)。 |
| flag | 渡された値は、nullと等しくない場合にtrueとみなされ、そうでない場合はfalseとみなされます。 |
| integer | 整数。 |
| float | 浮動小数点数。 |
| string | テキスト文字列。 |
| text | より長いテキスト文字列。 |
| timestamp | Unixタイムスタンプ。 |
| array | 順序付けられた値のシーケンス(単純な配列)。 |
| object | 連想配列。 |
| query | 返されるデータを定義する値。(特定のプロパティのみを返す)プロパティ名の配列として定義するか、定義済みの値のいずれかとして定義できます。extend - すべてのオブジェクトプロパティを返します。count - 取得したレコードの数を返します。特定のサブセレクトでのみサポートされます。 |
Zabbix APIは常に文字列または配列としてのみ値を返します。
プロパティの動作
一部のオブジェクトプロパティには、その動作を説明する短いラベルが付けられています。使用されるラベルは次のとおりです:
- 読み取り専用 - プロパティの値は自動的に設定され、特定の状況下でもユーザーが定義または変更することはできません(例: 継承オブジェクトまたは検出されたオブジェクトの場合は読み取り専用)。
- 書き込み専用 - プロパティの値は設定できますが、作成後にアクセスすることはできません。
- 定数 - プロパティの値はオブジェクトの作成時に設定できますが、作成後は変更できません。
- サポート - プロパティの値の設定は必須ではありませんが、特定の状況下では設定が許可されます(例:
typeが"シンプルチェック"、"外部チェック"、"SSH エージェント"、"TELNETエージェント"、または"HTTPエージェント"に設定されている場合、サポート)。ただし、サポートのプロパティは、状況に関係なくデフォルト値に設定される場合があることに注意してください。 - 必須 - プロパティの値は、すべての操作(取得操作を除く)または特定の条件(例: 作成操作の場合は必須、
operationtypeが"グローバルスクリプト"に設定され、opcommand_hstが設定されていない場合は必須)で設定する必要があります。
更新操作の場合、プロパティは更新操作中に設定されると"設定済み"とみなされます。
ラベルが付いていないプロパティはオプションです。
パラメーターの動作
一部の操作パラメーターには、操作における動作を説明する短いラベルが付けられています。使用されるラベルは次のとおりです:
- 読み取り専用 - パラメーターの値は自動的に設定され、特定の条件下でもユーザーが定義または変更することはできません(例: 継承されたオブジェクトまたは検出されたオブジェクトの場合は読み取り専用）。
- 書き込み専用 - パラメーターの値は設定できますが、設定後はアクセスできません。
- サポート - パラメーターの値の設定は必須ではありませんが、特定の条件下では設定が許可されます(例: Proxyオブジェクトの
operating_modeが"パッシブプロキシ"に設定されている場合はサポート)。ただし、サポートされたパラメーターは、条件に関わらずデフォルト値に設定される場合があります。 - 必須 - パラメーターの値の設定は必須です。
ラベルが付いていないパラメーターはオプションです。
予約ID値"0"
予約ID値"0"は、要素をフィルタリングしたり、参照されているオブジェクトを削除したりするために使用できます。たとえば、ホストから参照されているプロキシを削除するには、proxyidを0に設定する必要があります("proxyid": "0")。また、サーバーオプションproxyidsによって監視されるホストをフィルタリングするには、proxyidsを0に設定する必要があります("proxyids": "0")。
"get" メソッドの共通パラメータ
以下のパラメータは、すべての get メソッドでサポートされています:
| パラメータ | Type | 説明 |
|---|---|---|
| countOutput | boolean | Return the number of records in the result instead of the actual data. |
| editable | boolean | If set to true return only objects that the user has write permissions to.Default: false. |
| excludeSearch | boolean | Return results that do not match the criteria given in the search parameter. |
| filter | object | Return only those results that exactly match the given filter. Accepts an array, where the keys are property names, and the values are either a single value or an array of values to match against. Doesn't work for text fields. |
| limit | integer | Limit the number of records returned. |
| output | query | Object properties to be returned. Default: extend. |
| preservekeys | boolean | Use IDs as keys in the resulting array. |
| search | object | Return results that match the given wildcard search (case-insensitive). Accepts an array, where the keys are property names, and the values are strings to search for. If no additional options are given, this will perform a LIKE "%…%" search.Works only for string and text fields. |
| searchByAny | boolean | If set to true return results that match any of the criteria given in the filter or search parameter instead of all of them.Default: false. |
| searchWildcardsEnabled | boolean | If set to true enables the use of "*" as a wildcard character in the search parameter.Default: false. |
| sortfield | string/array | Sort the result by the given properties. Refer to a specific API get method description for a list of properties that can be used for sorting. Macros are not expanded before sorting. If no value is specified, data will be returned unsorted. |
| sortorder | string/array | Order of sorting. If an array is passed, each value will be matched to the corresponding property given in the sortfield parameter.Possible values are: ASC - (default) ascending;DESC - descending. |
| startSearch | boolean | The search parameter will compare the beginning of fields, that is, perform a LIKE "…%" search instead.Ignored if searchWildcardsEnabled is set to true. |
Entity origin flags
Get methods return a flags property for entities related to low-level discovery (LLD rule/LLD rule prototype, item/item prototype, etc). This property is useful to denote if the entity has been discovered or not, since editing for discovered entities is limited.
The flags property returns a result based on a combination ("+" operation) of these values:
| Value | Description |
|---|---|
| 0 | Base entity (item, trigger, graph, host) |
| 1 | Low-level discovery rule |
| 2 | Any prototype (item prototype, trigger prototype, LLD rule prototype, etc) |
| 4 | Discovered entity (discovered item, trigger, graph, host, LLD rule) |
The combined value returned by the flags property may be:
| Value | Combination of | Description |
|---|---|---|
| 0 | 0 | Plain entity (item, trigger, graph, host). |
| 2 | 2 | Entity prototype (item prototype, trigger prototype, etc). |
| 6 | 2+4 | Discovered item, trigger, graph, host (converted from prototype). |
| 1 | 1 | Low-level discovery rule. |
| 3 | 1+2 | Low-level discovery rule prototype. |
| 5 | 1+4 | Discovered low-level discovery rule (converted from prototype). |
| 7 | 1+2+4 | Discovered low-level discovery rule prototype. |
例
ユーザー権限のチェック
ユーザーは、名前が"MySQL"または"Linux"で始まるホストに書き込む権限を持っていますか？
{ "jsonrpc": "2.0", "method": "host.get", "params": { "countOutput": true, "search": { "host": ["MySQL", "Linux"] }, "editable": true, "startSearch": true, "searchByAny": true }, "id": 1 }レスポンス:
"result"が"0"の場合は、読み取り/書き込み権限を持つホストが存在しないことを意味します。
不一致を数える
名前に部分文字列"ubuntu"が含まれていないホストの数を数えます。
{ "jsonrpc": "2.0", "method": "host.get", "params": { "countOutput": true, "search": { "host": "ubuntu" }, "excludeSearch": true }, "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 }