[comment]: # translation:outdated

[comment]: # ({6d056871-6d056871})
# Apèndix 1. Comentari de referència

[comment]: # ({/6d056871-6d056871})

[comment]: # ({6594bdc4-6594bdc4})
### Notació

[comment]: # ({/6594bdc4-6594bdc4})

[comment]: # ({8c926b1a-2df08058})
#### Tipus de dades

L'API de Zabbix suporta, com a dades d'entrada, els següents tipus:

|Tipus|Descripció|
|--|--------|
|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.<br><br>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:<br>`extend` - retorna totes les propietats de l'objecte;<br>`count` - retorna el nombre de registres recuperats, suportats només per algunes subseleccions.|

::: notaimportant
L'API de Zabbix sempre retorna com a valors valors strings o arrays.
:::

[comment]: # ({/8c926b1a-2df08058})

[comment]: # ({8f68b338-a2c16a18})
#### 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 `tipus` s'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 `operationtype` s'estableix a "script global" i `opcommand_hst` no s'ha establert).

::: noteclassic
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.

[comment]: # ({/8f68b338-a2c16a18})

[comment]: # ({f960f4be-f255da9d})
#### 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;
- ***admès*** - no cal establir el valor de la propietat, però es pot establir en algunes condicions específiques (p. ex., *admès* si `operating_mode` de 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.

[comment]: # ({/f960f4be-f255da9d})

[comment]: # ({cf59def4-5e99748d})
### 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").

[comment]: # ({/cf59def4-5e99748d})

[comment]: # ({93faa603-b4e0f5ab})
### Paràmetres comuns del mètode "get"

Es suporten per tots els mètodes `get` els paràmetres següents:

|Paràmetre|[Tipus](#data_types)|Descripció|
|---------|------|---------------------------------------------------|
|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.<br><br>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.<br><br>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 a `item.get', etc.), i els valors són un valor únic o una matriu de valors amb els quals coincideix.<br><br><br> type](#data-types).<br><br>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](/manual/api/reference/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.<br><br>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).<br><br>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 "%…%"`.<br><br>Només admet propietats de `string` i `text` [tipus de dades](#data-types).<br><br>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.<br><br>Per defecte: `false`.|
|searchWildcardsEnabled|boolean|Si s'estableix a `true`, permet l'us de "\*" com a comodí al paràmetre `search`.<br><br>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.<br><br>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`.<br><br>Els valors possibles són:<br>`ASC` - *(per defecte)* ascendent;<br>`DESC` - descendent.|
|startSearch|boolean|El paràmetre `search` es compara amb el principi dels camps; és a dir, es farà una cerca `LIKE "…%"`.<br><br>S'ignorarà si el `searchWildcardsEnabled` és establert a `true`.|

[comment]: # ({/93faa603-b4e0f5ab})

[comment]: # ({1f52febe-4a0aeab6})
### Banderes d'origen d'entitats

Els mètodes Get retornen una propietat `flags` per a entitats relacionades amb la descoberta de baix nivell (regla LLD/prototip de regla LLD, element/prototip d'element, etc.). Aquesta propietat és útil per indicar si l'entitat s'ha trobat o no, ja que l'edició per a entitats trobades és limitada.

La propietat `flags` retorna un resultat basat en una combinació (operació "+") d'aquests valors:

|Valor|Descripció|
|--|--------|
|0|Entitat base (element, trigger, gràfic, equip)|
|1|Regla de descoberta de baix nivell|
|2|Qualsevol prototip (prototip d'element, prototip de trigger, prototip de regla LLD, etc.)|
|4|Entitat trobada (element, trigger, gràfic, equip, regla LLD)|

El valor **combinat** retornat per la propietat `flags` pot ser:

|Valor|Combinació de|Descripció|
|--|--|------|
|**0**|0|Entitat simple (element, trigger, gràfic, equip).|
|**2**|2|Prototip d'entitat (prototip d'element, prototip de trigger, etc.).|
|**6**|2+4|Element, trigger, gràfic, equips trobats (convertits des del prototip).|
|**1**|1|Regla de descoberta de baix nivell.|
|**3**|1+2|Prototip de regla de descoberta de baix nivell.|
|**5**|1+4|Regla de descoberta de baix nivell (convertida des del prototip).|
|**7**|1+2+4|Prototip de regla de descoberta de baix nivell.| 

[comment]: # ({/1f52febe-4a0aeab6})

[comment]: # ({b41637d2-b41637d2})
### Exemples

[comment]: # ({/b41637d2-b41637d2})

[comment]: # ({7f8a25ac-7a121fac})
#### Verificació dels permisos d'usuari

Té permisos l'usuari per escriure als equips amb noms que comencen amb "MySQL" o "Linux"?

[Petició](/manual/api#performing-requests):

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

Resposta:

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

::: noteclassic
El resultat zero vol dir que no hi ha equips amb permisos de lectura/escriptura.
:::

[comment]: # ({/7f8a25ac-7a121fac})

[comment]: # ({b814e950-ea3cccd8})
#### Recompte d'incompatibilitat

Compta el nombre d'equips amb noms que no tenen pas la subcadena "ubuntu"

[Petició](/manual/api#performing-requests):

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

Resposta:

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

[comment]: # ({/b814e950-ea3cccd8})

[comment]: # ({a325f949-e911c08b})
#### 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.

[Petició](/manual/api#performing-requests):

```json
{
    "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:

```json
{
    "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
}
```

[comment]: # ({/a325f949-e911c08b})

[comment]: # ({8c8fa5f6-8ce6f554})
#### 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.

[Petició](/manual/api#performing-requests):

```json
{
    "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:

```json
{
    "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
}
```

[comment]: # ({/8c8fa5f6-8ce6f554})