Пока приложение разблокировано, Agilelogin запускает на этом компьютере небольшой HTTP API. Скрипт читает порт и токен сеанса из двух файлов, просит API запустить профиль и подключается к запущенному браузеру через Chrome DevTools Protocol (CDP); в статье описан этот путь и то, чего API не делает.
Относится к: launcher 0.1.0, версия API v1. Полный справочник по API будет опубликован после первого выпуска; до тех пор используйте только вызовы, показанные здесь.
Где работает сервис?
- API слушает только
127.0.0.1, на порту, который операционная система случайно выбирает при каждом запуске сервиса. Удалённого доступа нет, как нет и настройки, которая привязала бы его к другому адресу. - При запуске сервис записывает в папку данных приложения два файла, и скрипт читает оба перед каждым подключением:
api_port— номер порта обычным текстом.api_token— токен сеанса из 64 шестнадцатеричных символов, новый при каждом запуске. В Windows он защищён стандартными правами пользователя на%APPDATA%; в macOS файл доступен для чтения только вашему пользователю.
- Папка данных —
%APPDATA%\com.agilelogin.app\в Windows и~/Library/Application Support/com.agilelogin.app/в macOS. - Блокировка приложения, вручную или после 15 минут без ввода, останавливает сервис и удаляет оба файла. Скрипт тогда получает отказ в соединении, а не
401. После разблокировки сервис запускается снова с новым портом и новым токеном, поэтому никогда не кэшируйте их. Блокировка останавливает только этот API: она не закрывает уже запущенные браузеры, и их CDP-подключения продолжают работать. После сбоя оба файла могут остаться на диске и указывать на неработающий порт; если скрипт находит их, но не может подключиться, откройте и разблокируйте приложение. - Каждый маршрут, кроме
GET /api/v1/status, требует заголовокAuthorization: Bearer <contents of api_token>. Если токена нет или он неверный, возвращается401с телом вида{ "error": { "kind": "unauthorized", "message": "…" } }. - Все пути начинаются с
/api/v1. Поля JSON в запросах и ответах записываются в camelCase.
Минимальный сценарий
- Прочитайте
api_portиapi_tokenиз папки данных. POST /api/v1/profiles/{id}/startс заголовком Bearer. Ответ200содержитcdpReadyиcdpEndpoint, напримерws://127.0.0.1:<port>/devtools/browser/<guid>.- Подключитесь:
puppeteer.connect({ browserWSEndpoint: cdpEndpoint })илиplaywright.chromium.connectOverCDP(cdpEndpoint). GET /api/v1/profiles/{id}/statusвозвращаетstatus(idle,runningилиerror) иcdpEndpoint: адрес, который вернулstart, илиnull, если браузер не запущен илиstartвернул ответ без адреса.POST /api/v1/profiles/{id}/stopзакрывает браузер.
От чего зависит этот сценарий:
cdpEndpoint— адрес, который сообщает само ядро; его порт меняется при каждом запуске. Берите его из ответа и никогда не собирайте вручную.startможет вернуть200сcdpReady: falseиcdpEndpoint: null, если браузер запустился, но CDP не был готов примерно за десять секунд. ПроверяйтеcdpReadyперед подключением. ЕслиstartвернулcdpReady: false, опросstatusпозже адреса не даст; остановите профиль и запустите его снова.GET /api/v1/profiles/{id}возвращает профиль безcdpEndpoint; адрес берите изstatus.- У этого API нет событий и WebSocket. Чтобы следить, запущен ли профиль, опрашивайте
status. Единственный WebSocket, который вы используете, принадлежит CDP ядра, а не этому API. - Запуск уже работающего профиля возвращает
422с сообщениемProfile is already running. - При включённой «Блокировке запуска»
startможет вернуть409, если тот же профиль открыт на другом устройстве, где выполнен вход в тот же аккаунт. Сообщение начинается с машиночитаемого префиксаPROFILE_IN_USE_ELSEWHERE:. Блокировка запуска носит рекомендательный характер: она согласует корректно работающих клиентов и не является контролем доступа, а клиент, который не может получить аренду (lease), например без сети, всё равно запускает профиль. GET /api/v1/statusне требует токена и возвращает версию приложения иapiVersion. Используйте его для проверки работоспособности.
Что ещё покрывает API
Стабильно в этом выпуске; полные форматы запросов появятся в справочнике после выхода:
- Профили: список, чтение, изменение и удаление профилей, массовое удаление, подсчёт по состояниям, запуск, остановка и статус. Удаление, по одному или массово, перемещает профиль в корзину приложения; через 30 дней он удаляется навсегда. Новые профили создаются в приложении (см. ниже).
- Прокси: список, создание, массовое создание, изменение и удаление прокси, а также проверка подключения и выходного IP для отдельного прокси.
- Файлы cookie профиля: чтение сводки, очистка, импорт (Netscape, JSON или EditThisCookie), экспорт и копирование в другой профиль.
- Группы: список, создание и удаление.
- Расширения: список и удаление импортированных расширений, импорт расширения из локального пути (crx, zip или распакованная папка), чтение и настройка того, какие расширения загружает профиль.
- Аккаунт: чтение состояния аккаунта, регистрация, вход и выход, список сеансов устройств и их отзыв, запрос письма о пароле, повторная отправка подтверждения и установка пароля. Ответ на вход не содержит ни access-, ни refresh-токена. Вход через Google или GitHub по API недоступен: для него нужен человек за клавиатурой, и он есть только в окне приложения.
Создавайте профили в приложении, а не через API. Каждому профилю нужен собственный отпечаток, а формат отпечатка не публикуется, поэтому у скрипта нет допустимого значения для отправки. POST /api/v1/profiles без fingerprintJson или с пустой строкой, одними пробелами или пустым объектом возвращает 422 с сообщением, которое начинается с FINGERPRINT_REQUIRED:; то же возвращает PATCH /api/v1/profiles/{id}, который задаёт одно из этих значений. PATCH без этого поля сохраняет отпечаток, поэтому отправляйте только изменяемые поля. Массовый импорт через API отклоняет весь пакет, если в строке, создающей профиль, нет отпечатка; массовый импорт в приложении это не затрагивает.
Есть в этом выпуске, но их формат может измениться после первого выпуска, поэтому они перечислены без описания использования: статус ядра, массовый импорт и экспорт (асинхронные, с операцией, которую можно опрашивать или отменить), перенос профилей на другую версию ядра, сброс состояния входа профиля, проверка компьютера на клонирование, конечные точки лицензий, которые приложение использует само, и подготовка компьютера к созданию образа.
Ошибки
- Тело имеет вид
{ "error": { "kind": "<snake_case>", "message": "<English sentence>" } }, а код статуса соответствует категории:400,403,404,409,422,500,502. - Если фреймворк отклоняет запрос до того, как он дойдёт до маршрута, например когда тело JSON не разбирается, ответом будет
422обычным текстом, а не в этом формате. - Сообщения пишутся на английском и не локализуются. Поля тела ошибки могут измениться после первого выпуска.
Что может токен
Локальный процесс, который читает api_token, может делать всё, что может этот API от имени этого компьютера: импортировать и экспортировать файлы cookie, запускать и останавливать браузеры, выполнять вход в аккаунт этого компьютера и выход из него. Граница — права доступа к файлу: в macOS он доступен для чтения только вашему пользователю, в Windows действуют стандартные права %APPDATA% для каждого пользователя. Разрешений для отдельных скриптов нет, токенов только для чтения тоже. Ответ на вход не передаёт access- и refresh-токены, поэтому процесс может действовать от имени этого компьютера, но не может унести учётные данные куда-то ещё.
Чего нет
- Удалённого доступа: сервис слушает
127.0.0.1, и изменить это нельзя. - Облачного API: этот API есть только на компьютере, где установлено приложение. Сервис аккаунтов не предоставляет интерфейс третьим сторонам.
- Push-уведомлений о событиях и WebSocket в этом API.
Вопросы об API присылайте на support@agilelogin.com.