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ăngLệnh khởi đầuMục đích
Web Unlockerscrapeless unlock / scrapeless scrapeTrích xuất một trang ở định dạng HTML, Markdown hoặc các định dạng được hỗ trợ khác.
Crawlscrapeless crawlTạo tác vụ crawl website và lấy kết quả của tác vụ.
AI Scraperscrapeless aiThu thập câu trả lời từ các nền tảng AI được hỗ trợ.
Google Searchscrapeless scraping-api google-searchLấ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.
Proxiesscrapeless proxy createTạo URL proxy có xác thực ngay trên máy cục bộ.
Cloud browserscrapeless browserChạ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

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 --help

2. 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:

  1. Mở Settings (Cài đặt) trong bảng điều khiển.
  2. Chọn API Key Management (Quản lý API Key).
  3. 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 status

auth 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 markdown

Lệ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 --json

4. 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 us

Lệ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.json

Nế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 --help

Ví 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.json

scrape 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.json

Cá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.

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 nws

Các tùy chọn thường dùng:

Tùy chọnMô tả
--qTruy 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, --glMã ngôn ngữ và quốc gia tìm kiếm, chẳng hạn en và us.
--location, --uuleTên vị trí chuẩn hoặc vị trí Google đã mã hóa. Chỉ dùng một trong hai.
--google-domainTên miền Google, chẳng hạn google.com.
--tbmLoạ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.
--safeThiết lập SafeSearch: active hoặc off.
--deviceHiện chỉ chấp nhận desktop.
--country, --proxy-urlQuốc gia proxy hoặc URL proxy tùy chỉnh.
--timeout, --intervalThời gian chờ và khoảng cách polling, tính bằng giây. Mặc định: 300 và 5.
-o, --outputLư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.json

Cá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 us

Việ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 close

Vớ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ếnMục đích
SCRAPELESS_API_KEYAPI key; cũng được Browser hỗ trợ.
SCRAPELESS_API_TOKENBiế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_URLGhi đè HTTP API hợp nhất; mặc định là https://api.scrapeless.com.
SCRAPELESS_CACHE_DIRThư 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 5

Sử 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.

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.json

Lệ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/403Kiể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 AIGiữ 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ạiKiể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-apiCậ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 SearchDù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ạiCung 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.