Tự động hóa Octo Browser bằng API — hướng dẫn đầy đủ

API là gì

API (Giao diện Lập trình Ứng dụng) là một giao diện lập trình cho phép các hệ thống phần mềm giao tiếp với nhau. Hãy nghĩ về nó như một nhà hàng: bạn đặt món, người phục vụ mang nó vào bếp, và mang món ăn về. Điều tương tự xảy ra khi ứng dụng của bạn gửi yêu cầu qua API và nhận phản hồi từ máy chủ của Octo Browser.

Các yêu cầu HTTP

Giao tiếp qua API diễn ra thông qua các yêu cầu HTTP — các thông điệp mà một máy khách gửi đến một máy chủ để yêu cầu hoặc chuyển dữ liệu.

Các phương thức HTTP chính

Cấu trúc yêu cầu

Mỗi yêu cầu bao gồm một số thành phần:

• URL: nơi yêu cầu được gửi tới.

• Phương thức: những gì chúng ta muốn thực hiện (GET, POST, v.v.).

• Headers: thông tin yêu cầu bổ sung (ví dụ, một mã thông báo API).

• Body: dữ liệu chúng ta gửi (ví dụ, thông tin cho một hồ sơ mới).

Hãy cùng thực hiện tạo hồ sơ thông qua một yêu cầu POST, Node.js và thư viện Axios. Dưới đây là một kịch bản mẫu:

const axios = require('axios');
const data = JSON.stringify({
  "title": "Test profile from api",
  "fingerprint": {
    "os": "win"
  }
});
const config = {
  method: 'post',
maxBodyLength: Infinity,
  url: 'https://app.octobrowser.net/api/v2/automation/profiles',
  headers: { 
    'Content-Type': 'application/json', 
    'X-Octo-Api-Token': '<GET_TOKEN_IN_CLIENT>'
  },
  data : data
};
axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

URL: 'https://app.octobrowser.net/api/v2/automation/profiles' (điểm cuối API được sử dụng để làm việc với hồ sơ).

Phương thức: 'post' (tạo hồ sơ mới).

Nội dung yêu cầu (dữ liệu): một đối tượng Json chứa các trường cần thiết (tên hồ sơ và Hệ điều hành).

Headers:

• Content-Type': 'application/json' cho máy chủ biết rằng dữ liệu ở định dạng Json.

• 'X-Octo-Api-Token': '<GET_TOKEN_IN_CLIENT>' là mã thông báo API duy nhất có sẵn trong cài đặt tài khoản chính cho Gói đăng kí Base và cao hơn.

Sau khi bạn gửi yêu cầu, máy chủ luôn trả về một phản hồi HTTP bao gồm mã trạng thái — một số ba chữ số chỉ ra kết quả của việc xử lý yêu cầu.

Phản hồi từ máy chủ

• Thành công (2xx):

{"success":true,"msg":"","data":{"uuid":"<profile_uuid>"},"code":null}

• Lỗi (4xx và 5xx):

  • 400 Yêu cầu không hợp lệ — cú pháp không chính xác hoặc thiếu một tham số bắt buộc.

  • 401 Không có quyền — mã thông báo API không hợp lệ hoặc thiếu.

  • 404 Không tìm thấy — URL không tồn tại.

  • 429 Quá nhiều yêu cầu — vượt quá giới hạn yêu cầu.

  • 500 Lỗi máy chủ nội bộ — lỗi từ phía máy chủ.

Khối .catch trong kịch bản giúp xử lý các lỗi này.

Tài liệu API của Octo Browser

Tài liệu API chính thức của Octo Browser bao gồm các cấu trúc yêu cầu và các ví dụ sử dụng:

• Menu bên trái liệt kê các phần như Hồ sơ, Proxy, Local Client API, Đội nhóm và hơn thế nữa.

• Ở trung tâm mô tả yêu cầu: điểm cuối, phương thức (GET, POST, v.v.), tham số, tiêu đề, và các ví dụ sử dụng.

• Bên phải bao gồm các yêu cầu mẫu sẵn và phản hồi từ máy chủ.

• Hiển thị thả xuống danh sách các ngôn ngữ cho phép bạn chọn ví dụ trong Node.js, Python, Java, C#, PHP và các ngôn ngữ khác.

Làm việc với Public và Local API

Public API

• Một giao diện từ xa có sẵn trực tuyến. Không yêu cầu duyệt web phải đang chạy.

• Các yêu cầu được gửi tới: https://app.octobrowser.net.

• Giới hạn phụ thuộc vào gói đăng ký:

Sử dụng Public API, bạn có thể:

• truy xuất thông tin hồ sơ;

• tạo, chỉnh sửa và xóa hồ sơ;

• làm việc với thẻ, đội nhóm, và proxy.

Yêu cầu mẫu: tạo hồ sơ

POST https://app.octobrowser.net/api/v2/automation/profiles

Tiêu đề: X-Octo-Api-Token: <YOUR_API_TOKEN>

Local API

• Hoạt động cục bộ khi Octo Browser đang chạy trên thiết bị.

• Giới hạn phụ thuộc vào loại yêu cầu: Hồ sơ Bắt đầu — 1 yêu cầu, Hồ sơ Một lần — 4 yêu cầu. Tất cả các yêu cầu Local API khác không ảnh hưởng đến giới hạn.

• Bạn có thể đăng nhập, bắt đầu và dừng các hồ sơ, và kết nối các thư viện tự động.

• Các yêu cầu được gửi tới: http://localhost:58888 (58888 là cổng của máy chủ HTTP cục bộ).

Yêu cầu mẫu: khởi động một hồ sơ

POST http://localhost:58888/api/profiles/start

Tiêu đề: Content-Type: application/json và một nội dung Json với UUID và các tham số khác.

Giải pháp cho việc gửi yêu cầu

Postman

1. Tải xuống Postman hoặc sử dụng phiên bản web.

2. Nhập API Octo Browser vào không gian làm việc của bạn bằng cách sử dụng nút Chạy trong Postman.

3. Chọn một yêu cầu (ví dụ, POST Tạo Hồ sơ → Hồ sơ Đơn giản).

4. Chỉ định https://app.octobrowser.net thay cho {{baseUrl}}.
   
   

   

5. Đặt mã thông báo API trong tab Headers.

   

6. Nhập các tham số hồ sơ cần thiết trong tab Body.

   

7. Nhấp vào Gửi để tạo hồ sơ.

Tương tự áp dụng khi bắt đầu một hồ sơ:

1. Chọn yêu cầu POST Bắt đầu Hồ sơ.

2. Chỉ định URL Local API: http://localhost:58888.

3. Tìm UUID hồ sơ dưới “Lịch sử và Khôi phục,” trong bảng hồ sơ hoặc bằng cách sử dụng yêu cầu GET Lấy Hồ sơ.

4. Trong tab Body, đặt các tham số:

• uuid: ID của hồ sơ;

• headless: khởi động không có giao diện người dùng (đúng/sai);

• debug_port: bật cổng tự động hóa (đúng/sai hoặc một cổng cụ thể);

• timeout: thời gian chờ bằng giây;

• only_local: hạn chế truy cập vào localhost (đúng/sai);

• flags: các đối số bổ sung (ví dụ, ["--start-maximized"]);

• password: mật khẩu của hồ sơ, nếu đã đặt.

5. Nhấp vào Gửi và kiểm tra phản hồi.

VS Code

1. Tải xuống và cài đặt VS Code.

2. Tải xuống và cài đặt node.js cho JavaScript.

3. Tải xuống và cài đặt Python cho các kịch bản Python.

4. Mở VS Code và tạo một thư mục dự án.

5. Cài đặt các phụ thuộc:

   • Đối với Node.js: npm install axios.

   • Đối với Python: pip install requests.

6. Sao chép ví dụ tài liệu Octo cho POST Tạo Hồ sơ sử dụng node.js + axios.

7. Tạo tệp .js và dán kịch bản vào đó.

8. Chèn mã thông báo API của bạn và lưu tệp.

9. Chạy kịch bản với lệnh node <filename> (ví dụ, node post_create_profile).

Tương tự, để bắt đầu một hồ sơ bằng Python, chọn POST Bắt đầu Hồ sơ trong Yêu cầu Mẫu, dán kịch bản vào một tệp .py, lưu lại và chạy nó.

Terminal/CMD

Bạn cũng có thể làm việc với API trong Terminal/CMD. Để làm điều này, chọn cURL trong menu LANGUAGE.

Chèn mã thông báo API của bạn vào yêu cầu POST Tạo Hồ sơ và chạy:

Quan trọng: đối với CMD trên Windows bạn cần điều chỉnh cú pháp, vì CMD diễn giải các lệnh khác với shell kiểu Unix. Đặc biệt, cần làm việc với dấu ngoặc kép đúng cách, và xử lý ngắt dòng đúng. Dưới đây là ví dụ điều chỉnh về kịch bản bắt đầu hồ sơ:

curl --location "http://localhost:58888/api/profiles/start" ^
--header "Content-Type: application/json" ^
--data "{\"uuid\": \"42c4231d71f6495fb33e70d97915c696\", \"headless\": false, \"debug_port\": true, \"timeout\": 120, \"only_local\": true, \"flags\": [], \"password\": \"\"}"

*Chèn UUID của hồ sơ cần thiết.

Đây không phải là tất cả các cách khả thi để làm việc với API Octo Browser — đây chỉ là một số ví dụ.

Khung tự động và CDP

CDP (Giao thức Công cụ Dành cho Nhà phát triển Chrome) cho phép bạn điều khiển các hành động của hồ sơ qua mã: mở trang web, nhấp chuột, gõ phím, và chụp ảnh màn hình. 

Octo Browser hỗ trợ kết nối CDP thông qua Local API. Khi bạn bắt đầu một hồ sơ qua POST Bắt đầu Hồ sơ, bạn cần truyền tham số debug_port: true (hoặc chỉ định một cổng), và Octo sẽ mở một cổng cho truy cập từ xa (ví dụ, ws://127.0.0.1:53215/devtools/browser/...).

Ví dụ về bắt đầu một hồ sơ với cổng CDP:

curl --location 'http://localhost:58888/api/profiles/start' \
--header 'Content-Type: application/json' \
--data '{
    "uuid": "eb5d6441b2b349368b31fd901b82a8ac",
    "headless": false,
    "debug_port": true,
    "timeout": 120,
    "only_local": true
}'

Phản hồi sẽ chứa địa chỉ kết nối:

{"uuid":"eb5d6441b2b349368b31fd901b82a8ac","state":"STARTED","headless":false,"start_time":1761735064,"ws_endpoint":"ws://127.0.0.1:53215/devtools/browser/d633f197-1623-4f61-a9b0-28a65e0df2fd","debug_port":"53215","one_time":false,"browser_pid":57411,"connection_data":{"ip":"","country":""}}

Bạn có thể sử dụng địa chỉ này trong bất kỳ thư viện nào hỗ trợ CDP, ví dụ như Puppeteer/Pyppeteer hoặc Playwright. Các ví dụ sử dụng chi tiết có sẵn trong tài liệu.

Ngoài việc trực tiếp sử dụng CDP, bạn có thể kết nối Selenium với các hồ sơ Octo Browser thông qua WebDriver. Trong trường hợp này, Selenium điều khiển một trình duyệt đã đang chạy qua debug_port, nhưng sử dụng WebDriver thay vì các lệnh CDP trực tiếp. Một ví dụ kết nối có sẵn trong tài liệu.

Sử dụng các thư viện tự động hóa mở ra nhiều khả năng, từ việc làm ấm lên các hồ sơ và thu thập cookie, đến xây dựng logic đăng ký tài khoản phức tạp và quản lý các hành động tài khoản.

Cách chạy Octo Browser trong Docker

Docker là phần mềm để tự động hóa việc triển khai và quản lý các ứng dụng trong các container. Mỗi container có hệ điều hành riêng của nó (thường là Linux), thư viện, phụ thuộc và cài đặt. Không giống như một máy ảo, một container rất nhẹ và khởi động rất nhanh.

Lợi ích của việc sử dụng Docker cho Octo Browser:

• Cô lập: Octo Browser và các phụ thuộc của nó chạy độc lập, không xung đột với các ứng dụng khác.

• Di động: cùng một container có thể chạy trên một máy chủ, máy tính xách tay, hoặc VPS, và mọi thứ sẽ hoạt động như nhau.

• Khả năng mở rộng: bạn có thể chạy nhiều hồ sơ cùng lúc, và tạo các container mới khi cần xử lý nhiều hồ sơ hơn cùng lúc.

• Tự động hóa: tiện lợi cho các kịch bản mà trình duyệt chạy ở chế độ không giao diện đồ họa.

Chạy Docker:

1. Chuẩn bị một Dockerfile. Một ví dụ Dockerfile cho Ubuntu 22.04 với tất cả các phụ thuộc, bao gồm Octo Browser và Google Chrome, có sẵn trong tài liệu.

2. Xây dựng một container Docker:

docker build -t octobrowser:latest

3. Chạy container:

docker run --name octo -it --rm \
       --security-opt seccomp:unconfined \
       -v '/srv/docker_octo/cache:/home/octo/.Octo Browser/' \
       -p 58895:58888 \
       octobrowser:latest

Cách quản lý các container Octo Browser bằng Kubernetes

Kubernetes (K8s) giúp quản lý nhiều container cùng lúc.

• Docker là dành cho chạy một container duy nhất.

• Kubernetes giúp chạy cả một cụm container với việc phân phối tự động tải.

Bạn có thể sử dụng Minikube, kind, Docker Desktop hoặc các công cụ khác để chạy Kubernetes.

Quy trình làm việc cho Octo Browser và Kubernetes:

1. Xây dựng container Docker.

2. Chạy container.

3. Sử dụng Kubernetes để quản lý các container.

Một ví dụ YAML Deployment có sẵn trong tài liệu.

Các kịch bản và đoạn mã hữu ích

Trong tài liệu API của Octo Browser, bạn sẽ tìm thấy không chỉ các phương pháp cơ bản mà còn cả các kịch bản sẵn sàng bằng Node.js và Python. Các kịch bản sau được mô tả trong tài liệu:

1. Tạo hàng loạt hồ sơ — chỉ định số lượng hồ sơ và mã thông báo API của bạn.

2. Thêm hàng loạt các tiện ích mở rộng, trang bắt đầu và dấu trang vào các hồ sơ đã chọn — chỉ định danh sách hồ sơ, tiện ích mở rộng, trang bắt đầu, dấu trang và mã thông báo API.

3. Thêm hàng loạt các tiện ích mở rộng, trang bắt đầu và dấu trang vào tất cả hồ sơ — chỉ định tiện ích mở rộng, trang bắt đầu, dấu trang và mã thông báo API.

4. Thêm hàng loạt các tiện ích mở rộng, trang bắt đầu và dấu trang vào hồ sơ với một hoặc vài thẻ cụ thể — chỉ định thẻ/thẻ, tiện ích mở rộng, trang bắt đầu, dấu trang và mã thông báo API.

5. Tạo hàng loạt proxy từ một tập tin .txt và tạo hồ sơ sử dụng các proxy này — tập tin phải ở định dạng protocol;host;port;login;password;title;change_ip_url (change_ip_url là tuỳ chọn). Chỉ định mã thông báo API và tên tệp trong kịch bản.

6. Thêm proxy đã lưu vào một hồ sơ — chỉ định proxy, hồ sơ, và mã thông báo API.

7. Sao chép tất cả các hồ sơ xuất khẩu từ danh sách xuất khẩu của trình duyệt vào thư mục được chỉ định — chỉ định thư mục và mã thông báo API.

8. Tạo tập tin .txt chứa tên của tất cả các hồ sơ trong tài khoản Octo Browser của bạn — chèn mã thông báo API của bạn.

Các câu hỏi thường gặp về API

Làm thế nào để truyền tham số khi tạo một hồ sơ bằng API?

Ví dụ về nội dung yêu cầu:

const body = {
  title: "profile_title", // required field
  fingerprint: {
    os: "mac", // required field: "mac", "win", or "android"
    os_arch: "arm", // optional field: you can set "x86" if you want to create a mac profile with an Intel processor
    os_version: "13" // optional field
    /*
      Possible values:
      — for Windows: 10, 11
      — for macOS (arm): 12, 13, 14, 15
      — for macOS (x86): 12, 13, 14, 15
      — for Android: 12, 13, 14, 15
    */
  }
};

Trường os bên trong đối tượng vân tay là bắt buộc. Nếu bạn không chỉ định các tham số khác, Octo Browser sẽ tự động tạo các giá trị tối ưu cho chúng.

Để xem các tham số nào khác có thể được truyền khi tạo một hồ sơ:

1. Đi tới tài liệu API của Octo Browser (yêu cầu POST Tạo Hồ sơ).

2. Cuộn xuống phần Nội dung — nó hiển thị cấu trúc của tất cả các tham số có sẵn.

3. Sau khi tạo hồ sơ, bạn có thể truy xuất các tham số của nó qua yêu cầu GET Lấy Hồ sơ — phản hồi từ máy chủ sẽ chứa cấu trúc hồ sơ đầy đủ.

Hồ sơ một lần hoạt động như thế nào?

Một hồ sơ một lần là một hồ sơ dùng một lần được tạo và chạy ngay lập tức bằng một yêu cầu API duy nhất, và tự động bị xóa sau khi đóng.

• Không cần gửi các yêu cầu riêng để tạo, chạy, dừng và xóa hồ sơ. Điều này có thể hữu ích, ví dụ, cho web scraping, nơi bạn chỉ cần truy cập một tài nguyên web với vân tay trình duyệt mới, thu thập dữ liệu, và sau đó xóa hồ sơ.

• Hồ sơ một lần có sẵn trong tất cả các gói đăng ký có quyền truy cập API.

• Một yêu cầu POST Hồ sơ một lần được tính là 4 yêu cầu đối với giới hạn RPM/RPH của bạn.

Để kết thúc làm việc với một hồ sơ một lần, bạn chỉ cần gửi POST Dừng Hồ sơ, đóng cửa sổ trình duyệt thủ công, hoặc gọi một hành động đóng bằng chương trình thông qua Puppeteer, Playwright hoặc các thư viện tương tự — ví dụ, bằng cách sử dụng await browser.close(). Sau khi đóng, hồ sơ tự động bị xóa và không xuất hiện trong danh sách hồ sơ của bạn hoặc trong Thùng rác.

Tôi nên làm gì nếu tôi vượt quá giới hạn API (lỗi 429)?

Dừng kịch bản của bạn và tạm dừng gửi yêu cầu trong một thời gian. Bạn có thể kiểm tra giới hạn API của mình trong header phản hồi:

• Retry-After: 0 # bạn có thể gửi yêu cầu tiếp theo nếu giá trị là không

• X-Ratelimit-Limit: 200 # RPM chỉ tổng số yêu cầu mỗi phút

• X-Ratelimit-Limit-Hour: 3000 # RPH chỉ tổng số yêu cầu mỗi giờ

• X-Ratelimit-Remaining: 4 # RPM còn lại chỉ số yêu cầu còn lại trong phút này

• X-Ratelimit-Remaining-Hour: 2999 # RPH còn lại chỉ số yêu cầu còn lại trong giờ này

• X-Ratelimit-Reset: 1671789217 # Dấu thời gian UNIX chỉ khi nào các giới hạn được đặt lại

Không gửi yêu cầu khi giới hạn của bạn đã hết. Nếu không, thời gian hạn chế sẽ tăng lên, và các giới hạn rate nghiêm ngặt hơn có thể được áp dụng. Hãy đảm bảo các kịch bản của bạn kiểm tra các header giới hạn này trước khi gửi yêu cầu.

Tôi có thể lấy ws_endpoint cho kết nối CDP ở đâu?

Khi bạn khởi chạy một hồ sơ qua API với tham số "debug_port": true (hoặc chỉ định một cổng cụ thể, ví dụ "debug_port": 20000), Octo Browser trả về giá trị ws_endpoint trong phản hồi.

Ws_endpoint này được sử dụng bởi các thư viện tự động hóa (như Puppeteer hoặc Playwright) để kết nối với một hồ sơ đang chạy.

Tôi có thể tìm mã thông báo API của mình ở đâu?

API có sẵn cho người dùng có Gói đăng kí Base và cao hơn.

Mã thông báo API được hiển thị trong cài đặt tài khoản chính, dưới tab “Additional.” Các thành viên khác trong đội nhóm không thể thấy mã thông báo API.