API

Omówienie

API Zabbix umożliwia programowe pobieranie i modyfikowanie konfiguracji Zabbix oraz zapewnia dostęp do danych historycznych. Jest szeroko używane do:

• Tworzenia nowych aplikacji współpracujących z Zabbix.
• Integracji Zabbix z oprogramowaniem firm trzecich.
• Automatyzacji rutynowych zadań.

API Zabbix jest API opartym na HTTP i jest dostarczane jako część 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 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 szeregu metod, które nominalnie są pogrupowane w oddzielne API. Każda z metod wykonuje jedno konkretne zadanie. Na przykład metoda host.create należy do host API i służy do tworzenia nowych hostów. Historycznie API bywają czasami określane jako „klasy”.

Większość API zawiera co najmniej cztery metody: get, create, update i delete, służące odpowiednio do pobierania, tworzenia, aktualizowania i usuwania danych, ale niektóre API mogą udostępniać zupełnie inny zestaw metod.

Wykonywanie żądań

Po skonfigurowaniu frontend możesz używać zdalnych żądań HTTP do wywoływania API. Aby to zrobić, należy wysyłać żądania HTTP POST do pliku api_jsonrpc.php znajdującego się w katalogu frontend.
Na przykład, jeśli 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:

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

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
}

Z kolei obiekt odpowiedzi 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.

Uwierzytelnianie

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

• Użyć istniejącego tokenu API utworzonego w frontendzie Zabbix, w sekcji Users > API tokens, albo utworzonego za pomocą Token API.
• Użyć tokenu uwierzytelniającego uzyskanego metodą user.login.

Na przykład, jeśli chcesz uzyskać nowy token uwierzytelniający, logując się jako standardowy użytkownik Admin, żądanie JSON wyglądałoby 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 dane uwierzytelniające zostały podane poprawnie, 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).

Przykładowy przepływ pracy

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

Pobieranie hostów

Teraz masz prawidłowy token uwierzytelniania użytkownika (reprezentowany 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óre można wykorzystać do odwoływania się do niej w kolejnych żądaniach:

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

Tworzenie wielu wyzwalaczy

Zatem, jeśli metody tworzenia akceptują tablice, możesz dodać wiele wyzwalaczy, na przykład ten:

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":"Processor load is too high on {HOST.NAME}","expression":"last(/Linux server/system.cpu.load[percpu,avg1])>5"},{"description":"Too many processes on {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
}

Aktualizacja 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
}

Aktualizacja 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óbowaliście, działało poprawnie. Ale co się stanie, jeśli spróbujesz 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ótki opis błędu;
• data - bardziej szczegółowy komunikat o błędzie.

Błędy mogą występować w różnych przypadkach, na przykład przy użyciu nieprawidłowych wartości wejściowych, przekroczeniu limitu czasu sesji lub próbie dostępu do nieistniejących obiektów. Twoja aplikacja powinna umieć w sposób elegancki obsługiwać tego typu 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 zależnych od wersji.

Zabbix gwarantuje zgodność wsteczną funkcji w obrębie głównej wersji. W przypadku wprowadzania zmian niezgodnych wstecznie między głównymi wydaniami, Zabbix zwykle oznacza stare funkcje jako przestarzałe w następnym wydaniu, a usuwa je dopiero w wydaniu po nim. Zdarza się jednak, że Zabbix usuwa funkcje między głównymi wydaniami bez zapewnienia jakiejkolwiek zgodności wstecznej. Ważne jest, aby nigdy nie polegać na żadnych przestarzałych funkcjach i jak najszybciej migrować do nowszych alternatyw.

Dalsza lektura

Teraz masz już wystarczającą wiedzę, aby rozpocząć pracę z Zabbix API, jednak nie zatrzymuj się na tym. W celu dalszej lektury zalecamy zapoznanie się z listą dostępnych API.