Documentation
Table of Contents
Ap¨¨ndix 1. Comentari de refer¨¨ncia
±·´Ç³Ù²¹³¦¾±¨®
Tipus de dades
L'API de Áú»¢¶Ä²© suporta, com a dades d'entrada, els seg¨¹ents tipus:
| Tipus | ¶Ù±ð²õ³¦°ù¾±±è³¦¾±¨® |
|---|---|
| ID | Un identificador ¨²nic emprat per referenciar una entitat. |
| boolean | Un valor boole¨¤ accepta tant true com false. |
| flag | El valor es considera true si no ¨¦s igual a null, i false en cas contrari. |
| integer | Un nombre sencer. |
| float | Un nombre de coma flotant. |
| string | Una cadena de text. |
| text | Una cadena llarga de text. |
| timestamp | Una marca de temps de Unix. |
| array | Una seq¨¹¨¨ncia ordenada de valors; o sia, una matriu simple. |
| object | Una matriu associativa. |
| query | Un valor que defineix quina informaci¨® ha de retornar. Es pot definir com una matriu de noms de propietats, per tal de retornar nom¨¦s propietats espec¨ªfiques; o com un dels valors predefinits: extend - retorna totes les propietats de l'objecte;count - retorna el nombre de registres recuperats, suportats nom¨¦s per algunes subseleccions. |
L'API de Áú»¢¶Ä²© sempre retorna com a valors valors strings o arrays.
Comportament de la propietat
Algunes de les propietats de l'objecte s¨®n etiquetades per descriure el seu comportament. S'empren les seg¨¹ents etiquetes:
- nom¨¦s lectura - el valor de la propietat s'estableix autom¨¤ticament i l'usuari no pot definir ni canviar, fins i tot en algunes condicions espec¨ªfiques (p. ex., nom¨¦s lectura per a objectes heretats o objectes descoberts);
- nom¨¦s escriptura - es pot establir el valor de la propietat, per¨° no s'hi pot accedir despr¨¦s;
- constant - el valor de la propietat es pot establir en crear un objecte, per¨° no es pot canviar despr¨¦s;
- suportada - no cal establir el valor de la propietat, per¨° es pot establir en algunes condicions espec¨ªfiques (p. ex., suportada si
tipuss'estableix a "Comprovaci¨® simple", "Comprovaci¨® externa", "Agent SSH", "Agent TELNET" o "Agent HTTP"); tingueu en compte, per¨°, que les propietats admeses encara es poden establir als seus valors predeterminats, independentment de les condicions; - obligatori - cal establir el valor de la propietat per a totes les operacions (excepte les operacions d'obtenci¨®) o en algunes condicions espec¨ªfiques (p. ex., obligatori per a les operacions de creaci¨®; obligatori si
operationtypes'estableix a "script global" iopcommand_hstno s'ha establert).
Per a les operacions d'actualitzaci¨®, una propietat es considera "configurada" quan es defineix durant l'operaci¨® d'actualitzaci¨®.
Les propietats que no s¨®n etiquetades s¨®n opcionals.
Comportament del par¨¤metre
Alguns dels par¨¤metres de l'objecte s¨®n etiquetats per descriure el seu comportament. S'empren les seg¨¹ents etiquetes:
- nom¨¦s lectura - el valor del par¨¤metre s'estableix autom¨¤ticament i l'usuari no pot definir ni canviar, fins i tot en algunes condicions espec¨ªfiques (p. ex., nom¨¦s lectura per a objectes heretats o objectes descoberts);
- nom¨¦s escriptura - es pot establir el valor del par¨¤metre, per¨° no s'hi pot accedir despr¨¦s;
- ²¹»å³¾¨¨²õ - no cal establir el valor de la propietat, per¨° es pot establir en algunes condicions espec¨ªfiques (p. ex., ²¹»å³¾¨¨²õ si
operating_modede l'objecte Proxy s'estableix a "proxy passiu"); tingueu en compte, per¨°, que les propietats admeses encara es poden establir als seus valors predeterminats, independentment de les condicions; - obligatori - cal establir el valor de la propietat.
Les propietats que no s¨®n etiquetades s¨®n opcionals.
Valor d'ID reservat "0"
El valor "0" d'ID reservat es pot emprar per filtrar elements i esborrar objectes referenciats. Per exemple, per esborrar un proxy referenciat d'un equip, s'ha d'establir proxyid should a 0 ("proxyid": "0"), o per filtrar equips monitorats per l'opci¨® del servidor, s'ha d'establir proxyids a 0 ("proxyids": "0").
±Ê²¹°ù¨¤³¾±ð³Ù°ù±ðs comuns del m¨¨tode "get"
Es suporten per tots els m¨¨todes get els par¨¤metres seg¨¹ents:
| ±Ê²¹°ù¨¤³¾±ð³Ù°ù±ð | Tipus | ¶Ù±ð²õ³¦°ù¾±±è³¦¾±¨® |
|---|---|---|
| countOutput | boolean | Torna el nombre de registres al resultat, enlloc de les dades reals. |
| editable | boolean | Si s'estableix a true, nom¨¦s retorna els objectes per als quals l'usuari t¨¦ permisos d'escriptura.Per defecte: false. |
| excludeSearch | boolean | Retorna els resultats que no corresponen pas als criteris prove?ts al par¨¤metre search. |
| filter | object | Retorna els resultats que corresponen al filtre prove?t. Admet un objecte, on les claus s¨®n noms de propietat (p. ex., propietats de l'objecte de l'equip a host.get', propietats de l'objecte de l'element aitem.get', etc.), i els valors s¨®n un valor ¨²nic o una matriu de valors amb els quals coincideix.type](#data-types). Tingueu en compte que alguns m¨¨todes tenen una funcionalitat espec¨ªfica per a aquest par¨¤metre, que es descriu a la p¨¤gina del m¨¨tode (per exemple, el par¨¤metre filter a host.get tamb¨¦ admet propietats de la interf¨ªcie de l'equip). |
| limit | integer | Limita el nombre de registres retornats. |
| output | query | Propietats de l'objecte que es retornaran. Per defecte: extend. |
| preservekeys | boolean | Empra els IDs com a claus de la matriu resultant. |
| search | object | Retorna els resultats que corresponen a la cerca amb comodins (sensible a maj¨²scules i min¨²scules). Accepta una matriu, on les claus s¨®n noms de propietats i els valors s¨®n les cadenes que seran cercades. Si no s'especifica cap opci¨® addicional, s'executar¨¤ una cerca LIKE "%¡%".Nom¨¦s admet propietats de string i text tipus de dades.Tingueu en compte que alguns m¨¨todes tenen una funcionalitat espec¨ªfica per a aquest par¨¤metre, que es descriu a la p¨¤gina del m¨¨tode (p. tamb¨¦ admet propietats de la interf¨ªcie de l'equip). |
| searchByAny | boolean | Si s'estableix a true, retorna els resultats que corresponen al criteri donat als par¨¤metres filter o search, enlloc de retornar-los tots.Per defecte: false. |
| searchWildcardsEnabled | boolean | Si s'estableix a true, permet l'us de "*" com a comod¨ª al par¨¤metre search.Per defecte: false. |
| sortfield | string/array | Ordena el resultat per les propietats donades. Consulteu una descripci¨® espec¨ªfica del m¨¨tode get de l'API per obtindre una llista de propietats que es poden emprar per la classificaci¨®. Les macros no s¨®n pas ampliades abans d'ordenar. Si no s'especifiquen valors, la informaci¨® es retorna sense ordenar. |
| sortorder | string/array | Ordre de classificaci¨®. Si es passa una matriu, cada valor correspondr¨¤ amb la propietat donada al par¨¤metre sortfield.Els valors possibles s¨®n: ASC - (per defecte) ascendent;DESC - descendent. |
| startSearch | boolean | El par¨¤metre search es compara amb el principi dels camps; ¨¦s a dir, es far¨¤ una cerca LIKE "¡%".S'ignorar¨¤ si el searchWildcardsEnabled ¨¦s establert a true. |
Exemples
Verificaci¨® dels permisos d'usuari
T¨¦ permisos l'usuari per escriure als equips amb noms que comencen amb "MySQL" o "Linux"?
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"countOutput": true,
"search": {
"host": ["MySQL", "Linux"]
},
"editable": true,
"startSearch": true,
"searchByAny": true
},
"id": 1
}Resposta:
El resultat zero vol dir que no hi ha equips amb permisos de lectura/escriptura.
Recompte d'incompatibilitat
Compta el nombre d'equips amb noms que no tenen pas la subcadena "ubuntu"
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"countOutput": true,
"search": {
"host": "ubuntu"
},
"excludeSearch": true
},
"id": 1
}Resposta:
Cerca d'equips emprant comodins
Troba els equips amb nom que cont¨¦ la paraula "servidor" i t¨¦ ports de xarxa "10050" o "10071". Ordena el resultat per nom d'equip, en ordre decreixent, i limitat a 5 equips.
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"output": ["hostid", "host"],
"selectInterfaces": ["port"],
"filter": {
"port": ["10050", "10071"]
},
"search": {
"host": "*servidor*"
},
"searchWildcardsEnabled": true,
"searchByAny": true,
"sortfield": "host",
"sortorder": "DESC",
"limit": 5
},
"id": 1
}Resposta:
{
"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
}Cercant equips emprant comodins amb "preservekeys"
Si afegiu al par¨¤metre "preservekeys" a la consulta anterior, retorna el resultat com una matriu associativa, on les claus s¨®n els id dels objectes.
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"output": ["hostid", "host"],
"selectInterfaces": ["port"],
"filter": {
"port": ["10050", "10071"]
},
"search": {
"host": "*servidor*"
},
"searchWildcardsEnabled": true,
"searchByAny": true,
"sortfield": "host",
"sortorder": "DESC",
"limit": 5,
"preservekeys": true
},
"id": 1
}Resposta:
{
"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
}