[comment]: # aside:3

[comment]: # ({d1748010-ebcec779})
# Использование Zabbix API

[zabbix\_utils](https://github.com/zabbix/python-zabbix-utils/blob/main/README.md) позволяет использовать [Zabbix API](/manual/api) для управления объектами Zabbix, включая создание узлов сети, обновление элементов данных, получение событий и многое другое.

Запросы API можно выполнять в синхронном или асинхронном режиме:

-   В синхронном режиме ваш скрипт Python отправляет запрос и ожидает ответа, прежде чем продолжить выполнение, что подходит для простых, последовательных и предсказуемых операций.
-   В асинхронном режиме скрипт отправляет запросы, не ожидая каждого ответа, что позволяет выполнять другие операции параллельно; это эффективнее для медленных запросов или больших пакетов данных.

Примеры на этой странице ориентированы на синхронный режим, хотя [асинхронный режим](#asynchronous-mode) использует похожие подходы.
Дополнительные примеры доступны в репозитории GitHub [zabbix_utils](https://github.com/zabbix/python-zabbix-utils/tree/main/examples).

[comment]: # ({/d1748010-ebcec779})

[comment]: # ({3d27f26b-8304e91c})
#### Импорт

Чтобы использовать zabbix\_utils для работы с Zabbix API, импортируйте класс `ZabbixAPI` в свой скрипт:

```python
from zabbix_utils import ZabbixAPI
```

::: noteclassic
Если вы уже используете [библиотеку Python из сообщества](https://www.zabbix.com/integrations/python), обычно можно заменить этот импорт на `ZabbixAPI` из zabbix\_utils.
:::

[comment]: # ({/3d27f26b-8304e91c})

[comment]: # ({55f43c13-2fe24fc5})
#### Вход в систему

Перед выполнением запросов к API необходимо создать экземпляр `ZabbixAPI` и выполнить вход в Zabbix API.

Выберите метод, который лучше всего соответствует тому, как вы управляете учетными данными.
Вы можете использовать имя пользователя и пароль или [API tokens](/manual/web_interface/frontend_sections/users/api_tokens).

[comment]: # ({/55f43c13-2fe24fc5})

[comment]: # ({eecbd507-f5ed9f85})
##### Во время инициализации

При создании экземпляра `ZabbixAPI` вы можете сразу указать URL веб-интерфейса Zabbix и свои учетные данные:

```python
# Имя пользователя и пароль:
api = ZabbixAPI(url="127.0.0.1/zabbix", user="Admin", password="zabbix")

# Токен API:
api = ZabbixAPI(url="127.0.0.1/zabbix", token="your_api_token")
```

Если вы предпочитаете группировать параметры подключения, вы можете передать их в виде словаря Python и распаковать его с помощью синтаксиса именованных аргументов Python:

```python
ZABBIX_AUTH = {
    "url": "127.0.0.1/zabbix",
    "user": "Admin",
    "password": "zabbix"
}

api = ZabbixAPI(**ZABBIX_AUTH)
```

[comment]: # ({/eecbd507-f5ed9f85})

[comment]: # ({5cb46e5e-3bf35a85})
##### Использование `login()`

Сначала можно создать экземпляр `ZabbixAPI`, указав только URL веб-интерфейса Zabbix, а затем использовать метод `login()` со своими учетными данными:

```python
# Имя пользователя и пароль:
api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(user="Admin", password="zabbix")

# Токен API:
api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(token="your_api_token")
```

[comment]: # ({/5cb46e5e-3bf35a85})

[comment]: # ({ff280370-a8fe2b33})
##### Использование переменных среды

Сначала вы можете сохранить свои учетные данные в переменных среды, например, с помощью терминала:

```bash
# Имя пользователя и пароль:
export ZABBIX_USER="Admin"
export ZABBIX_PASSWORD="zabbix"

# Токен:
export ZABBIX_TOKEN="your_api_token"
```

Затем, если вы запустите свой скрипт из той же сессии терминала, экземпляру `ZabbixAPI` в скрипте потребуется только URL веб-интерфейса Zabbix:

```python
api = ZabbixAPI(url="127.0.0.1/zabbix")
```

Вы также можете сохранить URL в переменной среды:

```bash
# Имя пользователя и пароль:
export ZABBIX_USER="Admin"
export ZABBIX_PASSWORD="zabbix"
export ZABBIX_URL="https://127.0.0.1/zabbix"

# Токен:
export ZABBIX_TOKEN="your_api_token"
export ZABBIX_URL="https://127.0.0.1/zabbix"
```

Когда URL и учетные данные заданы как переменные среды, экземпляру `ZabbixAPI` в скрипте не требуется никаких аргументов:

```python
api = ZabbixAPI()
```

[comment]: # ({/ff280370-a8fe2b33})

[comment]: # ({b539ed93-326ac077})
#### Выход из системы

Если вы вошли в систему, используя имя пользователя и пароль, вызовите метод `logout()` после завершения операций с API:

```python
from zabbix_utils import ZabbixAPI

api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(user="Admin", password="zabbix")

# API actions go here

api.logout()
```

::: noteclassic
При использовании токенов API вызывать метод `logout()` не требуется.
:::

[comment]: # ({/b539ed93-326ac077})

[comment]: # ({a94d5334-e970d222})
#### API-запросы

После входа в систему вы можете выполнять любые API-запросы, вызывая методы, описанные в [справочнике методов](/manual/api/reference) Zabbix API.

Методы API вызываются в следующем формате:

```python
api_instance.zabbix_object.method(parameters)
```

::: noteclassic
Некоторые имена методов или объектов Zabbix API используют слова, которые являются зарезервированными ключевыми словами в Python (например, `import`).
Чтобы избежать ошибок Python, добавляйте символ подчеркивания к имени метода или объекта при использовании его в Python (например, `api.configuration.import_`).
:::

Например, чтобы получить список узлов сети с помощью [`host.get`](/manual/api/reference/host/get):

```python
# 1. Импортируйте ZabbixAPI из zabbix_utils:
from zabbix_utils import ZabbixAPI

# 2. Создайте экземпляр ZabbixAPI и выполните вход:
api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(user="Admin", password="zabbix")

# 3. Получите узлы сети, соответствующие фильтру:
hosts = api.host.get(
    filter={
        "host": [
            "Zabbix server",
            "Linux server"
        ]
    }
)

# 4. Переберите возвращенные узлы сети и выведите сведения о каждом узле:
for host in hosts:
    print(host)

# 5. Выйдите из API, чтобы закрыть сеанс:
api.logout()
```

[comment]: # ({/a94d5334-e970d222})

[comment]: # ({7b3e3f97-0e327592})
##### Асинхронный режим

Асинхронный режим позволяет вашему скрипту отправлять API-запросы, не дожидаясь завершения каждого из них.
Это может сделать ваш скрипт более эффективным, когда ему нужно выполнить много API-запросов или когда некоторые запросы занимают много времени.

При использовании асинхронного режима есть важные отличия по сравнению с синхронным режимом:

-   Импортируйте модуль Python `asyncio` (сначала необходимо [установить](/devel/python/install) требуемые зависимости).
-   Импортируйте `AsyncZabbixAPI` вместо `ZabbixAPI`.
-   Пишите код внутри функции `async`.
-   Используйте `await` при вызове методов API, включая `login()` и `logout()`.

::: noteimportant
При создании экземпляра `AsyncZabbixAPI` вы не можете выполнить вход [во время инициализации](#during-initialization).
:::

Например, чтобы увидеть список узлов сети с помощью [`host.get`](/manual/api/reference/host/get) в асинхронном режиме:

```python
# 1. Import asyncio for asynchronous mode, and AsyncZabbixAPI from zabbix_utils:
import asyncio
from zabbix_utils import AsyncZabbixAPI

# 2. Define the main async function where all API operations will run:
async def main():

    # 3. Create an AsyncZabbixAPI instance and log in (must await):
    api = AsyncZabbixAPI(url="127.0.0.1")
    await api.login(user="User", password="zabbix")

    # 4. Retrieve hosts matching a filter (must await):
    hosts = await api.host.get(
        filter={
            "host": [
                "Zabbix server",
                "Linux server"
            ]
        }
    )

    # 5. Iterate over returned hosts and print each host's details:
    for host in hosts:
        print(host)

    # 6. Log out from the API to close the session (must await):
    await api.logout()

# 7. Run the async main() function using asyncio's event loop:
asyncio.run(main())
```

[comment]: # ({/7b3e3f97-0e327592})

[comment]: # ({57854c72-5dc3bb95})
#### Примеры

Следующие примеры показывают распространенные задачи Zabbix API с использованием библиотеки zabbix\_utils.

Дополнительные примеры доступны в каталоге `examples` репозитория [zabbix_utils](https://github.com/zabbix/python-zabbix-utils) на GitHub.

[comment]: # ({/57854c72-5dc3bb95})