Hướng dẫn sử dụng OvoBrowser Local API

OvoBrowser Local API được sử dụng để quản lý môi trường trình duyệt, nhóm, nhãn, proxy, thùng rác và quy trình trình duyệt tại địa phương. Giao diện chỉ nghe127.0.0.1Không cần Token, Bearer Tokenx-api-key。

1. Cách bắt đầu

Khởi động tự động ở cuối màn hình nền

Sau khi đăng nhập tài khoản thành công, API cục bộ sẽ tự động khởi động và lưu cổng hiện tại. Nó cũng sẽ tự động khởi động sau khi khôi phục phiên lưu tiếp theo thành công. Địa chỉ mặc định:

http://127.0.0.1:50325

Cổng thực tế tùy thuộc vào trang "API&MCP" của khách hàng. Google、GitHub、 Đăng nhập mật khẩu tài khoản và đăng ký mời cuối cùng đều thành lập cùng một phiên đăng nhập, cho nên sau khi vào tài khoản thành công đều khởi động API cục bộ.

Nếu dịch vụ được dừng thủ công trong máy khách, cổng hiện tại sẽ đóng ngay lập tức; Nó vẫn sẽ tự động khởi động vào lần đăng nhập tiếp theo hoặc khi phiên tiếp tục thành công.

Mô hình CLI

Bắt đầu bằng cách đăng nhập thành công một lần ở phía máy tính để bàn và duy trì trạng thái đăng nhập, sau đó thực hiện:

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

Đường dẫn chương trình phụ thuộc vị trí cài đặt thực tế.--api-portCó thể bỏ qua và sử dụng cổng đã lưu khi bỏ qua. CLI ghép kênh các phiên tài khoản được lưu trữ an toàn trong hệ điều hành và không nhận mật khẩu tài khoản dòng lệnh hoặc token.

"Keep Login" có nghĩa là không có nhấp chuột để thoát khỏi đăng nhập ở phía máy tính để bàn và phiên lưu vẫn hoạt động. Nếu bạn đã thoát đăng nhập, phiên hết hạn hoặc dữ liệu ứng dụng bị xóa, bạn cần bật lại đăng nhập phía máy tính để bàn; Đăng nhập Google/GitHub cũng được thực hiện ở phía máy tính để bàn.

2. Quy tắc gọi

• Tất cả các interface được sử dụngPOSTTham số được đặt trong JSON Body.

• Sử dụng đầu yêu cầuContent-Type: application/json。

• Định vị môi trường Đề nghị sử dụngidHầu hết các giao diện cũng hỗ trợseqsố môi trường.

• Thông số phân trangpageTừ0Bắt đầu,pageSizePhạm vi là1-100。

• Số tài khoản, cookie, khóa 2FA và mật khẩu proxy là thông tin nhạy cảm và không được ghi vào nhật ký công khai.

Phản hồi thành công:

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

Phản ứng thất bại:

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

3. Tổng quan giao diện

4. Kiểm tra sức khỏe

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

trở vềdata.running=trueNghĩa là cổng đã được khởi động. Gọi lại danh sách môi trường để xác nhận rằng phiên tài khoản và workspace đã được khôi phục.

5. API nhóm

Nhóm được sử dụng để phân loại radio: một môi trường thuộc về tối đa một nhóm, thông quagroupIdRàng buộc.

Danh sách nhóm

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

data.listLà một mảng nhóm,_count.profilesĐó là số lượng môi trường trong một gói.

Nhóm mới

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

Sửa nhóm

idVàgroupIdBạn có thể định vị các nhóm. Ngoài các trường định vị, chỉ các trường cần thay đổi được truyền đi.

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

Xoá nhóm

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

Xóa gói không xóa môi trường, môi trường bên dưới gói ban đầu trở thành không được nhóm. Các gói mặc định của hệ thống không thể bị xóa.

6. Nhãn API

Thẻ được sử dụng cho các thẻ đa lựa chọn: tối đa 20 thẻ được ràng buộc trong một môi trường, thông quatagIdsArray Binding (Ràng buộc mảng)

Danh sách thẻ

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

Thẻ mới

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

Sửa thẻ

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

Xoá thẻ

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

Xóa một nhãn sẽ loại bỏ nó khỏi tất cả các môi trường, nhưng không phải môi trường.

7. Đại lý API

Môi trường có thể tạo proxy tái sử dụng trướcproxyIdBạn cũng có thể truyền trực tiếp khi tạo hoặc cập nhật môi trườngproxyHai cách không thể sử dụng cùng một lúc.

Danh sách đại lý

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

Trả về mật khẩu proxy hiện tạipasswordVàhasPasswordKhông trả lại mật văn phục vụ.

Thêm proxy mới

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"
  }'

Tác nhân biên tập

idVàproxyIdĐều có thể định vị đại lý. Bỏ quapasswordGiữ nguyên mật khẩu, chuyểnnullXóa mật khẩu.

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"}'

Trạng thái phát hiện được đặt lại sau khi thay đổi giao thức, máy chủ, cổng, tên người dùng hoặc mật khẩuUNCHECKED。

8. Tạo môi trường

Mô tả trường đầy đủ

accountsMỗi mục:

Nội tuyếnproxy：

Ví dụ về Complete Creation

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"
    }
  }'

Khi sử dụng một proxy hiện có, xóaproxyToàn bộ đoạn, truyền lại.ProxyId: Proxy ID đã tồn tạiKhi không sử dụng proxy,proxyVàproxyIdĐều không nên truyền.

Định dạng cookie

Đề nghị sử dụngcookiesTruyền trực tiếp mảng JSON. Các lĩnh vực phổ biến của cookie:name、value、domain、path、secure、httpOnly、expirationDate、sameSite。

Nếu sử dụngcookieDataNó phải là một chuỗi, có thể mở rộng trình duyệt để xuất văn bản JSON, Netscapecookies.txthoặc yêu cầu header texta=1; b=2。

không códomainCookie khởi chạy chỉ có thể suy ra tên miền dựa trên địa chỉ web khởi chạy đầu tiên, đề nghị điền rõ ràngdomain。

9. Cập nhật môi trường

Giao diện cập nhật chỉ sửa đổi các trường được gửi; Các lĩnh vực bị bỏ qua vẫn giữ nguyên. Hỗ trợ định vịid、profileId、seq、serialNumber、serial_number。

Quy tắc ghi đè:

• accountsToàn bộ nhóm phủ sóng,[]Xóa sạch toàn bộ tài khoản;

• tagIdsToàn bộ nhóm phủ sóng,[]Xóa toàn bộ nhãn;

• cookieshoặccookieDataThay thế cookie,nullTrống rỗng;

• startupUrlsThay thế toàn bộ địa chỉ khởi động mạng,[]Trống rỗng;

• groupId:nullGiải nhóm;

• proxy:nullhoặcproxyId:nullGiải tán đặc vụ.

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"
  }'

Thay đổi môi trường vận hành, Cookie、 Sau khi bạn khởi chạy địa chỉ web hoặc dấu vân tay, hãy tắt môi trường trước khi mở lại.

10. Yêu cầu môi trường

Danh sách môi trường

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"}'

Các trường lọc không mong muốn được loại bỏ trực tiếp.data.listLà một mảng môi trường,data.totalNumLà tổng số; Các đối tượng môi trường bao gồmgroupVàtags。

Chi tiết môi trường

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

Chi tiết trở lạigroup、tags、fingerprint、proxy、accountCount、hasCookieDataChủ sở hữu môi trường cũng nhận đượccookieData。

11. Xóa, thùng rác và xóa hoàn toàn

Xóa môi trường vào Recycle Bin

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

Nếu môi trường đang chạy, trình duyệt sẽ đóng trước khi chuyển vào thùng rác. Hoạt động này có thể được tiếp tục.

Danh sách thùng rác

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

Môi trường trong danh sáchidCó thể được sử dụng để khôi phục hoặc xóa hoàn toàn.

Phục hồi môi trường

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

Phục hồi phải sử dụng Environment ID và không thể chỉ truyền số sê-ri môi trường.

Xóa hoàn toàn môi trường

Độc thân:

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

Số lượng lớn:

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

idsTối đa 500 chiếc. Chỉ xóa môi trường đã có trong thùng rác,data.purgedLà số lượng xóa thực tế.

Xóa hoàn toàn không thể khôi phục và cấu hình môi trường, tài khoản và cookie sẽ bị xóa vĩnh viễn.

12. Mở, truy vấn và đóng môi trường

Mở môi trường

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

headlessGiá trị Boolean JSON Trả lời returnpid、ws、http、headless；wsCó sẵn cho Playwright hoặc Puppeteer.

Trạng thái hoạt động

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

Gọi không tham số/browser/activeTrở về toàn bộ môi trường chạy. Chạy danh sách:

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

Cổng PID và 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 '{}'

Đóng môi trường

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

Đóng tất cả:

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

Đóng tất cả ảnh hưởng đến tất cả các cửa sổ làm việc hiện tại, hãy lưu nội dung trang trước khi thực hiện.

Sử dụng Postman

Được cung cấp bởi Trung tâm trợ giúp nhập khẩu 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. Xác nhận trong Collection VariablesbaseUrl；

2. Thực hiện "kiểm tra sức khỏe";

3. Chạy danh sách môi trường để xác nhận rằng phiên đã được khôi phục;

4. Mỗi yêu cầu đi kèm với mục đích, mô tả trường, cơ thể JSON đầy đủ và ví dụ cURL;

5. Để trình bày đầy đủ, chạy theo thứ tự thư mục mà không cần phải hiểu số sê-ri môi trường hoặc duy trì các biến phức tạp bằng tay;

6. Trước khi thực hiện "Xóa hoàn toàn môi trường", hãy đảm bảo rằng mục tiêu là cho phép xóa vĩnh viễn môi trường thử nghiệm.

14 Sai lầm thường gặp