Центр помощи

Подключение скрипта к профилю через локальный API

Где работает локальный API, как прочитать его порт и токен, и пять вызовов: запустить профиль, подключить Puppeteer или Playwright по CDP и остановить его.

Пока приложение разблокировано, 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.

Минимальный сценарий

  1. Прочитайте api_port и api_token из папки данных.
  2. POST /api/v1/profiles/{id}/start с заголовком Bearer. Ответ 200 содержит cdpReady и cdpEndpoint, например ws://127.0.0.1:<port>/devtools/browser/<guid>.
  3. Подключитесь: puppeteer.connect({ browserWSEndpoint: cdpEndpoint }) или playwright.chromium.connectOverCDP(cdpEndpoint).
  4. GET /api/v1/profiles/{id}/status возвращает status (idle, running или error) и cdpEndpoint: адрес, который вернул start, или null, если браузер не запущен или start вернул ответ без адреса.
  5. 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.