[comment]: # translation:outdated [comment]: # ({6d056871-6d056871}) # Dodatek 1. Komentarz referencyjny [comment]: # ({/6d056871-6d056871}) [comment]: # ({6594bdc4-6594bdc4}) ### Notacja [comment]: # ({/6594bdc4-6594bdc4}) [comment]: # ({8c926b1a-2df08058}) #### Typy danych API Zabbix obsługuje następujące typy danych jako dane wejściowe: |Type|Description| |--|--------| |ID|Unikalny identyfikator używany do odwoływania się do encji.| |boolean|Wartość logiczna (`true` lub `false`).| |flag|Wartość uznawana za `true`, jeśli została przekazana i nie jest równa `null`; w przeciwnym razie wartość jest uznawana za `false`.| |integer|Liczba całkowita.| |float|Liczba zmiennoprzecinkowa.| |string|Ciąg tekstowy.| |text|Dłuższy ciąg tekstowy.| |timestamp|Znacznik czasu Unix.| |array|Uporządkowana sekwencja wartości (zwykła tablica).| |object|Tablica asocjacyjna.| |query|Wartość definiująca dane, które mają zostać zwrócone. Wartość może być zdefiniowana jako tablica nazw właściwości (aby zwrócić tylko określone właściwości) lub jako jedna ze wstępnie zdefiniowanych wartości:
`extend` - zwraca wszystkie właściwości obiektu;
`count` - zwraca liczbę pobranych rekordów, obsługiwane tylko przez niektóre podwybory.| ::: noteimportant API Zabbix zawsze zwraca wartości wyłącznie jako ciągi znaków lub tablice. ::: [comment]: # ({/8c926b1a-2df08058}) [comment]: # ({8f68b338-a2c16a18}) #### Zachowanie właściwości Niektóre właściwości obiektu są oznaczone krótkimi etykietami opisującymi ich zachowanie. Używane są następujące etykiety: - ***tylko do odczytu*** - wartość właściwości jest ustawiana automatycznie i nie może być definiowana ani zmieniana przez użytkownika, nawet w niektórych szczególnych warunkach (np. *tylko do odczytu* dla obiektów dziedziczonych lub obiektów wykrytych); - ***tylko do zapisu*** - wartość właściwości może zostać ustawiona, ale później nie można uzyskać do niej dostępu; - ***stała*** - wartość właściwości może zostać ustawiona podczas tworzenia obiektu, ale później nie może być zmieniona; - ***obsługiwana*** - ustawienie wartości właściwości nie jest wymagane, ale jest dozwolone w niektórych szczególnych warunkach (np. *obsługiwana*, jeśli `type` jest ustawione na "Simple check", "External check", "SSH agent", "TELNET agent" lub "HTTP agent"); należy jednak pamiętać, że właściwości oznaczone jako *obsługiwana* mogą nadal być ustawiane na swoje wartości domyślne niezależnie od warunków; - ***wymagana*** - ustawienie wartości właściwości jest wymagane dla wszystkich operacji (z wyjątkiem operacji pobierania) lub w niektórych szczególnych warunkach (np. *wymagana* dla operacji tworzenia; *wymagana*, jeśli `operationtype` jest ustawione na "global script", a `opcommand_hst` nie jest ustawione). ::: noteclassic W przypadku operacji aktualizacji właściwość jest uznawana za „ustawioną”, gdy zostanie ustawiona podczas operacji aktualizacji. ::: Właściwości, które nie są oznaczone etykietami, są opcjonalne. [comment]: # ({/8f68b338-a2c16a18}) [comment]: # ({f960f4be-f255da9d}) #### Zachowanie parametrów Niektóre parametry operacji są oznaczone krótkimi etykietami opisującymi ich zachowanie dla danej operacji. Używane są następujące etykiety: - ***tylko do odczytu*** - wartość parametru jest ustawiana automatycznie i nie może być definiowana ani zmieniana przez użytkownika, nawet w niektórych szczególnych warunkach (np. *tylko do odczytu* dla obiektów dziedziczonych lub obiektów wykrytych); - ***tylko do zapisu*** - wartość parametru może zostać ustawiona, ale później nie można uzyskać do niej dostępu; - ***obsługiwany*** - ustawienie wartości parametru nie jest wymagane, ale jest dozwolone w niektórych szczególnych warunkach (np. *obsługiwany*, jeśli `operating_mode` obiektu Proxy jest ustawiony na "passive proxy"); należy jednak pamiętać, że parametry oznaczone jako *obsługiwany* nadal mogą być ustawiane na wartości domyślne niezależnie od warunków; - ***wymagany*** - wartość parametru musi zostać ustawiona. Parametry, które nie są oznaczone etykietami, są opcjonalne. [comment]: # ({/f960f4be-f255da9d}) [comment]: # ({cf59def4-5e99748d}) ### Zastrzeżona wartość ID "0" Zastrzeżona wartość ID "0" może być używana do filtrowania elementów i usuwania obiektów , do których istnieją odniesienia. Na przykład, aby usunąć odwołanie do proxy z hosta , proxyid powinno być ustawione na 0 ("proxyid": "0") lub aby filtrować hosty monitorowane przez opcję serwera proxyids powinno być ustawione na 0 ("proxyids": "0"). [comment]: # ({/cf59def4-5e99748d}) [comment]: # ({da9957c2-b4e0f5ab}) ### Wspólne parametry metod "get" Następujące parametry są obsługiwane przez wszystkie metody `get`: |Parametr|[Typ](#data-types)|Opis| |-|-|--------| |countOutput|boolean|Zwraca liczbę rekordów w wyniku zamiast rzeczywistych danych.| |editable|boolean|Jeśli ustawiono na `true`, zwraca tylko obiekty, do których użytkownik ma uprawnienia zapisu.

Domyślnie: `false`.| |excludeSearch|boolean|Zwraca wyniki, które nie pasują do kryteriów podanych w parametrze `search`.| |filter|object|Zwraca tylko te wyniki, które dokładnie odpowiadają podanemu filtrowi.

Akceptuje obiekt, w którym kluczami są nazwy właściwości (np. właściwości obiektu Host w `host.get`, właściwości obiektu Item w `item.get` itd.), a wartościami są pojedyncza wartość lub tablica wartości do dopasowania.

Nie obsługuje właściwości typu danych `text` [data type](#data-types).

Należy pamiętać, że niektóre metody mają specyficzną funkcjonalność dla tego parametru, opisaną na stronie danej metody (np. parametr `filter` w [host.get](/manual/api/reference/host/get) obsługuje również właściwości interfejsu hosta).| |limit|integer|Ogranicza liczbę zwracanych rekordów.| |output|query|Właściwości obiektu, które mają zostać zwrócone.

Należy pamiętać, że identyfikator obiektu (tj. `hostid`, `itemid` itd.) jest zawsze uwzględniany w odpowiedzi, nawet jeśli nie został określony w parametrze `output`.

Domyślnie: `extend`.| |preservekeys|boolean|Używa identyfikatorów jako kluczy w wynikowej tablicy.| |search|object|Zwraca wyniki pasujące do podanego wzorca (bez rozróżniania wielkości liter).

Akceptuje obiekt, w którym kluczami są nazwy właściwości (np. właściwości obiektu Host w `host.get`, właściwości obiektu Item w `item.get` itd.), a wartościami są ciągi znaków do wyszukania. Jeśli nie podano dodatkowych opcji, zostanie wykonane wyszukiwanie `LIKE "%…%"`.

Obsługuje tylko właściwości typu danych `string` i `text` [data type](#data-types).

Należy pamiętać, że niektóre metody mają specyficzną funkcjonalność dla tego parametru, opisaną na stronie danej metody (np. parametr `search` w [host.get](/manual/api/reference/host/get) obsługuje również właściwości interfejsu hosta).| |searchByAny|boolean|Jeśli ustawiono na `true`, zwraca wyniki pasujące do dowolnego z kryteriów podanych w parametrze `filter` lub `search`, zamiast do wszystkich.

Domyślnie: `false`.| |searchWildcardsEnabled|boolean|Jeśli ustawiono na `true`, włącza użycie znaku "\*" jako znaku wieloznacznego w parametrze `search`.

Domyślnie: `false`.| |sortfield|string/array|Sortuje wynik według podanych właściwości. Listę właściwości, które mogą być używane do sortowania, można znaleźć w opisie konkretnej metody API get. Makra nie są rozwijane przed sortowaniem.

Jeśli nie podano wartości, dane zostaną zwrócone bez sortowania.| |sortorder|string/array|Kolejność sortowania. Jeśli przekazano tablicę, każda wartość zostanie dopasowana do odpowiadającej jej właściwości podanej w parametrze `sortfield`.

Możliwe wartości:
`ASC` - *(domyślnie)* rosnąco;
`DESC` - malejąco.| |startSearch|boolean|Parametr `search` będzie porównywał początek pól, czyli zamiast tego wykona wyszukiwanie `LIKE "…%"`.

Ignorowane, jeśli `searchWildcardsEnabled` jest ustawione na `true`.| [comment]: # ({/da9957c2-b4e0f5ab}) [comment]: # ({1f52febe-4a0aeab6}) ### Flagi pochodzenia encji Metody get zwracają właściwość `flags` dla encji powiązanych z wykrywaniem niskopoziomowym (reguła LLD/prototyp reguły LLD, pozycja/prototyp pozycji itd.). Ta właściwość jest przydatna do określenia, czy encja została wykryta, czy nie, ponieważ możliwości edycji wykrytych encji są ograniczone. Właściwość `flags` zwraca wynik oparty na kombinacji (operacja „+”) tych wartości: |Value|Description| |--|--------| |0|Encja bazowa (pozycja, wyzwalacz, wykres, host)| |1|Reguła wykrywania niskopoziomowego| |2|Dowolny prototyp (prototyp pozycji, prototyp wyzwalacza, prototyp reguły LLD itd.)| |4|Wykryta encja (wykryta pozycja, wyzwalacz, wykres, host, reguła LLD)| **Łączna** wartość zwracana przez właściwość `flags` może być następująca: |Value|Combination of|Description| |--|--|------| |**0**|0|Zwykła encja (pozycja, wyzwalacz, wykres, host).| |**2**|2|Prototyp encji (prototyp pozycji, prototyp wyzwalacza itd.).| |**6**|2+4|Wykryta pozycja, wyzwalacz, wykres, host (utworzone z prototypu).| |**1**|1|Reguła wykrywania niskopoziomowego.| |**3**|1+2|Prototyp reguły wykrywania niskopoziomowego.| |**5**|1+4|Wykryta reguła wykrywania niskopoziomowego (utworzona z prototypu).| |**7**|1+2+4|Wykryty prototyp reguły wykrywania niskopoziomowego.| [comment]: # ({/1f52febe-4a0aeab6}) [comment]: # ({b41637d2-b41637d2}) ### Przykłady [comment]: # ({/b41637d2-b41637d2}) [comment]: # ({7f8a25ac-7a121fac}) #### Sprawdzenie uprawnień użytkownika Czy użytkownik ma uprawnienia do zapisu do hostów, których nazwy zaczynają się od "MySQL" lub "Linux" ? [Żądanie](/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 } ``` Odpowiedź: ```json { "jsonrpc": "2.0", "result": "0", "id": 1 } ``` ::: noteclassic Wynik zero oznacza brak hostów z uprawnieniami do odczytu/zapisu. ::: [comment]: # ({/7f8a25ac-7a121fac}) [comment]: # ({b814e950-ea3cccd8}) #### Zliczanie niedopasowań Policz liczbę hostów, których nazwy nie zawierają podciągu "ubuntu" [Żądanie](/manual/api#performing-requests): ```json { "jsonrpc": "2.0", "method": "host.get", "params": { "countOutput": true, "search": { "host": "ubuntu" }, "excludeSearch": true }, "id": 1 } ``` Odpowiedź: ```json { "jsonrpc": "2.0", "result": "44", "id": 1 } ``` [comment]: # ({/b814e950-ea3cccd8}) [comment]: # ({a325f949-e911c08b}) #### Wyszukiwanie hostów przy użyciu symboli wieloznacznych Znajdź hosty, których nazwa zawiera słowo „server” i które mają porty interfejsów „10050” lub „10071”. Posortuj wynik według nazwy hosta malejąco i ogranicz go do 5 hostów. [Żądanie](/manual/api#performing-requests): ```json { "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 } ``` Odpowiedź: ```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}) #### Wyszukiwanie hostów przy użyciu symboli wieloznacznych z parametrem "preservekeys" Jeśli dodasz parametr "preservekeys" do poprzedniego żądania, wynik zostanie zwrócony jako tablica asocjacyjna, gdzie kluczami są identyfikatory obiektów. [Żądanie](/manual/api#performing-requests): ```json { "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 } ``` Odpowiedź: ```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})