Scrapeless CLI
Tổng quan
Scrapeless CLI cung cấp một lệnh scrapeless duy nhất để trích xuất web, thu thập dữ liệu website, lấy kết quả Google Search có cấu trúc, thu thập câu trả lời AI, tạo URL proxy và thao tác với trình duyệt đám mây. Chạy lệnh trong terminal hoặc gọi từ các tập lệnh tự động hóa.
Tính năng
| Tính năng | Lệnh khởi đầu | Mục đích |
|---|---|---|
| Web Unlocker | scrapeless unlock / scrapeless scrape | Trích xuất một trang ở định dạng HTML, Markdown hoặc các định dạng được hỗ trợ khác. |
| Crawl | scrapeless crawl | Tạo tác vụ crawl website và lấy kết quả của tác vụ. |
| AI Scraper | scrapeless ai | Thu thập câu trả lời từ các nền tảng AI được hỗ trợ. |
| Google Search | scrapeless scraping-api google-search | Lấy kết quả Google Search có cấu trúc với các tùy chọn ngôn ngữ, vị trí và phân trang. |
| Proxies | scrapeless proxy create | Tạo URL proxy có xác thực ngay trên máy cục bộ. |
| Cloud browser | scrapeless browser | Chạy CLI trình duyệt đám mây upstream. |
api là bí danh của scraping-api. Ví dụ, scrapeless api google-search và scrapeless scraping-api google-search chạy cùng một lệnh.
Bắt đầu
- Bắt đầu nhanh — cài đặt, cấu hình khóa và gửi yêu cầu đầu tiên.
- Ví dụ sử dụng — các lệnh cho từng tính năng.
- Cấu hình và tác vụ — thông tin xác thực, đầu ra, polling và yêu cầu đối với Browser.
Bắt đầu nhanh
Yêu cầu
Sử dụng Node.js 22 trở lên và npm. Node.js là môi trường chạy của CLI; bạn không cần viết JavaScript hay TypeScript. Cần có tài khoản Scrapeless và API key để sử dụng các dịch vụ yêu cầu xác thực.
1. Cài đặt CLI
npm install -g scrapeless
scrapeless --version
scrapeless --help2. Cấu hình API Key
Sao chép API key từ bảng điều khiển Scrapeless và thay thế YOUR_API_TOKEN:
- Mở Settings (Cài đặt) trong bảng điều khiển.
- Chọn API Key Management (Quản lý API Key).
- Sử dụng một khóa có sẵn, hoặc chọn Create API Key (Tạo API Key) nếu bạn cần. Sao chép khóa để dùng cho lệnh cấu hình bên dưới.
scrapeless config set api_token YOUR_API_TOKEN
scrapeless auth statusauth status kiểm tra trạng thái xác thực và số dư tài khoản. Các yêu cầu đám mây và lưu lượng proxy sẽ tiêu tốn credit của tài khoản.
3. Trích xuất một trang
scrapeless unlock https://example.com --type markdownLệnh này in ra nội dung Markdown được trích xuất từ trang.
Xem toàn bộ phản hồi
Thêm --json để xem toàn bộ phản hồi, bao gồm mã phản hồi và nội dung trang:
scrapeless unlock https://example.com --type markdown --json4. Tìm kiếm trên Google
Chạy tìm kiếm với truy vấn, ngôn ngữ và quốc gia:
scrapeless scraping-api google-search --q "coffee" --hl en --gl usLệnh in toàn bộ JSON kết quả. Để lưu vào tệp:
scrapeless scraping-api google-search --q "coffee" --hl en --gl us -o search.jsonNếu CLI đã cài đặt không nhận diện scraping-api, hãy cập nhật rồi xem trợ giúp của lệnh:
npm install -g scrapeless@latest
scrapeless scraping-api google-search --helpVí dụ sử dụng
Hãy cài đặt CLI và cấu hình API key trước khi chạy các ví dụ này.
Web Unlocker
Trích xuất một vùng được chọn dưới dạng HTML, hoặc lưu toàn bộ phản hồi JSON:
scrapeless unlock https://example.com --type html --selector body
scrapeless unlock https://example.com --type markdown --json -o page.jsonscrape là bí danh của unlock. Đầu ra mặc định là HTML, với tính năng render JavaScript được bật.
Crawl
scrapeless crawl https://example.com --limit 3 --max-depth 2 --formats markdown --json -o crawl.json--formats markdown chọn định dạng cho nội dung trang; kết quả tổng thể của tác vụ vẫn là JSON. Giới hạn phạm vi crawl bằng --include-paths và --exclude-paths.
AI Scraper
scrapeless ai platforms
scrapeless ai chatgpt "Explain what Scrapeless is used for" -o answer.md
scrapeless ai perplexity "What web scraping techniques are available?" --web-search true --json -o answer.jsonCác tác vụ thành công trả về Markdown theo mặc định. Các tùy chọn khác nhau tùy theo nền tảng; dùng ai platforms để xem danh sách hiện tại. Các prompt tiếng Anh chỉ là ví dụ: CLI chấp nhận văn bản Unicode, và khả năng hỗ trợ ngôn ngữ phụ thuộc vào dịch vụ được chọn.
Google Search
Dùng scraping-api google-search, hoặc bí danh ngắn hơn api google-search, để lấy kết quả tìm kiếm có cấu trúc.
# Search with a Google search operator and a specific location
scrapeless api google-search \
--q "site:example.com coffee" \
--location "Seattle,Washington,United States"
# Request results starting at offset 10 and save the JSON
scrapeless api google-search \
--q "coffee" --hl en --gl us --start 10 \
-o search.json
# Search Google News
scrapeless api google-search --q "artificial intelligence" --tbm nwsCác tùy chọn thường dùng:
| Tùy chọn | Mô tả |
|---|---|
--q | Truy vấn tìm kiếm bắt buộc. Hỗ trợ toán tử tìm kiếm Google. Cũng có thể cung cấp dưới dạng input.q qua --data. |
--hl, --gl | Mã ngôn ngữ và quốc gia tìm kiếm, chẳng hạn en và us. |
--location, --uule | Tên vị trí chuẩn hoặc vị trí Google đã mã hóa. Chỉ dùng một trong hai. |
--google-domain | Tên miền Google, chẳng hạn google.com. |
--tbm | Loại tìm kiếm, chẳng hạn nws cho tin tức, isch cho hình ảnh hoặc lcl cho kết quả địa phương. |
--start | Độ lệch kết quả không âm. Với --tbm lcl, dùng bội số của 20. |
--safe | Thiết lập SafeSearch: active hoặc off. |
--device | Hiện chỉ chấp nhận desktop. |
--country, --proxy-url | Quốc gia proxy hoặc URL proxy tùy chỉnh. |
--timeout, --interval | Thời gian chờ và khoảng cách polling, tính bằng giây. Mặc định: 300 và 5. |
-o, --output | Lưu JSON kết quả vào tệp. |
--gl điều khiển quốc gia tìm kiếm; --country cấu hình quốc gia proxy. Đây là hai thiết lập riêng biệt. --proxy-url không rỗng được ưu tiên hơn quốc gia proxy.
Để thêm các trường yêu cầu khác, hãy truyền toàn bộ nội dung JSON. Lưu nội dung sau thành search-request.json:
{
"actor": "scraper.google.search",
"input": {
"q": "coffee",
"hl": "en",
"gl": "us",
"as_eq": "instant"
},
"proxy": {
"country": "US"
}
}Chạy yêu cầu:
scrapeless api google-search --data @search-request.json -o search.jsonCác flag được chỉ định rõ ghi đè trường tương ứng trong body. Lệnh luôn đặt actor thành scraper.google.search.
Chạy scrapeless scraping-api google-search --help để xem mọi tùy chọn CLI. Xem tài liệu Google Search để biết chi tiết API.
Proxies
scrapeless proxy gateways
scrapeless proxy create --type residential --country US --gateway usViệc tạo URL diễn ra trên máy cục bộ và không kiểm tra kết nối. Các loại được hỗ trợ là residential, ipv6 và datacenter; gateway chấp nhận us, eu, ap hoặc hostname:port. URL chứa thông tin xác thực; hãy giữ bí mật.
Cloud Browser
Thay thế SESSION_ID bằng ID phiên được trả về từ new-session:
scrapeless browser new-session --name demo --ttl 300 --json
scrapeless browser --session-id SESSION_ID open https://example.com
scrapeless browser --session-id SESSION_ID snapshot -i
scrapeless browser --session-id SESSION_ID screenshot page.png
scrapeless browser --session-id SESSION_ID closeVới click @e1 hoặc fill @e2 "hello world", hãy sử dụng các tham chiếu tương tác thực tế từ một snapshot mới trong khi phiên vẫn đang mở. Theo mặc định, lần sử dụng đầu tiên, kể cả browser --help, sẽ cài đặt CLI upstream; xem phần Yêu cầu đối với Browser trong Cấu hình và tác vụ.
Để xem các tùy chọn lệnh, chạy scrapeless unlock --help, scrapeless crawl --help, scrapeless ai --help, scrapeless scraping-api google-search --help hoặc scrapeless proxy create --help. Hành vi cài đặt khi sử dụng lần đầu của browser --help đã được mô tả ở trên.
Tài liệu tham khảo lệnh đầy đủ và hướng dẫn build từ mã nguồn có trong kho lưu trữ CLI. Hành vi và cách tính phí của dịch vụ AI được trình bày trong tài liệu AI Scraper.
Cấu hình và tác vụ
Thông tin xác thực
Tệp mặc định là ~/.scrapeless/config.json. Thứ tự ưu tiên của khóa là tệp cấu hình → SCRAPELESS_API_TOKEN → SCRAPELESS_API_KEY. Để sử dụng biến môi trường:
export SCRAPELESS_API_KEY="YOUR_API_TOKEN"Khóa đã lưu được ưu tiên hơn. CLI không tự động tải .env. Đây là cú pháp POSIX; PowerShell sử dụng $env:SCRAPELESS_API_KEY="YOUR_API_TOKEN".
| Biến | Mục đích |
|---|---|
SCRAPELESS_API_KEY | API key; cũng được Browser hỗ trợ. |
SCRAPELESS_API_TOKEN | Biến khóa thay thế cho các lệnh hợp nhất. |
SCRAPELESS_CONFIG_PATH | Đường dẫn cấu hình tùy chỉnh, chỉ áp dụng cho các lệnh hợp nhất. |
SCRAPELESS_API_BASE_URL | Ghi đè HTTP API hợp nhất; mặc định là https://api.scrapeless.com. |
SCRAPELESS_CACHE_DIR | Thư mục gốc bộ nhớ đệm của Browser; mặc định là ~/.cache/scrapeless. |
SCRAPELESS_BROWSER_BIN | Đường dẫn tuyệt đối đến một tệp thực thi tương thích; bỏ qua bước cài đặt tự động. |
Đường dẫn cấu hình tùy chỉnh không thay đổi tệp mặc định của Browser. Wrapper truyền khóa đã xác định qua một biến môi trường, nhưng khóa đã lưu mặc định của Browser có thể ghi đè nó. Hãy sử dụng tệp mặc định dùng chung để đảm bảo xác thực nhất quán.
Đầu ra và nội dung yêu cầu
Các lệnh HTTP hỗ trợ --json để lấy toàn bộ phản hồi và -o, --output <file> để lưu đầu ra. Theo mặc định, kết quả được ghi ra stdout; khi dùng -o, kết quả sẽ được lưu vào tệp thay vì stdout. Thông tin tiến trình, thông báo ID tác vụ trong quá trình polling và lỗi được ghi ra stderr. Khi dùng --no-wait, phản hồi tạo tác vụ, bao gồm ID tác vụ, là một phần của đầu ra kết quả.
Các lệnh tạo tác vụ của Unlocker, Crawl, AI và Scraping API chấp nhận --data '<JSON>' hoặc --data @request.json. Thứ tự ưu tiên là flag được chỉ định rõ → các trường trong body → giá trị mặc định của CLI; các object lồng nhau được hợp nhất còn các mảng sẽ bị thay thế.
Google Search luôn trả toàn bộ JSON kết quả, ngay cả khi không có --json. Dùng -o, --output <file> để lưu. Thông báo ID tác vụ và lỗi được ghi ra stderr.
Xử lý tác vụ
Theo mặc định, các lệnh tạo tác vụ Crawl và AI sẽ polling mỗi 5 giây trong tối đa 300 giây. Thêm --no-wait để trả về ngay sau khi tạo. Truy vấn một tác vụ hiện có bằng ID được trả về:
scrapeless crawl result TASK_ID --wait --timeout 300 --interval 5
scrapeless ai result TASK_ID --platform chatgpt --wait --timeout 300 --interval 5Sử dụng ID cho dịch vụ tương ứng. Hết thời gian chờ polling không hủy tác vụ trên máy chủ. Kiểm tra completed đối với Crawl hoặc success đối với AI và xem xét nội dung thực tế; chỉ riêng mã thoát 0 là không đủ.
--timeout và --interval dùng đơn vị giây; các tùy chọn thu thập --wait-for và --scrape-timeout dùng đơn vị mili giây. Mỗi yêu cầu HTTP có thời gian chờ riêng là 60 giây. Các yêu cầu POST tạo tác vụ không được tự động thử lại.
Tác vụ Google Search
Google Search trả kết quả ngay với HTTP 200. Nếu API phản hồi HTTP 201 cùng taskId, CLI tự động polling kết quả mỗi 5 giây trong tối đa 300 giây. Điều chỉnh các giá trị này bằng --interval và --timeout.
Để tiếp tục kiểm tra tác vụ hiện có mà không tạo yêu cầu mới:
scrapeless scraping-api result TASK_ID \
--timeout 300 --interval 5 \
-o search.jsonLệnh result tự động polling; không cần flag --wait.
Phản hồi HTTP 4xx hoặc 5xx và việc hết thời gian polling khiến lệnh thoát với mã 1. Khi hết thời gian polling, stderr chứa ID tác vụ, phản hồi cuối cùng và lệnh để tiếp tục kiểm tra. Việc hết thời gian chờ không hủy tác vụ trên máy chủ. Các yêu cầu POST tạo tác vụ không được tự động thử lại.
Yêu cầu đối với Browser
Wrapper cần npm, quyền truy cập npm và GitHub Releases, cùng quyền ghi vào bộ nhớ đệm. Các phiên chạy trên đám mây; wrapper chạy cục bộ mà không cần cài đặt Chromium riêng.
Phiên bản được ghim hỗ trợ macOS x64/arm64, Linux x64/arm64 và Windows x64; không có binary Windows arm64 đi kèm.
Khắc phục sự cố
| Vấn đề | Cần kiểm tra |
|---|---|
| Thiếu khóa hoặc HTTP 401/403 | Kiểm tra khóa đã lưu, quyền tài khoản và số dư; chạy scrapeless auth status. |
| Hết thời gian polling của Crawl hoặc AI | Giữ lại ID tác vụ và sử dụng các lệnh result ... --wait ở trên; kiểm tra trạng thái và nội dung thực tế. |
| Cài đặt Browser thất bại | Kiểm tra npm, quyền truy cập mạng, quyền ghi bộ nhớ đệm và các yêu cầu nền tảng ở trên. |
Không nhận diện lệnh scraping-api | Cập nhật bằng npm install -g scrapeless@latest, rồi chạy scrapeless scraping-api google-search --help. |
| Hết thời gian polling của Google Search | Dùng ID tác vụ được thông báo với scrapeless scraping-api result TASK_ID. Tăng --timeout nếu cần. |
| Xác thực tham số Google Search thất bại | Cung cấp truy vấn không rỗng, chỉ dùng một trong --location và --uule, và dùng --start không âm. Tìm kiếm địa phương yêu cầu độ lệch là bội số của 20. |