[comment]: # ({7cef99ec-92f30379}) # 20 API [comment]: # ({/7cef99ec-92f30379}) [comment]: # ({d9e959c3-13405b49}) ### Przegląd API Zabbix umożliwia programowe pobieranie i modyfikowanie konfiguracji Zabbix oraz zapewnia dostęp do danych historycznych. Jest ono szeroko wykorzystywane do: - tworzenia nowych aplikacji współpracujących z Zabbix; - integracji Zabbix z oprogramowaniem innych producentów; - automatyzacji rutynowych zadań. API Zabbix jest interfejsem API opartym na HTTP i jest dostarczane jako część web frontend. Wykorzystuje protokół JSON-RPC 2.0, co oznacza dwie rzeczy: - API składa się z zestawu oddzielnych metod; - żądania i odpowiedzi między klientami a API są kodowane przy użyciu formatu JSON. Więcej informacji o protokole i formacie JSON można znaleźć w [specyfikacji JSON-RPC 2.0](http://www.jsonrpc.org/specification) oraz na [stronie głównej formatu JSON](http://json.org/). Więcej informacji o integrowaniu funkcjonalności Zabbix z aplikacjami Python można znaleźć w [bibliotece Python dla Zabbix](/devel/python). ::: noteclassic Dostęp użytkownika w Zabbix, obejmujący zarówno konfigurację, jak i dane historyczne, zależy od [typu użytkownika](/manual/config/users_and_usergroups/permissions#user-types), przypisanej [roli użytkownika](/manual/config/users_and_usergroups/permissions#user-roles) oraz [grup użytkowników](/manual/config/users_and_usergroups/usergroup). ::: [comment]: # ({/d9e959c3-13405b49}) [comment]: # ({76e2a1dd-9cb56d09}) ### Struktura API składa się z wielu metod, które są umownie pogrupowane w oddzielne API. Każda z metod wykonuje jedno konkretne zadanie. Na przykład metoda `host.create` należy do API *host* i służy do tworzenia nowych hostów. Historycznie API są czasami określane jako „klasy”. ::: notetip Większość API zawiera co najmniej cztery metody: `get`, `create`, `update` i `delete`, służące odpowiednio do pobierania, tworzenia, aktualizowania i usuwania danych, jednak niektóre API mogą udostępniać zupełnie inny zestaw metod. ::: [comment]: # ({/76e2a1dd-9cb56d09}) [comment]: # ({d3a7ab69-9cb2f5ca}) ### Wykonywanie żądań Po skonfigurowaniu frontend możesz używać zdalnych żądań HTTP do wywoływania API. Aby to zrobić, musisz wysyłać żądania HTTP POST do pliku `api_jsonrpc.php` znajdującego się w katalogu frontend. Na przykład, jeśli Twój frontend Zabbixa jest zainstalowany pod adresem `https://example.com/zabbix`, żądanie HTTP wywołujące metodę `apiinfo.version` może wyglądać następująco: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"apiinfo.version","params":{},"id":1}' ``` Żądanie musi mieć nagłówek `Content-Type` ustawiony na jedną z następujących wartości: `application/json-rpc`, `application/json` lub `application/jsonrequest`. Obiekt żądania musi zawierać następujące właściwości: - `jsonrpc` - wersja protokołu JSON-RPC używana przez API (Zabbix API implementuje wersję JSON-RPC 2.0); - `method` - wywoływana metoda API; - `params` - parametry przekazywane do metody API; - `id` - dowolny identyfikator żądania (jeśli zostanie pominięty, API traktuje żądanie jako [powiadomienie](https://www.jsonrpc.org/specification#notification)). Jeśli żądanie jest poprawne, odpowiedź zwrócona przez API powinna wyglądać następująco: ```json { "jsonrpc": "2.0", "result": "7.4.0", "id": 1 } ``` Obiekt odpowiedzi z kolei zawiera następujące właściwości: - `jsonrpc` - wersja protokołu JSON-RPC; - `result` - dane zwrócone przez metodę; - `id` - identyfikator odpowiadającego mu żądania. [comment]: # ({/d3a7ab69-9cb2f5ca}) [comment]: # ({c36376e5-ec5a9f60}) ### Przykładowy przepływ pracy Poniższa sekcja przeprowadzi Cię przez kilka przykładów użycia bardziej szczegółowo. [comment]: # ({/c36376e5-ec5a9f60}) [comment]: # ({17ec6118-ef3f5841}) #### Uwierzytelnianie Aby uzyskać dostęp do jakichkolwiek danych w Zabbix, musisz: - użyć istniejącego [tokenu API](/manual/web_interface/frontend_sections/users/api_tokens) (utworzonego w Zabbix frontend lub przy użyciu [Token API](/manual/api/reference/token)); - użyć tokenu uwierzytelniającego uzyskanego za pomocą metody [user.login](/manual/api/reference/user/login). Na przykład, jeśli chcesz uzyskać nowy token uwierzytelniający, logując się jako standardowy użytkownik *Admin*, żądanie JSON będzie wyglądać następująco: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"user.login","params":{"username":"Admin","password":"zabbix"},"id":1}' ``` Jeśli podasz poprawne dane logowania, odpowiedź zwrócona przez API powinna zawierać token uwierzytelniający użytkownika: ```json { "jsonrpc": "2.0", "result": "0424bd59b807674191e7d77572075f33", "id": 1 } ``` [comment]: # ({/17ec6118-ef3f5841}) [comment]: # ({d920bab8-37011a71}) #### Metody autoryzacji [comment]: # ({/d920bab8-37011a71}) [comment]: # ({78bcb6bc-130188f5}) ##### Za pomocą nagłówka "Authorization" Wszystkie żądania API wymagają uwierzytelnienia lub tokenu API. Dane uwierzytelniające można przekazać, używając nagłówka Authorization w żądaniu: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer 0424bd59b807674191e7d77572075f33' ``` ::: noteimportant Jeśli występują problemy z uwierzytelnianiem, zobacz [Przekazywanie nagłówka Authorization](/manual/installation/known_issues#authorization-header-forwarding). ::: API Zabbix akceptuje nagłówki bez rozróżniania wielkości liter (np. `authorization`, `Authorization` i `AUTHORIZATION` są traktowane tak samo). Nagłówek Authorization jest obsługiwany w żądaniach między źródłami ([CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)). [comment]: # ({/78bcb6bc-130188f5}) [comment]: # ({8a583b03-8950965e}) ##### Za pomocą pliku cookie Zabbix Plik cookie *"zbx_session"* jest używany do autoryzacji żądania API z interfejsu Zabbix UI wykonywanego przy użyciu JavaScript (z modułu lub niestandardowego widżetu). [comment]: # ({/8a583b03-8950965e}) [comment]: # ({7f924528-f572ecc2}) #### Pobieranie hostów Masz teraz prawidłowy token uwierzytelnienia użytkownika (przedstawiony jako zmienna w poniższych przykładach), którego można użyć do uzyskania dostępu do danych w Zabbix. Na przykład możesz użyć metody [host.get](/manual/api/reference/host/get), aby pobrać identyfikatory, nazwy hostów i interfejsy wszystkich skonfigurowanych [hostów](/manual/api/reference/host/object): Żądanie: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \ --header 'Content-Type: application/json-rpc' \ --data @data.json ``` ::: notetip `data.json` to plik zawierający zapytanie JSON. Zamiast pliku możesz przekazać zapytanie w argumencie `--data`. ::: data.json ```json { "jsonrpc": "2.0", "method": "host.get", "params": { "output": [ "hostid", "host" ], "selectInterfaces": [ "interfaceid", "ip" ] }, "id": 2 } ``` Obiekt odpowiedzi będzie zawierał żądane dane o hostach: ```json { "jsonrpc": "2.0", "result": [ { "hostid": "10084", "host": "Zabbix server", "interfaces": [ { "interfaceid": "1", "ip": "127.0.0.1" } ] } ], "id": 2 } ``` ::: notetip Ze względów wydajnościowych zawsze zaleca się podawanie na liście właściwości obiektu, które chcesz pobrać. Dzięki temu unikniesz pobierania wszystkiego. ::: [comment]: # ({/7f924528-f572ecc2}) [comment]: # ({c9fda4ae-ee2c324f}) #### Tworzenie nowej pozycji Teraz utwórz nową [pozycję](/manual/api/reference/item/object) na hoście „Zabbix server”, używając danych uzyskanych z poprzedniego żądania `host.get`. Można to zrobić za pomocą metody [item.create](/manual/api/reference/item/create): ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"item.create","params":{"name":"Free disk space on /home/joe/","key_":"vfs.fs.size[/home/joe/,free]","hostid":"10084","type":0,"value_type":3,"interfaceid":"1","delay":30},"id":3}' ``` Pomyślna odpowiedź będzie zawierać ID nowo utworzonej pozycji, którego można użyć do odwoływania się do tej pozycji w kolejnych żądaniach: ```json { "jsonrpc": "2.0", "result": { "itemids": [ "24759" ] }, "id": 3 } ``` ::: notetip Metoda `item.create`, podobnie jak inne *metody create*, może również przyjmować tablice obiektów i tworzyć wiele pozycji za pomocą jednego wywołania API. ::: [comment]: # ({/c9fda4ae-ee2c324f}) [comment]: # ({49a2cbe1-5ed44978}) #### Tworzenie wielu wyzwalaczy Jeśli więc *metody create* akceptują tablice, możesz dodać wiele [wyzwalaczy](/manual/api/reference/trigger/object), na przykład takie: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"trigger.create","params":[{"description":"Obciążenie procesora jest zbyt wysokie na {HOST.NAME}","expression":"last(/Linux server/system.cpu.load[percpu,avg1])>5"},{"description":"Zbyt wiele procesów na {HOST.NAME}","expression":"avg(/Linux server/proc.num[],5m)>300"}],"id":4}' ``` Pomyślna odpowiedź będzie zawierać identyfikatory nowo utworzonych wyzwalaczy: ```json { "jsonrpc": "2.0", "result": { "triggerids": [ "17369", "17370" ] }, "id": 4 } ``` [comment]: # ({/49a2cbe1-5ed44978}) [comment]: # ({07f914b6-aa174634}) #### Aktualizowanie pozycji Włącz pozycję, ustawiając jej status na „0”: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"item.update","params":{"itemid":"10092","status":0},"id":5}' ``` Pomyślna odpowiedź będzie zawierać ID zaktualizowanej pozycji: ```json { "jsonrpc": "2.0", "result": { "itemids": [ "10092" ] }, "id": 5 } ``` ::: notetip Metoda `item.update`, podobnie jak inne *metody aktualizacji*, może również przyjmować tablice obiektów i aktualizować wiele pozycji za pomocą jednego wywołania API. ::: [comment]: # ({/07f914b6-aa174634}) [comment]: # ({bfbd84bd-e217b4a2}) #### Aktualizacja wielu wyzwalaczy Włącz wiele wyzwalaczy, ustawiając ich status na "0": ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"trigger.update","params":[{"triggerid":"13938","status":0},{"triggerid":"13939","status":0}],"id":6}' ``` Pomyślna odpowiedź będzie zawierać identyfikatory zaktualizowanych wyzwalaczy: ```json { "jsonrpc": "2.0", "result": { "triggerids": [ "13938", "13939" ] }, "id": 6 } ``` ::: notetip Jest to preferowana metoda aktualizacji. Niektóre metody API, takie jak `host.massupdate`, umożliwiają napisanie prostszego kodu. Nie zaleca się jednak używania tych metod, ponieważ zostaną usunięte w przyszłych wydaniach. ::: [comment]: # ({/bfbd84bd-e217b4a2}) [comment]: # ({a9952ff9-7665e280}) #### Obsługa błędów Do tej pory wszystko, czego próbowano, działało poprawnie. Ale co by się stało, gdyby wykonać nieprawidłowe wywołanie API? Spróbuj utworzyć kolejny host, wywołując [host.create](/manual/api/reference/host/create), ale pomijając wymagany parametr `groups`: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"host.create","params":{"host":"Linux server","interfaces":[{"type":1,"main":1,"useip":1,"ip":"192.168.3.1","dns":"","port":"10050"}]},"id":7}' ``` Odpowiedź będzie wtedy zawierać komunikat o błędzie: ```json { "jsonrpc": "2.0", "error": { "code": -32602, "message": "Invalid params.", "data": "No groups for host \"Linux server\"." }, "id": 7 } ``` Jeśli wystąpił błąd, zamiast właściwości `result` obiekt odpowiedzi będzie zawierał właściwość `error` z następującymi danymi: - `code` - kod błędu; - `message` - krótkie podsumowanie błędu; - `data` - bardziej szczegółowy komunikat o błędzie. Błędy mogą wystąpić w różnych przypadkach, na przykład przy użyciu nieprawidłowych wartości wejściowych, przekroczeniu limitu czasu sesji lub próbie uzyskania dostępu do nieistniejących obiektów. Aplikacja powinna potrafić w poprawny sposób obsługiwać tego rodzaju błędy. [comment]: # ({/a9952ff9-7665e280}) [comment]: # ({0de672ce-c1074d48}) ### Wersje API Aby uprościć wersjonowanie API, od Zabbix 2.0.4 wersja API odpowiada wersji samego Zabbix. Możesz użyć metody [apiinfo.version](/manual/api/reference/apiinfo/version), aby sprawdzić wersję API, z którą pracujesz. Może to być przydatne przy dostosowywaniu aplikacji do korzystania z funkcji specyficznych dla danej wersji. Zabbix gwarantuje wsteczną kompatybilność funkcji w obrębie wersji głównej. W przypadku wprowadzania zmian niezgodnych wstecznie między głównymi wydaniami Zabbix zwykle pozostawia stare funkcje jako przestarzałe w następnym wydaniu, a usuwa je dopiero w kolejnym. Sporadycznie Zabbix może usuwać funkcje między głównymi wydaniami bez zapewnienia jakiejkolwiek wstecznej kompatybilności. Ważne jest, aby nigdy nie polegać na żadnych przestarzałych funkcjach i jak najszybciej przechodzić na nowsze alternatywy. ::: notetip Możesz śledzić wszystkie zmiany wprowadzone w API w [dzienniku zmian API](/manual/api/changes). ::: [comment]: # ({/0de672ce-c1074d48}) [comment]: # ({77690bd2-dfd7315f}) ### Dalsza lektura Masz już wystarczającą wiedzę, aby rozpocząć pracę z API Zabbix, jednak nie poprzestawaj na tym. W ramach dalszej lektury zalecamy zapoznanie się z [listą dostępnych API](/manual/api/reference). [comment]: # ({/77690bd2-dfd7315f})