全部產品
Search

搜尋本產品

    AgentBay：瀏覽器持久化

    文件中心

    AgentBay：瀏覽器持久化

    更新時間：Oct 31, 2025

    瀏覽器持久化是無影 AgentBay SDK 的核心功能，可實現跨多個會話的持久瀏覽器狀態管理。允許在會話之間維護 Cookie、緩衝、本機存放區和其他瀏覽器資料，顯著減少反機器人檢測的幹擾並加快網頁載入速度。

    概述

    瀏覽器持久化代表一個持久的瀏覽器環境以儲存瀏覽器狀態，包括：

    • Cookie。

    • 緩衝。

    • 本機存放區。

    • 會話儲存。

    • 瀏覽器喜好設定。

    • 已安裝的擴充程式（當與擴充管理一起使用時）。

    優勢

    1. 減少反機器人檢測幹擾：通過維護瀏覽器狀態，網站會將會話識別為回訪使用者而不是新訪客。

    2. 更快的頁面載入速度：緩衝的資源和 Cookie 減少頁面載入時間。

    3. 會話連續性：在多個會話中繼續之前的操作。

    4. 一致的使用者體驗：保持使用者喜好設定和設定。

    Python 樣本

    基本用法

    from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams, BrowserContext

# 初始化 AgentBay 用戶端
agent_bay = AgentBay(api_key="your_api_key")

# 建立或擷取持久化上下文
context_result = agent_bay.context.get("my-browser-context", create=True)
context = context_result.context

# 使用持久化建立瀏覽器會話
browser_context = BrowserContext(
    context_id=context.id,
    auto_upload=True
)

session_params = CreateSessionParams(
    image_id="browser-image-id",
    browser_context=browser_context
)

session_result = agent_bay.create(session_params)
session = session_result.session

    Cookie 持久化

    import time
from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams, BrowserContext
from agentbay.browser.browser import BrowserOption
from playwright.sync_api import sync_playwright

# 初始化 AgentBay
agent_bay = AgentBay(api_key="your_api_key")

# 建立持久化上下文
context_result = agent_bay.context.get("cookie-demo-context", create=True)
context = context_result.context

# 第一個會話 - 設定 cookie
browser_context = BrowserContext(
    context_id=context.id,
    auto_upload=True
)

params = CreateSessionParams(
    image_id="browser-image-id",
    browser_context=browser_context
)

session1 = agent_bay.create(params).session

# 在第一個會話中設定 cookie
session1.browser.initialize(BrowserOption())
endpoint_url = session1.browser.get_endpoint_url()

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(endpoint_url)
    context_p = browser.contexts[0] if browser.contexts else browser.new_context()
    page = context_p.new_page()
    
    # 導航並設定 cookie
    page.goto("https://example.com")
    context_p.add_cookies([
        {
            "name": "session_cookie",
            "value": "session_value",
            "domain": "example.com",
            "path": "/",
        }
    ])
    
    browser.close()

# 刪除帶有上下文同步的第一個會話
agent_bay.delete(session1, sync_context=True)

# 第二個會話 - 驗證 cookie 是否持久化
session2 = agent_bay.create(params).session

# 在第二個會話中檢查 cookie
session2.browser.initialize(BrowserOption())
endpoint_url2 = session2.browser.get_endpoint_url()

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(endpoint_url2)
    context_p = browser.contexts[0] if browser.contexts else browser.new_context()
    
    # 驗證 cookie 是否持久化
    cookies = context_p.cookies()
    print(f"持久化的 cookie: {cookies}")
    
    browser.close()

    TypeScript 樣本

    基本用法

    import { AgentBay, CreateSessionParams, BrowserContext } from 'wuying-agentbay-sdk';

// 初始化 AgentBay 用戶端
const agentBay = new AgentBay({ apiKey: "your_api_key" });

// 建立或擷取持久化上下文
const contextResult = await agentBay.context.get("my-browser-context", true);
const context = contextResult.context;

# 建立帶持久化的瀏覽器會話
const browserContext: BrowserContext = {
    contextId: context.id,
    autoUpload: true
};

const params = new CreateSessionParams()
    .withImageId("browser-image-id")
    .withBrowserContext(browserContext);

const sessionResult = await agentBay.create(params);
const session = sessionResult.session;

    Cookie 持久化

    import { AgentBay, CreateSessionParams, BrowserContext, BrowserOption } from 'wuying-agentbay-sdk';
import { chromium } from 'playwright';

# 初始化 AgentBay
const agentBay = new AgentBay({ apiKey: "your_api_key" });

# 建立持久化上下文
const contextResult = await agentBay.context.get("cookie-demo-context", true);
const context = contextResult.context;

# 第一個會話 - 設定 cookie
const browserContext: BrowserContext = {
    contextId: context.id,
    autoUpload: true
};

const params = new CreateSessionParams()
    .withImageId("browser-image-id")
    .withBrowserContext(browserContext);

const session1 = (await agentBay.create(params)).session;

# 在第一個會話中設定 cookie
await session1.browser.initializeAsync(new BrowserOption());
const endpointUrl = session1.browser.getEndpointUrl();

const browser = await chromium.connectOverCDP(endpointUrl);
const contextP = browser.contexts()[0] || await browser.newContext();
const page = await contextP.newPage();

# 導航並設定 cookie
await page.goto("https://example.com");
await contextP.addCookies([
    {
        name: "session_cookie",
        value: "session_value",
        domain: "example.com",
        path: "/",
    }
]);

await browser.close();

# 刪除帶有上下文同步的第一個會話
await agentBay.delete(session1, true);

# 第二個會話 - 驗證 cookie 是否持久化
const session2 = (await agentBay.create(params)).session;

# 在第二個會話中檢查 cookie
await session2.browser.initializeAsync(new BrowserOption());
const endpointUrl2 = session2.browser.getEndpointUrl();

const browser2 = await chromium.connectOverCDP(endpointUrl2);
const contextP2 = browser2.contexts()[0] || await browser2.newContext();

# 驗證 cookie 是否持久化
const cookies = await contextP2.cookies();
console.log(`持久化的 cookie: ${JSON.stringify(cookies)}`);

await browser2.close();

    推薦用法

    1. 使用描述性的上下文名稱：根據用途命名內容（例如：ecommerce-scraping、social-media-automation）。

    2. 啟用自動上傳：設定 auto_upload=True 以在會話結束時自動同步瀏覽器資料。

    3. 清理資源：完成操作後刪除會話以釋放雲資源。

    4. 優雅地處理錯誤：為上下文操作實現適當的錯誤處理。

    5. 重用上下文：在多個會話中重用相同的上下文以保持連續性。

    進階功能

    上下文同步策略

    from agentbay.context_sync import SyncPolicy

# 建立自訂同步策略
policy = SyncPolicy(
    upload=True,
    extract=True,
    white_list=["/cookies.json", "/storage/"],
    black_list=["/cache/large_files/"]
)

# 使用上下文同步
context_sync = ContextSync.new(
    context_id=context.id,
    path="/browser-data",
    policy=policy
)

    多個上下文

    # 為不同網站建立單獨的上下文
ecommerce_context = agent_bay.context.get("ecommerce-site", create=True).context
social_context = agent_bay.context.get("social-media", create=True).context

# 對不同會話使用不同的上下文
ecommerce_session_params = CreateSessionParams(
    browser_context=BrowserContext(ecommerce_context.id, True)
)

social_session_params = CreateSessionParams(
    browser_context=BrowserContext(social_context.id, True)
)

    錯誤處理

    try:
    context_result = agent_bay.context.get("my-context", create=True)
    if not context_result.success:
        print(f"建立上下文失敗: {context_result.error_message}")
        
    session_result = agent_bay.create(session_params)
    if not session_result.success:
        print(f"建立會話失敗: {session_result.error_message}")
        
except Exception as e:
    print(f"發生錯誤: {e}")