文档开发者工具SDKsGo SDK

Go SDK

概述

官方 Scrapeless Go SDK 提供对浏览器自动化、抓取、爬取、代理、搜索结果以及 AI 聊天内容提取的访问能力。本指南遵循 SDK 仓库 README，包含可运行的示例和配置详情。

环境要求

仓库的 go.mod 要求使用 Go 1.24.0 或更高版本。请在 Go module 内运行安装命令。对于新项目，可使用 go mod init example.com/scrapeless-demo 初始化一个 module。

安装

go get -u github.com/scrapeless-ai/sdk-go

身份认证 / API Key

登录 Scrapeless 控制台 并创建一个 API key。在运行示例前将其导出：

export SCRAPELESS_API_KEY="YOUR_API_KEY"

请将 API key 保存在环境变量或密钥管理器中，而不要将其提交到源代码管理系统。

快速开始

将以下内容保存为 main.go，在设置好 API key 后运行 go run .。使用相应的 With...() 选项启用各项服务，并在完成后关闭客户端。

package main
 
import (
    "context"
    "fmt"
    "log"
 
    "github.com/scrapeless-ai/sdk-go/scrapeless"
    "github.com/scrapeless-ai/sdk-go/scrapeless/services/universal"
)
 
func main() {
    client := scrapeless.New(scrapeless.WithUniversal())
    defer client.Close()
 
    result, err := client.Universal.CreateTask(context.Background(), universal.UniversalTaskRequest{
        Actor: universal.ScraperUniversal,
        Input: map[string]any{
            "url": "https://example.com",
            "method": "GET",
            "redirect": false,
        },
    })
    if err != nil {
        log.Print(err)
        return
    }
    fmt.Printf("%+v\n", result)
}

产品覆盖对照表

产品SDK 服务启用方式覆盖范围
Agent Browserclient.Browserscrapeless.WithBrowser()创建并管理远程浏览器会话。
Browser Profilesclient.Profilescrapeless.WithProfile()跨会话持久化浏览器数据。
Scraping APIclient.Scrapingscrapeless.WithScraping()使用网站 actor 提取结构化数据。
Web Unlockerclient.Universalscrapeless.WithUniversal()从受保护的网站获取内容。
Crawlclient.Crawlscrapeless.WithCrawl()抓取单个页面或爬取整个网站。
Google Search APIclient.DeepSerpscrapeless.WithDeepSerp()提取搜索引擎结果。
Proxiesclient.Proxyscrapeless.WithProxy()生成代理连接 URL。
AI Scraperclient.AIScraperscrapeless.WithAIScraper()创建 AI 聊天任务并获取其状态和结果。

各项服务均为按需启用。例如，使用 scrapeless.New(scrapeless.WithBrowser(), scrapeless.WithAIScraper()) 可同时初始化浏览器和 AI Scraper 支持。README 中还记录了用于其他工作流的 Client.Captcha、Client.Server 和 Client.Router。

使用示例

Browser

package main
 
import (
	"context"
	"github.com/scrapeless-ai/sdk-go/scrapeless"
	"github.com/scrapeless-ai/sdk-go/scrapeless/log"
	"github.com/scrapeless-ai/sdk-go/scrapeless/services/browser"
)
 
func main() {
	client := scrapeless.New(scrapeless.WithBrowser())
	defer client.Close()
 
	browserInfo, err := client.Browser.Create(context.Background(), browser.Actor{
		Input:        browser.Input{SessionTtl: "180"},
		ProxyCountry: "US",
	})
	if err != nil {
		panic(err)
	}
	log.Infof("%+v", browserInfo)
}

Browser Profile

package main
 
import (
	"context"
	"fmt"
	"github.com/scrapeless-ai/sdk-go/scrapeless"
)
 
func main() {
	client := scrapeless.New(scrapeless.WithProfile())
	defer client.Close()
 
	result, err := client.Profile.CreateProfile(context.Background(), "My Profile")
	if err != nil {
		panic(err)
	}
	fmt.Printf("%+v\n", result)
}

Scraping API

package main
 
import (
	"context"
	"github.com/scrapeless-ai/sdk-go/scrapeless"
	"github.com/scrapeless-ai/sdk-go/scrapeless/log"
	"github.com/scrapeless-ai/sdk-go/scrapeless/services/scraping"
)
 
func main() {
	client := scrapeless.New(scrapeless.WithScraping())
	defer client.Close()
 
	scrape, err := client.Scraping.Scrape(context.Background(), scraping.ScrapingTaskRequest{
		Actor: "scraper.google.search",
		Input: map[string]interface{}{
			"q": "nike site:www.nike.com",
		},
		ProxyCountry: "US",
	})
	if err != nil {
		log.Errorf("scraping create err:%v", err)
		return
	}
	log.Infof("%+v", scrape)
}

Web Unlocker

使用 Web Unlocker（以 client.Universal 形式暴露）从网站提取数据。

package main
 
import (
	"context"
	"fmt"
	"github.com/scrapeless-ai/sdk-go/scrapeless"
	"github.com/scrapeless-ai/sdk-go/scrapeless/services/universal"
)
 
func main() {
	client := scrapeless.New(scrapeless.WithUniversal())
	defer client.Close()
 
	result, err := client.Universal.CreateTask(context.Background(), universal.UniversalTaskRequest{
		Actor: universal.ScraperUniversal,
		Input: map[string]any{
			"url":      "https://example.com",
			"method":   "GET",
			"redirect": false,
		},
	})
	if err != nil {
		panic(err)
	}
	fmt.Printf("%+v\n", result)
}

Crawl

package main
 
import (
	"context"
	"github.com/scrapeless-ai/sdk-go/scrapeless"
	"github.com/scrapeless-ai/sdk-go/scrapeless/log"
	"github.com/scrapeless-ai/sdk-go/scrapeless/services/crawl"
)
 
func main() {
	client := scrapeless.New(scrapeless.WithCrawl())
	defer client.Close()
 
	// Crawl
	response, err := client.Crawl.CrawlUrl(context.Background(), "https://redditinc.com/blog", crawl.CrawlParams{
		Limit: 10,
		ScrapeOptions: crawl.ScrapeOptions{
			Formats: []string{"links",
				"markdown",
				"html",
				"screenshot"},
		},
		BrowserOptions: crawl.ICreateBrowser{
			SessionName:      "Crawl",
			SessionTTL:       "900",
			SessionRecording: "true",
			ProxyCountry:     "ANY",
		},
	})
	if err != nil {
		panic(err)
	}
	log.Infof("Crawl response: %v", response)
 
	// scrape
	scrapeResponse, err := client.Crawl.ScrapeUrl(context.Background(), "https://docs.scrapeless.com/en/docs/get-started/overview/", crawl.ScrapeOptions{
		BrowserOptions: crawl.ICreateBrowser{
			SessionName:      "Crawl",
			SessionTTL:       "900",
			SessionRecording: "true",
			ProxyCountry:     "ANY",
		},
	})
	if err != nil {
		panic(err)
	}
	log.Infof("Scrape response: %v", scrapeResponse)
}

Proxy

package main
 
import (
	"context"
	"fmt"
	"github.com/scrapeless-ai/sdk-go/scrapeless"
	"github.com/scrapeless-ai/sdk-go/scrapeless/services/proxies"
)
 
func main() {
	client := scrapeless.New(scrapeless.WithProxy())
	defer client.Close()
 
	result, err := client.Proxy.Proxy(context.Background(), proxies.ProxyActor{
		Country:         "US",
		SessionDuration: 30,
		SessionId:       "my-session",
		Gateway:         "your-proxy-gateway:port",
	})
	if err != nil {
		panic(err)
	}
	fmt.Printf("%+v\n", result)
}

AI Scraper

批量提取 AI 聊天内容，以监测品牌提及、对比回答，并从最新模型中分析竞争情报。通过一次集成即可获取 URL、prompt、Markdown 格式回答、引用来源等信息。

支持的 actor 包括 scraper.chatgpt、scraper.perplexity、scraper.copilot、scraper.gemini、scraper.aimode、scraper.overview、scraper.grok 和 scraper.alexa。input JSON 取决于所选 actor；有关详细参数，请参阅 AI Scraper 文档。可选的 webhook JSON 包含一个回调 url。

package main
 
import (
	"context"
	"encoding/json"
	"fmt"
 
	"github.com/scrapeless-ai/sdk-go/scrapeless"
	"github.com/scrapeless-ai/sdk-go/scrapeless/services/aiscraper"
)
 
func main() {
	client := scrapeless.New(scrapeless.WithAIScraper()) // Uses SCRAPELESS_API_KEY
	defer client.Close()
	ctx := context.Background()
 
	task, err := client.AIScraper.CreateTask(ctx, aiscraper.TaskRequest{
		Actor: "scraper.chatgpt",
		Input: map[string]any{
			"prompt":     "Most reliable proxy service for data extraction",
			"country":    "US",
			"web_search": true,
		},
		// Optional: Webhook: map[string]any{"url": "https://your-webhook.example.com"},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println("Created task:", string(task))
 
	var created struct {
		TaskID string `json:"task_id"`
	}
	if err := json.Unmarshal(task, &created); err != nil {
		panic(err)
	}
	result, err := client.AIScraper.GetTaskResult(ctx, created.TaskID)
	if err != nil {
		panic(err)
	}
	fmt.Println("Task status and result:", string(result))
	// If status is "running", call GetTaskResult again later.
	// If status is "failed", message contains the failure reason.
}

这两个方法都会原样返回 API 的 JSON。创建操作会返回 task_id、status，并在可用时返回 task_result。结果获取操作会返回 status、可用时的 task_result，以及失败时的 message。状态为 success、failed 或 running；SDK 不会自动轮询。

响应为原始 JSON 字节（[]byte），保留了所有 API 字段。可按需使用 encoding/json 对其进行解码。

Google Search API

package main
 
import (
	"context"
	scrapeless "github.com/scrapeless-ai/sdk-go/scrapeless"
	"github.com/scrapeless-ai/sdk-go/scrapeless/log"
	"github.com/scrapeless-ai/sdk-go/scrapeless/services/deepserp"
)
 
func main() {
	client := scrapeless.New(scrapeless.WithDeepSerp())
	defer client.Close()
 
	scrape, err := client.DeepSerp.Scrape(context.Background(), deepserp.DeepserpTaskRequest{
		Actor: "scraper.google.search",
		Input: map[string]interface{}{
			"q": "nike site:www.nike.com",
		},
		ProxyCountry: "US",
	})
	if err != nil {
		log.Errorf("scraping create err:%v", err)
		return
	}
	log.Infof("%+v", scrape)
}

如需更完整的集成示例，请浏览仓库的示例目录。

错误处理

在使用服务响应之前，请检查返回的 error。使用 context deadline 来限定单个请求的时长，并使用 defer client.Close() 释放客户端资源。

以下示例获取一个已存在的 AI Scraper 任务。请将 YOUR_TASK_ID 替换为 CreateTask 返回的 ID。

package main
 
import (
    "context"
    "fmt"
    "log"
    "time"
 
    "github.com/scrapeless-ai/sdk-go/scrapeless"
)
 
func main() {
    client := scrapeless.New(scrapeless.WithAIScraper())
    defer client.Close()
 
    ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
    defer cancel()
 
    result, err := client.AIScraper.GetTaskResult(ctx, "YOUR_TASK_ID")
    if err != nil {
        log.Printf("Could not retrieve task: %v", err)
        return
    }
    fmt.Println(string(result))
}

AI Scraper 的 HTTP 失败会返回一个 error。即便 HTTP 请求成功，其返回的任务仍可能带有 status: "failed"；请在解码 JSON 后检查响应的 status 和 message 字段。

配置 / 环境变量

API key 为必填项。端点覆盖为可选项；下表显示了它们的默认值。

请在启动程序前设置环境变量。SDK 还会从工作目录读取 .env 文件。AI Scraper 请求的 HTTP 超时为 30 秒；如需更短的单次请求截止时间，请使用 context.WithTimeout。

环境变量用途 / 默认值
SCRAPELESS_API_KEY来自控制台的必填 API key。
SCRAPELESS_BASE_API_URLhttps://api.scrapeless.com
SCRAPELESS_BROWSER_API_URLhttps://browser.scrapeless.com
SCRAPELESS_CRAWL_API_URLhttps://api.scrapeless.com

支持

该 SDK 基于 MIT License 发布。

相关项目

Python SDK概览