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 メソッドでサポートされているパラメータは以下の通りです。
| パラメータ | 型 | 説明 |
|---|---|---|
| countOutput | boolean | 実際のデータの代わりに、結果のレコード数を返します。 |
| editable | boolean | true に設定すると、ユーザーが書き込み権限を持つオブジェクトのみを返します。デフォルト: false。 |
| excludeSearch | boolean | search パラメータで指定した条件に一致しない結果を返します。 |
| filter | object | 指定したフィルターに完全一致する結果のみを返します。 オブジェクトを受け入れ、キーはプロパティ名 (例: host.get ではホストオブジェクトのプロパティ、item.get ではアイテムオブジェクトのプロパティなど)、値は一致させる単一値または値の配列です。text データ型のプロパティはサポートされません。一部のメソッドでは、このパラメータに固有の機能があり、メソッドページで説明されています (例: host.get の filter パラメータはホストインターフェースのプロパティもサポートします)。 |
| limit | integer | 返されるレコード数を制限します。 |
| output | query | 返すオブジェクトのプロパティ。 デフォルト: extend。 |
| preservekeys | boolean | 結果配列のキーとしてIDを使用します。 |
| search | object | 指定したパターンに一致する結果を返します (大文字・小文字は区別しません)。 オブジェクトを受け入れ、キーはプロパティ名 (例: host.get ではホストオブジェクトのプロパティ、item.get ではアイテムオブジェクトのプロパティなど)、値は検索する文字列です。追加オプションが指定されていない場合、LIKE "%…%" 検索が実行されます。string および text データ型のプロパティのみサポートします。一部のメソッドでは、このパラメータに固有の機能があり、メソッドページで説明されています (例: host.get の search パラメータはホストインターフェースのプロパティもサポートします)。 |
| 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 の場合は無視されます。 |
エンティティの起源フラグ
Getメソッドは、低レベルディスカバリ（LLDルール/LLDルールプロトタイプ、アイテム/アイテムプロトタイプなど）に関連するエンティティに対してflagsプロパティを返します。このプロパティは、エンティティがディスカバリされたものかどうかを示すのに便利です。なぜなら、ディスカバリされたエンティティの編集は制限されるためです。
flagsプロパティは、これらの値の組み合わせ（"+"演算）に基づいて結果を返します。
| 値 | 説明 |
|---|---|
| 0 | 基本エンティティ（アイテム、トリガー、グラフ、ホスト） |
| 1 | 低レベルディスカバリルール |
| 2 | 任意のプロトタイプ（アイテムプロトタイプ、トリガープロトタイプ、LLDルールプロトタイプなど） |
| 4 | ディスカバリされたエンティティ（ディスカバリされたアイテム、トリガー、グラフ、ホスト、LLDルール） |
flagsプロパティによって返される組み合わせ値は次のとおりです。
| 値 | 組み合わせ | 説明 |
|---|---|---|
| 0 | 0 | 通常のエンティティ（アイテム、トリガー、グラフ、ホスト）。 |
| 2 | 2 | エンティティプロトタイプ（アイテムプロトタイプ、トリガープロトタイプなど）。 |
| 6 | 2+4 | ディスカバリされたアイテム、トリガー、グラフ、ホスト（プロトタイプから変換）。 |
| 1 | 1 | 低レベルディスカバリルール。 |
| 3 | 1+2 | 低レベルディスカバリルールプロトタイプ。 |
| 5 | 1+4 | ディスカバリされた低レベルディスカバリルール（プロトタイプから変換）。 |
| 7 | 1+2+4 | ディスカバリされた低レベルディスカバリルールプロトタイプ。 |
例
ユーザー権限のチェック
ユーザーは、名前が"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
}