18 API

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 oraz na stronie głównej formatu JSON.

Więcej informacji o integrowaniu funkcjonalności Zabbix z aplikacjami Python można znaleźć w bibliotece Python dla Zabbix.

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”.

Wykonywanie żądań

Po skonfigurowaniu frontend możesz używać zdalnych żądań HTTP do wywoływania API. W tym celu 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 Zabbix jest zainstalowany pod adresem https://example.com/zabbix, żądanie HTTP wywołujące metodę apiinfo.version może wyglądać następująco:

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 tych wartości: application/json-rpc, application/json lub application/jsonrequest.

Obiekt żądania musi zawierać następujące właściwości:

• jsonrpc - wersję protokołu JSON-RPC używaną przez API (API Zabbix implementuje JSON-RPC w wersji 2.0);
• method - wywoływaną metodę API;
• params - parametry, które zostaną przekazane do metody API;
• id - dowolny identyfikator żądania (jeśli zostanie pominięty, API traktuje żądanie jako powiadomienie).

Jeśli żądanie jest poprawne, odpowiedź zwrócona przez API powinna wyglądać następująco:

{
    "jsonrpc": "2.0",
    "result": "8.0.0",
    "id": 1
}

Obiekt odpowiedzi z kolei zawiera następujące właściwości:

• jsonrpc - wersję protokołu JSON-RPC;
• result - dane zwrócone przez metodę;
• id - identyfikator odpowiadającego żądania.

Przykładowy przepływ pracy

Poniższa sekcja przeprowadzi Cię przez kilka przykładów użycia bardziej szczegółowo.

Uwierzytelnianie

Aby uzyskać dostęp do jakichkolwiek danych w Zabbix, musisz:

• użyć istniejącego tokenu API (utworzonego w Zabbix frontend lub przy użyciu Token API);
• użyć tokenu uwierzytelniającego uzyskanego za pomocą metody 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:

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:

{
    "jsonrpc": "2.0",
    "result": "0424bd59b807674191e7d77572075f33",
    "id": 1
}

Metody autoryzacji

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:

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer 0424bd59b807674191e7d77572075f33'

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).

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).

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, aby pobrać identyfikatory, nazwy hostów i interfejsy wszystkich skonfigurowanych hostów:

Żądanie:

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

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

{
    "jsonrpc": "2.0",
    "result": [
        {
            "hostid": "10084",
            "host": "Zabbix server",
            "interfaces": [
                {
                    "interfaceid": "1",
                    "ip": "127.0.0.1"
                }
            ]
        }
    ],
    "id": 2
}

Tworzenie nowej pozycji

Teraz utwórz nową pozycję na hoście „Zabbix server”, używając danych uzyskanych z poprzedniego żądania host.get. Można to zrobić za pomocą metody item.create:

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:

{
    "jsonrpc": "2.0",
    "result": {
        "itemids": [
            "24759"
        ]
    },
    "id": 3
}

Tworzenie wielu wyzwalaczy

Jeśli więc metody create akceptują tablice, możesz dodać wiele wyzwalaczy, na przykład takie:

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:

{
    "jsonrpc": "2.0",
    "result": {
        "triggerids": [
            "17369",
            "17370"
        ]
    },
    "id": 4
}

Aktualizowanie pozycji

Włącz pozycję, ustawiając jej status na „0”:

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:

{
    "jsonrpc": "2.0",
    "result": {
        "itemids": [
            "10092"
        ]
    },
    "id": 5
}

Aktualizowanie wielu wyzwalaczy

Włącz wiele wyzwalaczy, ustawiając ich status na „0”:

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:

{
    "jsonrpc": "2.0",
    "result": {
        "triggerids": [
            "13938",
            "13939"
        ]
    },
    "id": 6
}

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, ale pomijając wymagany parametr groups:

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:

{
    "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.

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, 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.

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.