[comment]: # ({7cef99ec-92f30379})
# 20. API

[comment]: # ({/7cef99ec-92f30379})

[comment]: # ({d9e959c3-13405b49})
### Обзор

Zabbix API позволяет программно получать и изменять конфигурацию Zabbix, а также предоставляет доступ к историческим данным.
Она широко используется для:

-   создания новых приложений для работы с Zabbix;
-   интеграции Zabbix в стороннее программное обеспечение;
-   автоматизации рутинных задач.

Zabbix API — это API на основе HTTP, и оно поставляется как часть веб-интерфейса.
Оно использует протокол JSON-RPC 2.0, что означает две вещи:

-   API состоит из набора отдельных методов;
-   запросы и ответы между клиентами и API кодируются с использованием формата JSON.

Дополнительные сведения о протоколе и JSON см. в [спецификации JSON-RPC 2.0](http://www.jsonrpc.org/specification) и на [главной странице формата JSON](http://json.org/).

Дополнительные сведения об интеграции функциональности Zabbix в ваши приложения Python см. в [библиотеке Python для Zabbix](/devel/python).

::: noteclassic
Доступ пользователей в Zabbix, включая как конфигурацию, так и исторические данные, зависит от [типа пользователя](/manual/config/users_and_usergroups/permissions#user-types), назначенной [роли пользователя](/manual/config/users_and_usergroups/permissions#user-roles) и [групп пользователей](/manual/config/users_and_usergroups/usergroup).
:::

[comment]: # ({/d9e959c3-13405b49})

[comment]: # ({76e2a1dd-9cb56d09})
### Структура

API состоит из ряда методов, которые условно сгруппированы в отдельные
API. Каждый метод выполняет одну отдельную задачу. Например, метод
`host.create` относится к API *узла сети* и используется для создания
новых узлов сети. Исторически для API иногда используется название «классы».

::: notetip
Большинство API содержит по крайней мере четыре метода:
`get`, `create`, `update` и `delete` для получения, создания, обновления
и удаления данных соответственно, однако некоторые API могут
предоставлять совершенно другой набор методов.
:::

[comment]: # ({/76e2a1dd-9cb56d09})

[comment]: # ({d3a7ab69-9cb2f5ca})
### Выполнение запросов

После настройки веб-интерфейса вы можете использовать удаленные HTTP-запросы для вызова API. Для этого нужно отправлять HTTP POST-запросы к файлу `api_jsonrpc.php`, расположенному в каталоге веб-интерфейса. Например, если ваш веб-интерфейс Zabbix установлен в `https://example.com/zabbix`, HTTP-запрос для вызова метода `apiinfo.version` может выглядеть так:

```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}'
```

Запрос должен содержать заголовок `Content-Type` со значением `application/json-rpc`, `application/json` или `application/jsonrequest`.

Объект запроса должен содержать следующие свойства:

-   `jsonrpc` - версия протокола JSON-RPC, используемая API (Zabbix API реализует версию JSON-RPC 2.0);
-   `method` - вызываемый метод API;
-   `params` - параметры, которые будут переданы методу API;
-   `id` - произвольный идентификатор запроса (если не указан, API рассматривает запрос как [уведомление](https://www.jsonrpc.org/specification#notification)).

Если запрос корректен, ответ, возвращаемый API, должен выглядеть так:

```json
{
    "jsonrpc": "2.0",
    "result": "7.4.0",
    "id": 1
}
```

Объект ответа, в свою очередь, содержит следующие свойства:

-   `jsonrpc` - версия протокола JSON-RPC;
-   `result` - данные, возвращенные методом;
-   `id` - идентификатор соответствующего запроса.

[comment]: # ({/d3a7ab69-9cb2f5ca})

[comment]: # ({c36376e5-ec5a9f60})
### Пример рабочего процесса

В следующем разделе приведено несколько примеров использования более подробно.

[comment]: # ({/c36376e5-ec5a9f60})

[comment]: # ({17ec6118-ef3f5841})
#### Аутентификация

Для доступа к любым данным в Zabbix необходимо:

-   либо использовать существующий [токен API](/manual/web_interface/frontend_sections/users/api_tokens) (созданный в веб-интерфейсе Zabbix или с помощью [Token API](/manual/api/reference/token));
-   либо использовать токен аутентификации, полученный методом [user.login](/manual/api/reference/user/login).

Например, если вы хотите получить новый токен аутентификации, войдя в систему как стандартный пользователь *Admin*, запрос JSON будет наподобие следующего:

```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}'
```

Если вы правильно указали учётные данные, ответ API должен содержать токен аутентификации пользователя:

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

[comment]: # ({/17ec6118-ef3f5841})

[comment]: # ({d920bab8-37011a71})
#### Методы авторизации

[comment]: # ({/d920bab8-37011a71})

[comment]: # ({78bcb6bc-130188f5})
##### Через заголовок "Authorization"

Все запросы к API требуют аутентификации или API-токена.
Вы можете передать учетные данные, используя заголовок Authorization в запросе:

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

::: noteimportant
Если у вас возникают проблемы с аутентификацией, см. [переадресацию заголовка Authorization](/manual/installation/known_issues#authorization-header-forwarding).
:::

API Zabbix принимает заголовки без учета регистра (например, `authorization`, `Authorization` и `AUTHORIZATION` обрабатываются одинаково).

Заголовок Authorization поддерживается в междоменных запросах ([CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)).

[comment]: # ({/78bcb6bc-130188f5})

[comment]: # ({8a583b03-8950965e})
##### По cookie-файлам Zabbix

Cookie *"zbx_session"*  используется для авторизации запроса API из веб-интерфейса Zabbix, выполняемого при помощи JavaScript (из модуля или пользовательского виджета).

[comment]: # ({/8a583b03-8950965e})

[comment]: # ({7f924528-f572ecc2})
#### Получение узлов сети

Теперь у вас есть действительный токен аутентификации пользователя (в примерах ниже он представлен как переменная), который можно использовать для доступа к данным в Zabbix. Например, вы можете использовать метод [host.get](/manual/api/reference/host/get), чтобы получить идентификаторы, имена узлов сети и интерфейсы всех настроенных [узлов сети](/manual/api/reference/host/object):

Запрос:

```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` - это файл, содержащий JSON-запрос. Вместо файла вы можете передать запрос в аргументе `--data`.
:::

data.json

```json
{
    "jsonrpc": "2.0",
    "method": "host.get",
    "params": {
        "output": [
            "hostid",
            "host"
        ],
        "selectInterfaces": [
            "interfaceid",
            "ip"
        ]
    },
    "id": 2
}
```

Объект ответа будет содержать запрошенные данные об узлах сети:

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

::: notetip
Из соображений производительности всегда рекомендуется перечислять свойства объекта, которые вы хотите получить. Таким образом вы избежите получения всех данных.
:::

[comment]: # ({/7f924528-f572ecc2})

[comment]: # ({c9fda4ae-ee2c324f})
#### Создание нового элемента данных

Создайте новый [элемент данных](/manual/api/reference/item/object) на узле сети «Zabbix server», используя данные, полученные из предыдущего запроса`host.get`. Это можно сделать при помощи метода [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}'
```

Успешный ответ будет содержать ID только что созданного элемента данных, который можно использовать для обозначения этого элемента данных в последующих запросах:

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

::: notetip
Метод `item.create`, так же как и другие *методы создания*, может принимать массивы объектов и создавать несколько элементов данных с помощью одного вызова API.
:::

[comment]: # ({/c9fda4ae-ee2c324f})

[comment]: # ({49a2cbe1-5ed44978})
#### Создание нескольких триггеров

Соответственно, если *методы создания* принимают массивы, вы можете добавить
несколько [триггеров](/manual/api/reference/trigger/object), например:


```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":"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}'
```

Успешный ответ будет содержать ID только что созданных триггеров:

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

[comment]: # ({/49a2cbe1-5ed44978})

[comment]: # ({07f914b6-aa174634})
#### Обновление элемента данных

Активируйте элемент данных, указав для «status» значение «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}'
```

Успешный ответ будет содержать ID обновлённого элемента данных:

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

::: notetip
Метод `item.update`, так же как и другие *методы обновления*, тоже может принимать массивы объектов и обновлять несколько элементов данных за один вызов API.
:::

[comment]: # ({/07f914b6-aa174634})

[comment]: # ({bfbd84bd-e217b4a2})
#### Обновление нескольких триггеров

Активируйте несколько триггеров, указав для «status» значение «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}'
```

Успешный ответ будет содержать ID обновлённых триггеров:

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

::: notetip
Это предпочтительный метод обновления. Некоторые методы API, такие как `host.massupdate`, позволяют писать более простой код; однако, не рекомендуется использовать эти методы, так как они будут удалены в будущих релизах.
:::

[comment]: # ({/bfbd84bd-e217b4a2})

[comment]: # ({a9952ff9-7665e280})
#### Обработка ошибок

До этого момента всё, что мы пробовали, работало прекрасно. Но что может случиться, если мы попробуем выполнить некорректный запрос к API? Давайте попробуем создать ещё один узел сети при помощи вызова [host.create](/manual/api/reference/host/create), но не станем указывать обязательный параметр `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}'
```

Тогда ответ будет содержать сообщение об ошибке:

```json
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Invalid params.",
        "data": "No groups for host \"Linux server\"."
    },
    "id": 7
}
```

Если произошла ошибка, то вместо свойства `result`, объект ответа будет содержать свойство `error` со следующими данными:

-   `code` — код ошибки;
-   `message` — короткое описание ошибки;
-   `data` — более подробное сообщение об ошибке.

Ошибки могут возникать в разных ситуациях, таких как некорректные входные значения, превышение времени ожидания сессии или попытка доступа к несуществующим объектам. Ваше приложение должно быть способно корректно обработать такие виды ошибок.

[comment]: # ({/a9952ff9-7665e280})

[comment]: # ({0de672ce-c1074d48})
### Версии API

Чтобы упростить версионность API, начиная с Zabbix 2.0.4, версия API
совпадает с версией самого Zabbix. Вы можете использовать метод
[apiinfo.version](/manual/api/reference/apiinfo/version), чтобы
узнать версию API, с которой вы работаете. Знание версии может
пригодиться для корректировки вашего приложения, чтобы использовать
возможности конкретной версии API.

Zabbix гарантирует обратную совместимость в пределах одной мажорной версии.
При выполнении несовместимых изменений между мажорными выпусками, Zabbix
обычно оставляет старые функции как устаревшие в следующим выпуске, и
удаляет их только в выпуске, следующим за этим. Иногда Zabbix может удалить
функции между мажорными выпусками без предоставления какой-либо обратной
совместимости. Очень важно никогда не полагаться на какие-либо
устаревшие функции и мигрировать на новые альтернативы как можно скорее.

::: notetip
Вы можете следить за всеми изменениями, внесёнными в API,
на странице [журнала изменений API](/manual/api/changes).
:::

[comment]: # ({/0de672ce-c1074d48})

[comment]: # ({77690bd2-dfd7315f})
### Дополнительная литература

Теперь вы знаете достаточно для начала работы с Zabbix API, но не останавливайтесь на данном этапе. Для дальнейшего чтения мы предлагаем вам взглянуть на [список доступных API](/manual/api/reference).

[comment]: # ({/77690bd2-dfd7315f})