Руководство по использованию локальных API OvoBrowser

Локальный API ovoBrowser используется для управления средой браузера, группировкой, метками, прокси - серверами, станциями переработки и процессами браузера на вашем компьютере. Интерфейс только для прослушивания.127.0.0.1Не требуется токен, токен Bearer илиx-api-keyА.

1. Способ открытия производства

Автозапуск рабочего стола

После успешного входа в учетную запись локальный API запускается автоматически и сохраняет текущий порт. Следующий сеанс сохранения будет автоматически запущен после успешного восстановления. Адрес по умолчанию:

http://127.0.0.1:50325

Фактический порт основан на странице клиента « API & MCP». Google、GitHub、 Как пароль учетной записи, так и регистрация приглашений в конечном итоге создают один и тот же сеанс входа, поэтому после успешного входа в учетную запись запускается локальный API.

Если служба останавливается вручную в клиенте, текущий порт немедленно закрывается; При следующем успешном входе в систему или восстановлении сеанса он будет запущен автоматически.

Модель CLI

Сначала успешно войдите в систему на рабочем столе и сохраните статус входа, а затем выполните:

& "C:\Program Files\ovoBrowser\ovoBrowser.exe" --cli --api-port 50325

Путь программы зависит от фактического места установки.--api-portМожет быть опущен, когда используется сохраненный порт. CLI повторно использует сеансы учетной записи в безопасном хранилище операционной системы и не получает пароль учетной записи командной строки или токен.

« Сохранение состояния входа» означает, что на рабочем столе не нажимается кнопка « Выход из входа», и сеанс сохранения остается в силе. При выходе из системы, истечении срока действия сеанса или удалении данных приложения необходимо вновь открыть вход на рабочем столе; Войти в Google / GitHub также можно на рабочем столе.

2. Правила вызова

• Все интерфейсы используются.POSTПараметры размещены в JSON Body.

• Использовать заголовок запросаContent-Type: application/jsonА.

• Местоположение окружающей среды рекомендуется использоватьidБольшинство интерфейсов также поддерживаютseqЭкологический серийный номер.

• Параметры страницыpageотНольНачать,pageSizeСфера охвата1 - 100А.

• Учетные записи, файлы cookie, ключи 2FA и прокси - пароли являются конфиденциальной информацией и не записываются в публичный журнал.

Успешный ответ:

{"success":true,"data":{}}

Неудачный ответ:

{"success":false,"msg":"失败原因"}

3. Общий обзор интерфейса

4. Медицинские осмотры

curl --location 'http://127.0.0.1:50325/health' \
  --header 'Content-Type: application/json' \
  --data '{}'

возвращатьсяdata.running=trueПоказывает, что порт запущен. Повторный вызов списка среды подтверждает, что сеанс учетной записи и рабочая область восстановлены.

5. Групповой API

Кластеры используются для отдельных категорий: среда принадлежит максимум одной группе, черезgroupIdСвязь.

Список групп

curl --location 'http://127.0.0.1:50325/group/list' \
  --header 'Content-Type: application/json' \
  --data '{}'

data.listЭто кластерный массив,_count.profilesКоличество окружающей среды в подгруппе.

Дополнительные группы

curl --location 'http://127.0.0.1:50325/group/create' \
  --header 'Content-Type: application/json' \
  --data '{"name":"电商账号","color":"#3478F6"}'

Редактировать группу

idиgroupIdОба поля могут использоваться для указания группы. Помимо поля идентификации передавайте только поля, значения которых необходимо изменить.

curl --location 'http://127.0.0.1:50325/group/update' \
  --header 'Content-Type: application/json' \
  --data '{"id":"分组ID","name":"重要电商账号","color":"#16A34A"}'

Удалить группу

curl --location 'http://127.0.0.1:50325/group/delete' \
  --header 'Content-Type: application/json' \
  --data '{"id":"分组ID"}'

Удаление группы не удаляет окружения, окружения исходной группы будут перемещены в раздел «Без группы». Системную группу по умолчанию удалить нельзя.

6. Метки API

Метки используются для многовыборочных меток: среда связывает до 20 метокtagIdsСвязь массивов.

Список меток

curl --location 'http://127.0.0.1:50325/tag/list' \
  --header 'Content-Type: application/json' \
  --data '{}'

Добавить метку

curl --location 'http://127.0.0.1:50325/tag/create' \
  --header 'Content-Type: application/json' \
  --data '{"name":"高优先级","color":"#F97316"}'

Изменить вкладку

curl --location 'http://127.0.0.1:50325/tag/update' \
  --header 'Content-Type: application/json' \
  --data '{"id":"标签ID","name":"VIP","color":"#A855F7"}'

Удалить метку

curl --location 'http://127.0.0.1:50325/tag/delete' \
  --header 'Content-Type: application/json' \
  --data '{"id":"标签ID"}'

Удаление метки снимет ее связь со всеми средами, но не удалит среду.

7. Агентский API

Окружающая среда может сначала создать многоразовый агент, а затем передатьproxyIdОн также может быть передан непосредственно при создании или обновлении среды.proxyОба способа нельзя использовать одновременно.

Список агентов

curl --location 'http://127.0.0.1:50325/proxy/list' \
  --header 'Content-Type: application/json' \
  --data '{"page":0,"pageSize":10,"search":""}'

Ответ Вернуть текущий пароль проксиpasswordиhasPasswordНе возвращает конфиденциальный текст сервера.

Дополнительные агенты

curl --location 'http://127.0.0.1:50325/proxy/create' \
  --header 'Content-Type: application/json' \
  --data '{
    "name":"Tokyo Proxy",
    "protocol":"SOCKS5",
    "host":"proxy.example.com",
    "port":1080,
    "username":"proxy-user",
    "password":"proxy-password"
  }'

Редактировать прокси

idиproxyIdВсе они могут найти агента. ПропуститьpasswordСохранить оригинальный пароль, передатьnullОчистить пароль.

curl --location 'http://127.0.0.1:50325/proxy/update' \
  --header 'Content-Type: application/json' \
  --data '{"id":"代理ID","host":"new-proxy.example.com","port":1080,"password":"new-password"}'

После изменения протокола, хоста, порта, имени пользователя или пароля состояние обнаружения будет сброшено какUNCHECKEDА.

8. Создание среды

Полное описание поля

accountsКаждый пункт:

ИнтранетproxyА.

Полное создание примеров

curl --location 'http://127.0.0.1:50325/browser/create' \
  --header 'Content-Type: application/json' \
  --data '{
    "name":"完整环境示例",
    "platform":"windows",
    "remark":"通过本地 API 创建",
    "groupId":"分组ID",
    "tagIds":["标签ID1","标签ID2"],
    "accounts":[
      {
        "platform":"google",
        "username":"[email protected]",
        "password":"account-password",
        "totpSecret":null,
        "openOnStart":true,
        "remark":"主账号"
      }
    ],
    "cookies":[
      {
        "name":"session_id",
        "value":"cookie-value",
        "domain":".example.com",
        "path":"/",
        "secure":true,
        "httpOnly":true,
        "sameSite":"Lax"
      }
    ],
    "startupUrls":[
      "https://example.com/login",
      "https://example.com/dashboard"
    ],
    "fingerprint":{
      "timezone":"Asia/Shanghai",
      "acceptLanguage":"zh-CN,zh,en"
    },
    "proxy":{
      "type":"HTTP",
      "host":"proxy.example.com",
      "port":8080,
      "username":"proxy-user",
      "password":"proxy-password"
    }
  }'

При использовании существующего прокси - сервера удалитьproxyВесь абзац, переадресовать"ПроксиИд": "Уже есть Agent ID". Когда агент не используется,proxyиproxyIdДаже не передавайте.

Формат cookie

Рекомендуется использоватьcookiesПрямой доступ к массиву JSON. Часто используемые поля cookie:name、value、domain、path、secure、httpOnly、expirationDate、sameSiteА.

Если используетсяcookieDataЭто должна быть строка, воспроизводимая расширением браузера для экспорта текста JSON, Netscapecookies.txt& Запросить заголовок текстаa=1; b=2А.

нетdomainПри запуске файлов cookie доменное имя может быть экстраполировано только на основе первого инициализированного веб - сайта, рекомендуется явное заполнениеdomainА.

9. Обновление окружающей среды

Интерфейс обновления изменяет только отправленные поля; Пропущенное поле остается неизменным. Поддержка определения местоположенияid、profileId、seq、serialNumberАserial_numberА.

Правила перезаписи:

• accountsВся группа покрыта,[]Очистить все счета;

• tagIdsВся группа покрыта,[]Очистить все этикетки;

• cookiesИлиcookieDataЗамена cookie,nullОчистить;

• startupUrlsЗамена всех загрузочных сайтов,[]Очистить;

• groupId:nullУдалить группировку;

• proxy:nullИлиproxyId:nullОсвободить агента.

curl --location 'http://127.0.0.1:50325/browser/update' \
  --header 'Content-Type: application/json' \
  --data '{
    "id":"环境ID",
    "name":"更新后的环境",
    "remark":"完整更新示例",
    "groupId":"分组ID",
    "tagIds":["标签ID"],
    "accounts":[
      {
        "platform":"google",
        "username":"[email protected]",
        "password":"new-password",
        "openOnStart":false
      }
    ],
    "cookies":[
      {
        "name":"session_id",
        "value":"new-cookie-value",
        "domain":".example.com",
        "path":"/"
      }
    ],
    "startupUrls":["https://example.com/dashboard"],
    "proxyId":"已有代理ID"
  }'

Изменить текущую среду прокси, Cookie、 После запуска веб - сайта или отпечатков пальцев сначала закройте среду, а затем снова откройте.

10. Окружающая среда запросов

Список окружающей среды

curl --location 'http://127.0.0.1:50325/browser/list' \
  --header 'Content-Type: application/json' \
  --data '{"page":0,"pageSize":10,"name":"","groupId":"分组ID","tagId":"标签ID"}'

Поле фильтра, которое не требуется, удаляется напрямую.data.listЭто экологический массив,data.totalNumЭто общее количество; Объекты окружающей среды включаютgroupиtagsА.

Экологические подробности

curl --location 'http://127.0.0.1:50325/browser/detail' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID"}'

Подробнее Вернутьсяgroup、tags、fingerprint、proxy、accountCount、hasCookieData.Владельцы окружающей среды также получатcookieDataА.

11. Удаление, рециркуляция и полное удаление

Удалить окружающую среду на станцию

curl --location 'http://127.0.0.1:50325/browser/delete' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID"}'

Если среда работает, сначала закройте браузер, а затем перейдите на станцию переработки. Эта операция может быть восстановлена.

Список рекуперационных станций

curl --location 'http://127.0.0.1:50325/browser/recycle/list' \
  --header 'Content-Type: application/json' \
  --data '{"page":0,"pageSize":10,"search":"","sort":"desc"}'

Окружающая среда в спискеidМожет использоваться для восстановления или полного удаления.

Восстановление окружающей среды

curl --location 'http://127.0.0.1:50325/browser/restore' \
  --header 'Content-Type: application/json' \
  --data '{"id":"回收站环境ID"}'

Для восстановления необходимо использовать идентификатор окружающей среды, а не просто передавать серийный номер окружающей среды.

Полностью удалить окружающую среду

Индивидуально:

curl --location 'http://127.0.0.1:50325/browser/delete/permanent' \
  --header 'Content-Type: application/json' \
  --data '{"id":"回收站环境ID"}'

Серия:

curl --location 'http://127.0.0.1:50325/browser/delete/permanent' \
  --header 'Content-Type: application/json' \
  --data '{"ids":["环境ID1","环境ID2"]}'

idsМаксимум 500. Они просто удаляют окружающую среду, которая уже находится на перерабатывающей станции,data.purgedФактическое количество удалений.

Полное удаление невосстановимо, конфигурация среды, учетная запись и файлы cookie удаляются навсегда.

12. Окружающая среда открытия, запроса и закрытия

Открыть окружение

curl --location 'http://127.0.0.1:50325/browser/open' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID","headless":false}'

headlessЭто должно быть логическое значение JSON. Возвращение ответаpid、wsАhttp、headless*wsМожно использовать Playwright или Puppeteer.

Состояние работы

curl --location 'http://127.0.0.1:50325/browser/active' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID"}'

Безпараметрический вызов/browser/activeВозвращение в полную операционную среду. Запуск списка:

curl --location 'http://127.0.0.1:50325/browser/running' \
  --header 'Content-Type: application/json' \
  --data '{}'

Порты PID и CDP

curl --location 'http://127.0.0.1:50325/browser/pids' \
  --header 'Content-Type: application/json' \
  --data '{"ids":["环境ID1","环境ID2"]}'

curl --location 'http://127.0.0.1:50325/browser/pids/all' \
  --header 'Content-Type: application/json' \
  --data '{}'

curl --location 'http://127.0.0.1:50325/browser/ports' \
  --header 'Content-Type: application/json' \
  --data '{}'

Закрыть окружающую среду

curl --location 'http://127.0.0.1:50325/browser/close' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID"}'

Закрыть все:

curl --location 'http://127.0.0.1:50325/browser/close/all' \
  --header 'Content-Type: application/json' \
  --data '{}'

Закрытие всех повлияет на все текущие рабочие окна, сохраните содержимое страницы перед выполнением.

13 Использование Postman

Импорт в Центр помощи https://www.postman.com/ovo-desktop-api/workspace/ovodesktop-api-example/collection/57777046-8485fa5f-3e60-4da9-8b59-538ae4703339?action=share&source=copy-link&creator=57777046.

1. Подтверждение в коллекции VariablesbaseUrl*

2. Запуск « проверки здоровья»;

3. Запустить « Список среды» для подтверждения восстановления сеанса;

4. Каждый запрос содержит описание использования, описание поля, полный пример JSON Body и cURL;

5. Если вам нужна полная демонстрация, запустите ее в порядке папки, не нужно понимать серийный номер среды или вручную поддерживать сложные переменные;

6. Перед выполнением « среды полного удаления» убедитесь, что целью является тестовая среда, которая позволяет постоянно удалять.

14. Частые ошибки