Python SDK

概要

公式のScrapelessPython SDKは、ブラウザ自動化、スクレイピング、クロール、プロキシ、検索結果、AIチャット抽出にアクセスできます。このガイドは SDKリポジトリのREADMEに従っており、実行可能な例と設定の詳細を含んでいます。

必要条件

Python 3.8以降はパッケージメタデータで宣言されています。ブラウザ統合は、インストールされたPlaywrightまたはPyppeteerのバージョンに応じて、より新しいPythonバージョンを必要とする場合があります。

仮想環境を使用して、他のプロジェクトからSDKの依存関係を分離してください。

インストール

pip install scrapeless

リポジトリは python-dotenv を使用して環境変数を読み込みますが、現在のパッケージメタデータにはその依存関係が記載されていません。必要に応じて、SDKとともにインストールしてください：

pip install python-dotenv

対応するブラウザ統合を使用する際は、 pyppeteer または playwright を個別にインストールしてください。

認証 / APIキー

Scrapelessダッシュボードにログインし、APIキーを作成してください。例を実行する前にエクスポートしてください：

export SCRAPELESS_API_KEY="YOUR_API_KEY"

ソース管理にコミットする代わりに、APIキーは環境変数またはシークレットマネージャーに保存してください。

Scrapeless() SCRAPELESS_API_KEYを読み込みます。クライアント設定辞書に api_key エントリを渡すこともできます。

クイックスタート

このコードを quickstart.py として保存します。実行コマンドは python quickstart.py で、あらかじめAPIキーを設定してください。

from scrapeless import Scrapeless
from scrapeless.types import UniversalScrapingRequest
 
client = Scrapeless()
result = client.universal.scrape(UniversalScrapingRequest(
    actor='unlocker.webunlocker',
    input={'url': 'https://example.com', 'method': 'GET', 'redirect': False}
))
print(result)

製品対応マトリクス

製品	SDKサービス	対応範囲
Scraping Browser	`client.browser`	リモートブラウザセッションの作成と管理。
ブラウザプロファイル	`client.profiles`	セッション間でブラウザのデータを保持。
Scraping API	`client.scraping`	ウェブサイトアクターを使用して構造化データを抽出。
Web Unlocker	`client.universal`	保護されたウェブサイトからコンテンツを取得。
クローリング	`client.scraping_crawl`	ページをスクレイピングまたはウェブサイトをクロール。
Google Search API	`client.deepserp`	検索エンジンの結果を抽出。
Proxies	`client.proxies`	プロキシ接続URLを生成。
AI Scraper	`client.ai_scraper`	AIチャットタスクを作成し、そのステータスと結果を取得。

使用例

ブラウザ

ブラウザ統合を pip install pyppeteerでインストールしてください。

fingerprintの偽装やCAPTCHAの解決など、カスタマイズ可能な不正検知回避機能と拡張可能な自動化ワークフローを備えた、PlaywrightおよびPyppeteerフレームワークをサポートする高度なブラウザセッション管理：

from scrapeless import Scrapeless
from scrapeless.types import ICreateBrowser
import asyncio
import pyppeteer
 
client = Scrapeless()
 
 
async def example():
    # Create a browser session
    config = ICreateBrowser(
        session_name='sdk_test',
        session_ttl=180,
        proxy_country='US',
        session_recording=True
    )
    session = client.browser.create(config).__dict__
    browser_ws_endpoint = session['browser_ws_endpoint']
    print('Browser WebSocket endpoint created:', browser_ws_endpoint)
 
    # Connect to browser using pyppeteer
    browser = await pyppeteer.connect({'browserWSEndpoint': browser_ws_endpoint})
    try:
        page = await browser.newPage()
        await page.goto('https://example.com')
        print(await page.title())
    finally:
        await browser.close()
 
 
asyncio.run(example())

ブラウザプロファイル

永続的なセッション用にブラウザプロファイルを管理します。

from scrapeless import Scrapeless
 
client = Scrapeless()
profile = client.profiles.create('My Profile')
print(profile)

Scraping API

ウェブサイト（例：eコマース、旅行プラットフォーム）向けの直接データ抽出API。事前構築されたコネクタで、構造化された商品情報、価格、レビューを取得します：

from scrapeless import Scrapeless
from scrapeless.types import ScrapingTaskRequest
 
client = Scrapeless()
request = ScrapingTaskRequest(
    actor='scraper.google.search',
    input={'q': 'nike site:www.nike.com'}
)
result = client.scraping.scrape(request=request)
print(result)

Web Unlocker

Web Unlocker（ client.universalとして公開）を使用して、ウェブサイトからデータを抽出します。

from scrapeless import Scrapeless
from scrapeless.types import UniversalScrapingRequest
 
client = Scrapeless()
result = client.universal.scrape(UniversalScrapingRequest(
    actor='unlocker.webunlocker',
    input={'url': 'https://example.com', 'method': 'GET', 'redirect': False}
))
print(result)

クローリング

単一ページからデータを抽出するか、ドメイン全体を走査して、Markdown、JSON、HTML、スクリーンショット、リンクなどの形式でエクスポートします。

from scrapeless import Scrapeless
 
client = Scrapeless()
 
result = client.scraping_crawl.scrape_url("https://example.com")
print(result)

プロキシ

ゲートウェイとセッション設定を使用してプロキシのURLを生成します。

from scrapeless import Scrapeless
from scrapeless.types import ICreateProxy
 
client = Scrapeless()
proxy_url = client.proxies.proxy(ICreateProxy(
    country='US',
    session_duration=30,
    session_id=client.proxies.generate_session_id(),
    gateway='your-proxy-gateway:port'
))
print(proxy_url)

AI Scraper

AIチャットのコンテンツを一括抽出して、ブランドの言及を監視したり、回答を比較したり、最新モデルからの競合情報分析を行ったりできます。1つの統合でURL、プロンプト、Markdown形式の回答、引用文献などを取得できます。

サポートされているアクターには scraper.chatgpt、 scraper.perplexity、 scraper.copilot、 scraper.gemini、 scraper.aimode、 scraper.overview、 scraper.grok、 scraper.alexaが含まれます。 input JSONの動作はactorに依存します。詳細なパラメータについては AI Scraperドキュメントを参照してください。オプションの webhook JSONにはコールバック urlが含まれます。

from scrapeless import Scrapeless
from scrapeless.types import AIScraperTaskRequest
 
 
def main():
    client = Scrapeless()  # Uses SCRAPELESS_API_KEY
    task = client.ai_scraper.create_task(AIScraperTaskRequest(
        actor='scraper.chatgpt',
        input={
            'prompt': 'Most reliable proxy service for data extraction',
            'country': 'US',
            'web_search': True,
        },
        # Optional: webhook={'url': 'https://your-webhook.example.com'},
    ))
    print('Created task:', task)
 
    result = client.ai_scraper.get_task_result(task['task_id'])
    print('Task status and result:', result)
    # If status is 'running', call get_task_result again later.
    # If status is 'failed', message contains the failure reason.
 
 
if __name__ == '__main__':
    main()

どちらのメソッドも、APIJSONを変更せずに返します。作成時には task_id、 status、および利用可能な場合は task_resultを返します。結果の取得時には、利用可能な場合は status、 task_result 、失敗時には message を返します。ステータスは success、 failed、または runningです。SDKは自動的にポーリングしません。

create_task AIScraperTaskRequest または辞書を受け入れます。辞書では追加のAPIパラメーターも指定可能です。レスポンスは辞書形式です。

Google Search API

from scrapeless import Scrapeless
from scrapeless.types import ScrapingTaskRequest
 
client = Scrapeless()
result = client.deepserp.scrape(ScrapingTaskRequest(
    actor='scraper.google.search',
    input={'q': 'nike site:www.nike.com'}
))
print(result)

より完全な統合の例については、リポジトリの examples ディレクトリを参照してください。

エラー処理

ScrapelessError をキャッチしてAPIリクエストの失敗を処理します。タスク失敗を処理するには、AI Scraperレスポンスの status を別途確認してください。

from scrapeless import Scrapeless, ScrapelessError
from scrapeless.types import UniversalScrapingRequest
 
client = Scrapeless()
try:
    result = client.universal.scrape(UniversalScrapingRequest(
        actor='unlocker.webunlocker',
        input={'url': 'https://example.com', 'method': 'GET'}
    ))
    print(result)
except ScrapelessError as error:
    print(f'Scrapeless API error: {error}')

現在のPython例外はエラーメッセージを公開していますが、 status_code 属性は定義していません。

設定 / 環境変数

APIキーは必須です。エンドポイントの上書きは任意です。表にはデフォルト値が示されています。

構成を上書きするには、辞書を Scrapeless に渡します。

import os
from scrapeless import Scrapeless
 
client = Scrapeless({
    'api_key': os.environ['SCRAPELESS_API_KEY'],
    'timeout': 30000,  # Request timeout in milliseconds
    'base_api_url': 'https://api.scrapeless.com',
    'browser_api_url': 'https://browser.scrapeless.com',
    'scraping_crawl_api_url': 'https://api.scrapeless.com',
})

明示的な設定は環境変数よりも優先されます。デフォルトのリクエストタイムアウトは30,000ミリ秒です。

環境変数	目的 / デフォルト値
`SCRAPELESS_API_KEY`	ダッシュボードからの必須のAPIキー。
`SCRAPELESS_BASE_API_URL`	`https://api.scrapeless.com`
`SCRAPELESS_BROWSER_API_URL`	`https://browser.scrapeless.com`
`SCRAPELESS_CRAWL_API_URL`	`https://api.scrapeless.com`

サポート

SDKは MITライセンスの下で公開されています。