ドキュメント開発者ツールSDKsNode.js / TypeScript SDK

Node.js SDK

概要

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

必要条件

npm、pnpm、またはYarnでNode.jsを使用してください。 パッケージマニフェスト は最小のNode.jsバージョンを宣言していません。リポジトリの公開ワークフローではNode.js20を使用しています。JavaScriptおよびTypeScriptがサポートされており、ESモジュールとCommonJSの両方のエクスポートがあります。

以下の例はESモジュールを使用しています。それらを .mjs ファイルとして保存するか、プロジェクトの "type": "module" で package.jsonを設定してください。

インストール

npm install @scrapeless-ai/sdk

また、 pnpm add @scrapeless-ai/sdk または yarn add @scrapeless-ai/sdkを使用することもできます。

認証 / APIキー

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

export SCRAPELESS_API_KEY="YOUR_API_KEY"

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

new Scrapeless() SCRAPELESS_API_KEYを読み込みます。クライアントの構築時にオプションとして apiKey を渡すこともできます。

クイックスタート

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

import { Scrapeless } from '@scrapeless-ai/sdk';
 
const client = new Scrapeless();
const result = await client.universal.scrape({
  actor: 'unlocker.webunlocker',
  input: { url: 'https://example.com', method: 'GET', redirect: false }
});
console.log(result);

製品対応マトリクス

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

使用例

例が独自のクライアントを初期化しない限り、クイックスタートの const client = new Scrapeless() を再利用してください。

ブラウザ

この例では、Puppeteerをインストールしてください： npm install puppeteer-core。PlaywrightおよびSDKのブラウザラッパーについては、 ブラウザ統合の例を参照してください。

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

import { Scrapeless } from '@scrapeless-ai/sdk';
import puppeteer from 'puppeteer-core';
 
const client = new Scrapeless();
 
// Create a browser session
const { browserWSEndpoint } = await client.browser.create({
  sessionName: 'my-session',
  sessionTTL: 180,
  proxyCountry: 'US'
});
 
// Connect with Puppeteer
const browser = await puppeteer.connect({
  browserWSEndpoint: browserWSEndpoint
});
 
try {
  const page = await browser.newPage();
  await page.goto('https://example.com');
  console.log(await page.title());
} finally {
  await browser.close();
}

ブラウザプロファイル

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

const createResponse = await client.profiles.create('My Profile');
console.log('Profile created:', createResponse);
 
const profiles = await client.profiles.list({ page: 1, pageSize: 10 });
console.log('Profiles:', profiles.docs);
 
const profile = await client.profiles.get(createResponse.profileId);
console.log('Profile details:', profile);
 
// Delete the profile when it is no longer needed.
await client.profiles.delete(createResponse.profileId);

Scraping API

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

const result = await client.scraping.scrape({
  actor: 'scraper.google.search',
  input: {
    'q': 'coffee',
    'hl': 'en',
    'gl': 'us'
  }
});
 
console.log(result.data);

Web Unlocker

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

const result = await client.universal.scrape({
  actor: 'unlocker.webunlocker',
  input: { url: 'https://example.com', method: 'GET', redirect: false }
});
console.log(result);

クローリング

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

const result = await client.scrapingCrawl.scrapeUrl('https://example.com');
 
console.log(result);

プロキシ

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

const proxyUrl = client.proxies.proxy({
  type: 'residential',
  country: 'US',
  sessionDuration: 30,
  sessionId: client.proxies.generateSessionId(),
  gateway: 'your-proxy-gateway:port'
});
console.log(proxyUrl);

AI Scraper

タスクを作成します： client.aiScraper.createTask(request)

必須の actor と、actor固有の inputを渡します。任意の webhook オブジェクトには、コールバック用の urlを指定できます。Promiseが解決すると、完全なAPIレスポンスが返されます。レスポンスには task_id と statusが含まれ、利用可能な場合は task_result も含まれます。

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

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

import { Scrapeless } from '@scrapeless-ai/sdk';
 
const client = new Scrapeless(); // Uses SCRAPELESS_API_KEY
 
const task = await client.aiScraper.createTask({
  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' }
});
console.log('Created task:', task);

タスクのステータスと結果を取得します： client.aiScraper.getTaskResult(taskId)

作成時に得られた task_id を渡します。同じスクリプト内で続行するか、IDを保存して後からリクエストで結果を取得します。

const result = await client.aiScraper.getTaskResult(task.task_id);
 
switch (result.status) {
  case 'success':
    console.log('Task result:', result.task_result);
    break;
  case 'failed':
    console.error('Task failed:', result.message);
    break;
  case 'running':
    console.log('Task is running. Retrieve the result again later.');
    break;
}

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

ステータス意味次のステップ
runningタスクはまだ処理中です。後で再び getTaskResult を呼び出すか、webhookを使用してください。
successタスクが完了しました。結果は task_resultから読み取ります。その構造はactorによって異なります。
failedタスクは完了できませんでした。失敗の理由は message を参照してください。

作成時に既に結果が含まれている場合があります。さらにリクエストをスケジュールする前に、そのステータスを確認してください。ポーリングを実装する場合は、遅延と全体的なタイムアウトを使用します。

Google Search API

const result = await client.deepserp.scrape({
  actor: 'scraper.google.search',
  input: { q: 'nike site:www.nike.com' }
});
console.log(result);

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

エラー処理

ScrapelessError をキャッチしてAPIリクエストの失敗を処理します。タスクはエラーをスローせずに終了する可能性があるため、AI Scraperレスポンスの status は別途確認してください：タスクは failed を返すことができますが、その際HTTPリクエストがエラーをスローしない場合があります。

import { Scrapeless, ScrapelessError } from '@scrapeless-ai/sdk';
 
try {
  const client = new Scrapeless();
  const result = await client.universal.scrape({
    actor: 'unlocker.webunlocker',
    input: { url: 'https://example.com', method: 'GET' }
  });
  console.log(result);
} catch (error) {
  if (error instanceof ScrapelessError) {
    console.error('Scrapeless error:', error.message);
    console.error('Status code:', error.statusCode);
  } else {
    throw error;
  }
}

設定 / 環境変数

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

import { Scrapeless } from '@scrapeless-ai/sdk';
 
const client = new Scrapeless({
  apiKey: process.env.SCRAPELESS_API_KEY,
  timeout: 30000, // Request timeout in milliseconds
  baseApiUrl: 'https://api.scrapeless.com',
  browserApiUrl: 'https://browser.scrapeless.com',
  scrapingCrawlApiUrl: 'https://api.scrapeless.com'
});

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

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

サポート

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

関連プロジェクト

SDK の概要Python SDK