20 API

Omówienie

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

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

Zabbix API jest API oparte na HTTP i jest dostarczane jako część frontend. Korzysta z protokołu 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 Zabbixa z aplikacjami Python można znaleźć w bibliotece Python dla Zabbixa.

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 do odpowiednio 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": "7.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ć za pomocą nagłówka Authorization w żądaniu:

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

Od Zabbix 7.0.7 nagłówek Authorization jest obsługiwany w żądaniach międzyoriginowych (CORS). Od Zabbix 7.0.11 API Zabbix akceptuje nagłówki bez rozróżniania wielkości liter (np. authorization, Authorization i AUTHORIZATION są traktowane tak samo).

Za pomocą właściwości auth

Żądanie API może być autoryzowane za pomocą właściwości auth.

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"host.get","params":{"output":["hostid"]},"auth":"0424bd59b807674191e7d77572075f33","id":1}'

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 przebieg 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 tej pozycji 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, co próbowaliście, działało poprawnie. Ale co się stanie, jeśli spróbujecie 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ąpić 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 wersji głównej. 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ę, ż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.