---
title: "Python-скрипты"
id: "2097"
type: "page"
slug: "scripts"
published_at: "2026-09-30T02:42:32+00:00"
modified_at: "2026-10-15T11:19:29+00:00"
url: "https://pastukhov.com/agents/analytics/docs/scripts"
markdown_url: "https://pastukhov.com/agents/analytics/docs/scripts.md"
excerpt: "Analytics Agent можно расширять своими скриптами на Python: они лежат обычными файлами рядом с настройками…"
---

# Python-скрипты

[https://pastukhov.com/agents/analytics/docs/scripts.md](https://pastukhov.com/agents/analytics/docs/scripts.md)

Analytics Agent можно расширять своими скриптами на Python: они лежат обычными файлами рядом с настройками и подключаются к обработке данных. Дорабатывать само приложение не нужно — положили файл, и новая возможность уже работает, без сборки и перезапуска. Скрипт подходит там, где встроенных средств не хватает: подключить сервис, у которого нет готового источника, досчитать или переименовать результаты запроса, посчитать условие тревоги по-своему, отправить уведомление нестандартным способом.

Это возможность для тех, кто готов писать код, — остальные части продукта в скриптах не нуждаются. При этом скрипт не обязан быть сложным: часто это десяток строк.

## Где лежат скрипты

Все скрипты живут в папке `/project/apps/analytics/scripts/` — в том же постоянном томе, что документы и источники данных. Один скрипт — один JSON-файл с настройками:

```
{
  "title": "Заказы из вашей системы",
  "notes": "Что делает скрипт",
  "file": "orders.py",
  "timeoutSec": 120,
  "env": { "CRM_BASE_URL": "https://crm.example.com" },
  "args": { "pageSize": 100 }
}
```

- **код** — либо прямо в файле настроек, либо отдельным файлом `.py` рядом с ним: как удобнее;
- **название и заметки** — чтобы через полгода было понятно, что это и зачем;
- **таймаут** — сколько секунд ждать ответа (по умолчанию 60, потолок — 10 минут);
- **переменные окружения** — постоянные значения для запуска: адреса, ключи доступа. Можно также указать, какие переменные окружения сервера передавать скрипту;
- **аргументы** — готовые значения на каждый запуск; их можно переопределить в конкретном месте подключения.

Библиотеки, которые нужны скриптам, перечисляются в одном общем файле `scripts/requirements.txt`. Окружение Python приложение готовит само при первом запуске — отдельно его настраивать не нужно.

## Четыре точки подключения

Один и тот же скрипт подключается в четырёх местах конвейера аналитики:

- **Источник данных** — запросы к скрипту вместо базы: подойдёт любой сервис, у которого есть клиент на Python. Такой источник работает везде, где работают обычные: в графиках, таблицах, проверках, правилах оповещений и выгрузке в PDF (подробнее — [Источники данных](/agents/analytics/docs/data-sources) );
- **Обработка результата запроса** — скрипт получает готовую таблицу и возвращает её же, но переименованной, отфильтрованной, дополненной или досчитанной (подробнее — [Запросы](/agents/analytics/docs/queries) );
- **Условие тревоги** — свой расчёт прямо в правиле оповещения: сложная формула, внешние данные, модель оценки (подробнее — [Оповещения](/agents/analytics/docs/alerts) );
- **Доставка уведомления** — канал, которого нет среди готовых: скрипт получает текст уведомления и сам решает, куда и как его отправить (подробнее — [Оповещения](/agents/analytics/docs/alerts) ).

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

## Как проходит запуск

- скрипту на вход приходит один документ JSON — точка подключения, данные запроса, аргументы; читается он привычным `json.load(sys.stdin)`;
- ответ — тоже JSON: последний цельный объект, который скрипт напечатал. Сообщения о ходе работы печатать можно — они не мешают;
- у каждого скрипта есть своя рабочая папка, которая сохраняется между запусками: там удобно держать файлы, курсоры и промежуточные результаты;
- размер данных ограничен: если данных много, передавайте не сами данные, а ссылку или файл в рабочей папке;
- одновременных запусков ограниченное число — чтобы скрипты не перегружали сервер.

## Раздел «Скрипты»

В боковой панели есть раздел «Скрипты». Это страница наблюдения за запусками: определения здесь читаются, а не правятся — правка файла и есть изменение.

- состояние среды сверху: готов ли Python, собран ли набор библиотек, сколько запусков и сбоев было за сутки, что случилось в прошлый раз;
- карточки скриптов: название, откуда берётся код, когда запускался в последний раз;
- журнал запусков: время, точка подключения, результат или понятная причина сбоя, фильтры по состоянию и точке;
- тестовый запуск: задали аргументы и данные, нажали «Запустить» — результат тут же появился в журнале, как от обычного запуска;
- журнал хранится заданный срок (по умолчанию 30 дней) и чистится сам.

## Если скрипт сломался

Сбой скрипта никогда не подменяет данные: отчёт, график или тревога показывают понятную ошибку — что именно не получилось (скрипт не найден, превышено время ожидания, ответ не разобран) — и не показывают вместо этого что-то своё. Причина сбоя всегда видна в журнале запусков.

Запуски можно выключить одним переключателем — тогда все точки подключения честно сообщат, что скрипты отключены, а не сделают вид, что всё в порядке. Первый запуск бывает медленным: в этот момент собирается окружение и ставятся библиотеки.

## Граница доверия

Скрипты — это ваш собственный код, и запускаются они с правами приложения: отдельной изоляции между скриптом и сервером нет. Поэтому держите их в Git вместе с проектом, а не запускайте чужие файлы. Если нужна полная изоляция — разворачивайте всё приложение в отдельном контейнере, что и делает стандартная установка.

Ключи и пароли для скриптов хранятся в настройках скрипта обычным текстом, как и пароли подключения к базам, — это стоит учитывать при доступе к папке с настройками.

[← Оглавление документации](/agents/analytics/docs)