Chỉ cần nhập một URL, nhận lại dữ liệu có cấu trúc rõ ràng

Trích xuất dữ liệu

Yozh Scraper hiển thị bất kỳ URL nào trong trình duyệt Playwright thực tế và trả về chính xác những gì bạn yêu cầu — các trường dữ liệu đã trích xuất, mã HTML thô hoặc ảnh chụp màn hình toàn trang. Mỗi lần trích xuất đều là một tác vụ không đồng bộ: gửi URL, kiểm tra trạng thái tác vụ, và lấy kết quả. Các tính năng như proxy, chế độ ẩn danh, cài đặt sẵn và phiên đăng nhập đều được hỗ trợ đầy đủ.

• Kết xuất thực tế trên trình duyệt — Playwright kết xuất các trang được xây dựng bằng JavaScript; chuyển sang render để hiển thị HTML tĩnh.
• Trích xuất có cấu trúc — Các quy tắc trường CSS hoặc XPath trả về một data , tiết kiệm thời gian và công sức hơn nhiều so với việc tự tải xuống và phân tích cú pháp HTML thô.
• Proxy tích hợp sẵn — CyberYozh dành cho người dùng cá nhân / LTE di động / trung tâm dữ liệu, hỗ trợ định vị theo khu vực địa lý (GEO) và không có hiện tượng “hunting pool-id”.
• Chế độ ẩn danh theo mặc định — các bản vá playwright-stealth (navigator.webdriver, dấu vân tay WebGL / Canvas, thời gian chạy Chrome) nhằm giảm khả năng bị phát hiện là bot.
• Cài đặt sẵn — trích xuất dữ liệu từ Amazon / Google / eBay / Walmart / YouTube / LinkedIn theo tên, kèm tính năng tự phục hồi LLM tùy chọn.
• Phiên làm việc — các phiên làm việc đã được xác thực do máy chủ quản lý dành cho các mục tiêu đã đăng nhập, được tái sử dụng trong các lần thu thập dữ liệu.

Bắt đầu nhanh

Trình trích xuất được khởi chạy từ gốc docker-compose.yml (cùng với bộ thu thập dữ liệu):

cp .env.example .env          # set CYBERYOZH_API_KEY if using proxies
docker compose up --build
# scraper → http://localhost:8000
# crawler → http://localhost:8001

Kiểm tra xem nó đã hoạt động chưa:

curl http://localhost:8000/api/v1/health
# {"status":"ok","workers":2}

Cách sử dụng cơ bản

Mỗi điểm cuối scrape sẽ tạo ra một tác vụ chạy nền và trả về một job_id. Kiểm tra tiến trình công việc, sau đó lấy kết quả của nó.

curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{ "url": "https://example.com", "proxy_type": "none" }'
# → { "job_id": "req_abc123" }

curl http://localhost:8000/api/v1/scrape/req_abc123          # status
curl http://localhost:8000/api/v1/scrape/req_abc123/results  # results

Kết quả cuối cùng sẽ chứa siêu dữ liệu cùng với bất kỳ thông tin nào bạn yêu cầu (data, raw_html, screenshot_base64):

{
  "job_id": "req_abc123",
  "status": "done",
  "total": 1, "done": 1,
  "results": [
    {
      "request_id": "req_abc123",
      "took_ms": 1234,
      "meta": { "url": "https://example.com", "final_url": "https://example.com/",
                "status_code": 200, "device": "desktop", "proxy_type": "none", "retries": 0 },
      "data": null, "raw_html": null, "screenshot_base64": null, "warnings": []
    }
  ]
}

Trích xuất dữ liệu

Áp dụng một extract quy tắc và phản hồi sẽ bao gồm một data đối tượng có các khóa là tên trường của bạn — tiết kiệm hơn nhiều so với việc tải xuống raw_html và tự phân tích dữ liệu. Các quy tắc là css hoặc xpath.

curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{
    "url": "https://example.com",
    "extract": {
      "type": "css",
      "fields": {
        "title": { "selector": "h1", "attr": "text", "required": true }
      }
    }
  }'
# result → { "data": { "title": "Example Domain" } }

Mỗi trường là một quy tắc:

Sử dụng "type": "xpath" với các bộ chọn XPath (ví dụ: //h1) cho cùng một hình dạng.

Ảnh chụp màn hình & mã HTML thô

Đặt screenshot: true để tạo tệp PNG toàn trang (dạng base64 trong screenshot_base64), hoặc raw_html: true để lấy toàn bộ mã HTML sau khi hiển thị trong raw_html.

curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{ "url": "https://example.com", "screenshot": true, "raw_html": true }'

Proxy

Để quá trình thu thập dữ liệu diễn ra đáng tin cậy, việc sử dụng proxy là điều không thể thiếu — hầu hết các trang web hiện đại đều chặn các yêu cầu truy cập trực tiếp. Yozh tích hợp với Dịch vụ Proxy CyberYozh; hãy thiết lập proxy_type cho bất kỳ yêu cầu nào.

Chọn một vị trí bằng proxy_geo (country_code / region / city). Khám phá những gì bạn đã mua mà không cần phải tìm kiếm ID của các nhóm:

curl "http://localhost:8000/api/v1/proxies/available?proxy_type=res_rotating"
curl "http://localhost:8000/api/v1/proxies/countries"

Preset

Một cài đặt sẵn bao gồm một cấu hình yêu cầu + mẫu URL + công thức phân tích, nhờ đó bạn có thể trích xuất dữ liệu từ một trang web chỉ bằng cách nhập tên trang web thay vì phải tự tay xây dựng yêu cầu. Các cài đặt sẵn được tích hợp sẵn cho Amazon, Google, eBay, Walmart, YouTube và LinkedIn; bạn cũng có thể tự tạo cài đặt sẵn của riêng mình (dựa trên CSS/XPath xác định hoặc do AI tạo ra).

curl -X POST http://localhost:8000/api/v1/scrape/preset/page 
  -H "Content-Type: application/json" 
  -d '{
    "source": "amazon_product",
    "preset_params": { "asin": "B08N5WRWNW" },
    "locale": "us",
    "llm": { "model": "openai/gpt-5.4-mini" }
  }'
# → { "job_id": "..." }  then GET /api/v1/scrape/<job_id>/results

Quản lý các cài đặt sẵn qua GET /api/v1/presets, GET /api/v1/presets/{name}, và POST /api/v1/presets (tên cài đặt sẵn của người dùng phải bắt đầu bằng user_).

Phiên

Các phiên xác thực do máy chủ quản lý: tạo một phiên, đăng nhập một lần, sau đó truyền thông tin session_id cho bất kỳ quá trình thu thập dữ liệu nào để các trang được tải về bằng cookie đã lưu trữ cùng với trạng thái lưu trữ. Yêu cầu bắt buộc đối với các mục tiêu đã đăng nhập như linkedin_profile cài đặt sẵn.

1. POST /api/v1/sessions — Tạo. Ghim device / proxy_type / proxy_geo và một TTL. Trả về { session_id, expires_at }.
2. POST /api/v1/sessions/{id}/login — chạy lại một tập lệnh đăng nhập dạng khai báo với creds trong phần nội dung: { script, creds }.
3. POST /api/v1/scrape/page với session_id set — thu thập dữ liệu đã xác thực.
4. DELETE /api/v1/sessions/{id} — dọn dẹp.

# 1. create  →  {"session_id":"sess_...","expires_at":...}
curl -X POST http://localhost:8000/api/v1/sessions 
  -H "Content-Type: application/json" 
  -d '{ "device": "desktop", "proxy_type": "res_rotating" }'

# 2. log in (declarative DSL + creds)
curl -X POST http://localhost:8000/api/v1/sessions/sess_.../login 
  -H "Content-Type: application/json" 
  -d '{ "script": { "steps": [ {"op":"goto","url":"https://site/login"} ] },
        "creds": { "username": "...", "password": "..." } }'

# 3. scrape with the session
curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{ "url": "https://site/secure", "session_id": "sess_...", "raw_html": true }'

Trích xuất dữ liệu theo lô

Gửi nhiều trang trong một tác vụ bằng cách sử dụng POST /api/v1/scrape/pages — mỗi mục là một yêu cầu thu thập dữ liệu đầy đủ. Kiểm tra trạng thái và lấy kết quả thông qua các điểm cuối của cùng một tác vụ.

curl -X POST http://localhost:8000/api/v1/scrape/pages 
  -H "Content-Type: application/json" 
  -d '{
    "pages": [
      { "url": "https://example.com", "proxy_type": "none" },
      { "url": "https://example.org", "proxy_type": "none" }
    ]
  }'

MCP

Công cụ trích xuất này triển khai một điểm cuối của Giao thức Bối cảnh Mô hình (Model Context Protocol) tại /mcp (Streamable HTTP). Chỉ cần di chuột hoặc đặt con trỏ vào đó, các công cụ sẽ tự động xuất hiện:

• run_scrape_page
• run_scrape_pages
• get_job_status
• get_job_result
• cancel_scrape_job
• health

"yozh-scraper": {
  "type": "http",
  "url": "http://localhost:8000/mcp"
}

Sau đó, chỉ cần yêu cầu: "Trích xuất dữ liệu từ https://example.com và cho tôi biết trên trang đó có những gì." Điểm cuối này cũng hoạt động khi được gọi từ một tác nhân LangChain hoặc một nút n8n MCP Client Tool.

Tài liệu tham khảo về cấu hình

Yêu cầu — ScrapeRequest (đã chọn)

Tham khảo API

Các chi tiết quan trọng