Управление сессиями облачного браузера: создание, повторное подключение и безопасная остановка
TL;DR
Жизненный цикл сеанса облачного браузера отслеживает управляемый ресурс браузера, независимо от входа на сайт или соединения клиента.
Сохраните UUID v4 requestId и полный текст запроса на создание перед отправкой запроса на создание сеанса.
Повторите неопределенное создание с тем же ID и идентичным телом; измененная конфигурация требует нового ID.
ready означает, что браузер доступен для подключения, а не то, что ваша бизнес-задача успешно выполнена.
Обновление Live View или повторное подключение CDP не сбрасывает срок службы браузера.
Запрос на остановку считается завершенным только когда оригинальный сеанс достигнет состояния ended; состояние stopping является промежуточным.
Что такое жизненный цикл сеанса браузера?
Жизненный цикл сеанса браузера — это последовательность состояний, через которые проходит управляемый браузер от создания до завершения. Он описывает ресурс, который использует ваша автоматизация. Сессия аутентификации на сайте описывает, считает ли конкретный сайт пользователя вошедшим в систему, в то время как соединение клиента CDP описывает, подключена ли в данный момент ваша программа. Эти три жизненных цикла могут завершаться независимо.
Nstdata Cloud Browser предоставляет управляемые облачные браузеры для автоматизации браузеров и ИИ-агентов. Явное управление этим ресурсом позволяет команде восстанавливаться после сбоев работников, координировать передачу человеку и учитывать время выполнения после завершения задачи на странице. Введение в облачный браузер предоставляет контекст продукта; этот гид сосредоточен на владении и переходах состояний, необходимых в реальном выполнении задания.
Например, ваш скрипт может потерять свой WebSocket, в то время как браузер остается готовым и вошедшим в приложение. Напротив, сокет может оставаться подключенным, пока веб-сайт не истечет сессия входа. Один флаг не может точно представлять оба состояния.
Какие состояния должно обрабатывать ваше приложение?
Ваше приложение должно обрабатывать creating, unknown, ready, stopping, ended и failed из поля state ответа на сессию. Не ищите не задокументированное поле status и не пытайтесь выяснить состояние ресурса из превью-изображения.
State
Meaning for the controller
Appropriate next action
creating
Запуск браузера в процессе
Опрашивайте ту же сессию в течение установленного времени
unknown
Текущее состояние ресурса неизвестно
Уточните оригинальную операцию; избегайте дублирования создания
ready
Браузер может принять соединение
Получите учетные данные и проверьте состояние страницы задачи
stopping
Запрос на закрытие был отправлен
Продолжайте проверку на ended
ended
Эта сессия завершена
Не пытайтесь восстановить ее со старыми учетными данными
failed
Ресурс завершил работу с ошибкой
Зафиксируйте контекст ошибки и выполните очистку перед новой попыткой
Текущий Гид по API автоматизации браузера является контрактом для этих значений. Поддерживайте отдельное состояние задачи приложения, такое как ожидание человека, выполнение, принятое или отклоненное. Это ваши собственные состояния задач, а не дополнительные состояния API облачного браузера.
Какие конечные точки и параметры вам нужны?
Вам нужны конечные точки для опций, создания, инспекции, выдачи учетных данных и удаления по адресу https://api.nstdata.io/api/v1/cloud-browser. Получите текущие опции перед созданием тела запроса, так как классы ресурсов, страны и допустимые продолжительности зависят от текущей конфигурации сервиса.
Пример создания также предоставляет targetUrl, recording: false и captchaSolver: { enabled: false }. Просмотрите warnings и effectiveConfiguration из ответа на создание при его настройке. Предупреждение о конфигурации требует проверки, прежде чем задание будет разрешено выполнять значимую работу.
Используйте x-api-key без Bearer для вызовов HTTP жизненного цикла. Получите личный ключ в разделе Settings → Account или ключ члена команды в разделе Members. С личным ключом необязательный x-team-id выбирает присоединенную команду; сохраняйте одно и то же значение для каждого запроса. Учетные данные CDP выдаются отдельно и никогда не должны сохраняться в записи задания.
Как создать и остановить сессию без дублирования?
Создайте и остановите сессию безопасно, сохраняя запрашиваемый запрос до создания, удерживая возвращенный идентификатор сессии и рассматривая завершение работы как подтвержденный переход состояния. Этот пример намеренно разделяет команды, чтобы прерванный работник мог возобновить свое существующее намерение.
Шаг 1: Подготовка проекта Node.js
Используйте Node.js 22.12 или более позднюю версию и создайте рабочую директорию. Контроллер жизненного цикла использует встроенные API Node и не устанавливает клиент браузера.
mkdir browser-lifecycle-demo
cd browser-lifecycle-demo
Создайте приватный файл .env, содержащий NSTDATA_API_KEY и, только если необходимо, NSTDATA_TEAM_ID. Исключите .env и созданную запись работы из системы контроля версий. Запускайте каждую работу в своей директории или выберите отдельный путь JOB_FILE.
Шаг 2: Сохраните HTTP-хелпер
Сохраните этот модуль как cloud-api.mjs. Он проверяет конверт ответа и избегает вывода сырых сообщений сервера, которые могут содержать конфиденциальные данные. AbortSignal timeout Node ограничивает каждый запрос независимо от времени жизни браузера.
Предварительное условие для учетных данных: эти HTTP-запросы требуют бизнес-ключа Nstdata. Поведение API было проверено в соответствии с текущей документацией и синтетическими тестами перехода состояния; эта статья не утверждает, что она выполняется с управляемой учетной записью в реальном времени.
const root ='https://api.nstdata.io/api/v1/cloud-browser';exportasyncfunctionapi(method, path, body){const key = process.env.NSTDATA_API_KEY;if(!key)thrownewError('Set NSTDATA_API_KEY');const headers ={'x-api-key': key };if(process.env.NSTDATA_TEAM_ID) headers['x-team-id']= process.env.NSTDATA_TEAM_ID;if(body) headers['content-type']='application/json';let response;try{ response =awaitfetch(root + path,{ method, headers,redirect:'error',body: body ?JSON.stringify(body):undefined,signal:AbortSignal.timeout(20_000),});}catch{throwObject.assign(newError('API transport failed; reconcile the original operation'),{retryable:true});}const retryable = response.status===429|| response.status>=500;let result;try{ result =await response.json();}catch{throwObject.assign(newError('Invalid API JSON'),{ retryable });}if(!response.ok|| result.err===true|| result.success===false){throwObject.assign(newError(`Cloud Browser API HTTP ${response.status}`),{ retryable });}if(!result.data)thrownewError('Missing API data');return result.data;}exportasyncfunctionconnection(id){if(!id)thrownewError('Set NSTDATA_SESSION_ID');const path =`/sessions/${encodeURIComponent(id)}`;const session =awaitapi('GET', path);if(session.state!=='ready')thrownewError(`Session is ${session.state}, not ready`);const c =awaitapi('POST', path +'/automation-credentials');if(c.sessionId!== id ||!c.headerName||!c.accessToken||!(Date.parse(c.expiresAt)>Date.now())||newURL(c.cdpUrl).protocol!=='wss:'){thrownewError('Invalid or expired CDP credentials');}return{endpoint: c.cdpUrl,headers:{[c.headerName]: c.headerName.toLowerCase()==='authorization'?`Bearer ${c.accessToken}`: c.accessToken},};}exportasyncfunctionendpoint(){// An isolated local CDP endpoint can test the client without managed credentials.if(process.env.LOCAL_CDP_URL){const url =newURL(process.env.LOCAL_CDP_URL);if(!['127.0.0.1','localhost','[::1]'].includes(url.hostname)){thrownewError('LOCAL_CDP_URL must use loopback');}return{endpoint: url.href,headers:{}};}returnconnection(process.env.NSTDATA_SESSION_ID);}
Шаг 3: Сохраните управляемый контроллер
Сохраните следующий код как lifecycle.mjs. Контроллер создает локальную запись эксклюзивно и отказывается перезаписывать существующее намерение. Его цикл повторной попытки повторно использует сохраненное тело, включая тот же UUID, сгенерированный с помощью Node.js randomUUID.
Предварительное условие для учетных данных: ветка API требует ваш рабочий ключ. Поведение восстановления и повторного создания было протестировано с четко отделенным HTTP-фикстурой, не представленным как вывод службы Nstdata.
import{ randomUUID }from'node:crypto';import{ readFile, writeFile }from'node:fs/promises';import{ setTimeout as delay }from'node:timers/promises';import{ api }from'./cloud-api.mjs';const file = process.env.JOB_FILE||'browser-job.json';constpathFor=id=>`/sessions/${encodeURIComponent(id)}`;constsave=job=>writeFile(file,JSON.stringify(job,null,2),{mode:0o600});asyncfunctionretry(operation){for(let attempt =0;; attempt++){try{returnawaitoperation();}catch(error){if(!error.retryable|| attempt ===2)throw error;awaitdelay(500*2** attempt +Math.random()*250);}}}asyncfunctionwait(id, expected){const deadline =Date.now()+90_000;while(Date.now()< deadline){const session =awaitretry(()=>api('GET',pathFor(id)));if(session.state=== expected)return session;if(['ended','failed'].includes(session.state)){thrownewError(`Session ${session.state}; expected ${expected}`);}awaitdelay(2_000);}thrownewError('State wait expired; inspect the original session');}const command = process.argv[2];if(command ==='create'){const options =awaitapi('GET','/sessions/options');const{ resourceClass, proxyCountry, ttlSeconds }= options.defaults;if(!options.resourceClasses.some(x=> x.value=== resourceClass)||!options.proxyCountries.some(x=> x.value=== proxyCountry)||!Number.isInteger(ttlSeconds)|| ttlSeconds < options.session.minSeconds|| ttlSeconds > options.session.maxSeconds)thrownewError('Inspect current options');const job ={body:{requestId:randomUUID(),name:'lifecycle-demo', resourceClass, proxyCountry, ttlSeconds,targetUrl:'https://example.com/',recording:false,captchaSolver:{enabled:false}}};awaitwriteFile(file,JSON.stringify(job,null,2),{flag:'wx',mode:0o600});console.log('Saved create intent. Run: node lifecycle.mjs resume');}elseif(['resume','inspect','stop'].includes(command)){const job =JSON.parse(awaitreadFile(file,'utf8'));if(!job.sessionId&& command ==='resume'){const created =awaitretry(()=>api('POST','/sessions', job.body));if(typeof created.sessionId!=='string'||!created.sessionId)thrownewError('Missing sessionId'); job.sessionId= created.sessionId; job.configurationWarningsPresent=Boolean(created.warnings?.length);awaitsave(job);}if(!job.sessionId)thrownewError('Resume the original create intent first');if(command ==='stop'){const current =awaitapi('GET',pathFor(job.sessionId));if(current.state!=='ended')awaitretry(()=>api('DELETE',pathFor(job.sessionId)));awaitwait(job.sessionId,'ended');}elseif(command ==='resume'){awaitwait(job.sessionId,'ready');}const current =awaitapi('GET',pathFor(job.sessionId));console.log(JSON.stringify({sessionId: job.sessionId,state: current.state,configurationWarningsPresent: job.configurationWarningsPresent}));}elsethrownewError('Use create, resume, inspect, or stop');
Step 4: Зафиксируйте одно намерение создания
Запустите команду создания. Она получает действительные параметры по умолчанию и записывает browser-job.json перед любым запросом на создание сессии. Файл является локальной оперативной записью, а не полем API Cloud Browser.
node --env-file=.env lifecycle.mjs create
Команда намеренно не запускает браузер. Проверьте записанный класс ресурса, страну, срок действия и целевой URL перед продолжением. Если на этом этапе необходимо изменить конфигурацию, начните новое намерение с новым файлом задания и идентификатором запроса; не повторно используйте идентификатор, который уже был отправлен в сервис.
Step 5: Возобновите сохраненное намерение
Запустите команду возобновления, чтобы отправить записанный запрос и дождаться состояния ready. Если создание не возвращает используемого результата, исследуйте и возобновите ту же запись, а не удаляйте ее и не запускайте создание снова.
node --env-file=.env lifecycle.mjs resume
Успех печатает оригинальный sessionId и наблюдаемое состояние. Значение configurationWarningsPresent равное true означает, что вам следует проверить конфигурацию создания перед присоединением задачи. Ограниченные повторные попытки примера являются демонстрационной политикой, а не обещанием, что каждая временная ошибка будет восстановлена.
Step 6: Проверьте оригинальную сессию
Используйте команду инспекции, когда работник или клиент CDP отключается. Та же сессия все еще может работать. Если она готова, отдельный автоматизированный клиент может запросить новые учетные данные и вновь обнаружить состояние своей страницы.
node --env-file=.env lifecycle.mjs inspect
Не восстанавливайте действия только из памяти. Определите, завершился ли предыдущий шаг, прежде чем повторять его, особенно если он может отправить форму или создать запись. Руководство по обработке ошибок продакшн-скраперов объясняет, почему такие же политики не нужны для транспортных и бизнес-операционных повторных попыток.
Step 7: Остановите и подтвердите завершение
Запустите команду остановки после вашей задачи или сразу после этого демонстрационного цикла жизни. Она запрашивает удаление при необходимости, ожидает состояния ended и печатает последнее наблюдаемое состояние.
node --env-file=.env lifecycle.mjs stop
Если завершение не может быть подтверждено, сохраните запись задания и проверьте оригинальную сессию в Cloud Browser → Session History. Выброшенная ошибка не должна быть переведена в успешную метрику очистки.
[Screenshot: История сеансов показывает, что оригинальный сеанс завершился, с закрытыми URL-адресами и учетными данными.]
Как Cloud Browser помогает с управлением жизненным циклом?
Nstdata Cloud Browser предоставляет контроллеру явные операции по созданию, инспекции, подключению и остановке сеансов. Панель управления предлагает оператору второй способ проверить ресурсы, когда работник терпит неудачу. Краткосрочные учетные данные автоматизации сохраняют авторизацию подключения отдельно от бизнес-API ключа. Встроенная конфигурация прокси относится к сеансу, а не к каждому клиентскому скрипту. Эти возможности помогают команде реализовать восстановление, но не заменяют ее базу данных задач или правила собственности.
Обнаружение текущей конфигурации: читайте поддерживаемые значения опций вместо развертывания жестко закодированных классов ресурсов или ограничений времени жизни.
Инспектируемое время выполнения: коррелируйте идентификатор сеанса с активным браузером и историей, когда задача прерывается.
Контролируемое подключение: выдавайте учетные данные для подготовленного сеанса и повторно подключайтесь, не предполагая, что новый сеанс содержит старое состояние.
Явное завершение: сделайте подтвержденное завершение частью записи завершения задачи.
Время выполнения браузера, трафик прокси и необязательная деятельность CAPTCHA должны оцениваться отдельно, используя Cloud Browser pricing. Ожидание человека или отладка зависшей страницы могут удерживать браузер активным. Ограничение времени сеанса определяет объем воздействия, но проактивная остановка остается нормальной очисткой.
Сбоев в жизненном цикле производства обычно возникают из-за неопределенного создания, конкурирующих владельцев, прерванной очистки или лечения состояния аутентификации как состояния браузера.
Симптом
Причина
Ответ
Время создания истекло
Ответ мог быть утерян после создания
Сохраните оригинальное тело и идентификатор запроса; согласуйте эту операцию
HTTP 400
Неверная или устаревшая явная конфигурация
Извлеките опции и исправьте поле; используйте новый замысел при изменении конфигурации
HTTP 401/403/470
Несоответствие бизнес-аутентификации или рабочего пространства
Проверьте ключ и согласованный контекст команды
HTTP 409
Конфликтующее состояние или повторно использованный идентификатор с измененными параметрами
Проверьте оригинальную операцию и сеанс
HTTP 429/503
Временные ограничения по мощности или давлению на скорость
Примените ограниченное ожидание к той же операции
Остановка не подтверждена
Завершение задерживается, или контроллер потерял связь
Повторно проверьте тот же сеанс и повысьте до оператора
Локальная JSON-запись достаточна для демонстрации с одним рабочим. Это не распределенная блокировка, транзакционная база данных или безопасный планировщик для нескольких работников. В производстве храните намерение и идентичность сеанса в долговечной записи задач, предоставьте одному контроллеру аренду на изменение браузера и выполняйте согласование незавершенных задач после сбоев.
Не записывайте API-ключи, токены автоматизации, полные URL-адреса CDP или подписанные URL-адреса Live. Руководство OWASP по журналированию поддерживает хранение секретов вне логов. Ограничьте записи задач и диагностику уполномоченными операторами; руководство по инструментам автоматизации браузера полезно при сравнении того, какие ответственности на самом деле имеет фреймворк или управляемое время выполнения.
Что должно подтверждать завершенное задание браузера?
Завершенное задание браузера должно доказать, что его предполагаемый вывод был принят, и его сеанс браузера завершен. Храните эти результаты отдельно, вместе с идентификатором сеанса и неразрешенным состоянием очистки, когда это необходимо. Повторно подключайтесь только к подтвержденному работающему ресурсу, согласуйте неопределенное создание перед повторным созданием и дайте оператору увидеть незавершенную работу. Это практическая основа для управления удаленными сеансами браузера.
Нет. ready означает, что браузер может принять соединение. Ваше приложение должно отдельно проверить страницу и результат задачи.
Q: Могу ли я повторно подключиться после завершения сеанса?
Нет. Завершённую сессию нельзя восстановить путём запроса другого токена CDP. Создайте новую авторизованную задачу и восстановите только явно поддерживаемое состояние приложения.
Q: Должен ли повторный запрос создания генерировать новый идентификатор запроса?
Нет. Повторите то же неуверенное создание с его оригинальным идентификатором и идентичным телом. Изменённая конфигурация или преднамеренно новая задача требуют нового идентификатора.
Q: Является ли вход на сайт тем же самым, что и сессия браузера?
Нет. Сайт управляет сроком действия своей аутентификации независимо от управляемого браузера. Проверьте состояние входа после повторного подключения; не делайте выводов на основе ready.
Q: Заменяет ли продолжительность сессии очистку?
Нет. Продолжительность сессии - это автоматический лимит. Завершите вашу собственную сессию после задачи и подтвердите ended, чтобы избежать ненужного активного времени выполнения.
Q: Достаточен ли локальный файл задания для распределённого сервиса?
Нет. Распределённый сервис требует надёжных записей, контроля конкурентности и процесса согласования. Локальный файл демонстрирует сохранённое намерение, не претендуя на эти производственные гарантии.
Пусть оператор войдет через Live View, прежде чем скрипт проверит ту же вкладку приложения. Определите принадлежность, утверждения учетной записи, границы одобрения и очистку, не встраивая пароль в автоматизацию.
Ivy Lin
Nov. 17th 2026
Запускайте облачные браузеры по запросу
Работайте с отпечатками браузера и CAPTCHA
Автоматизируйте процессы и расширяйте возможности ИИ-агентов
От сбора веб-данных и тестирования до автоматизации с ИИ — запускайте всё в облаке.