> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # WebExtrator ウェブレンダリング API 統合ガイド > WebExtrator Web Render & Extract API guide - Ace Data Cloud `POST https://api.acedata.cloud/webextrator/render` WebExtrator ウェブレンダリング API は、ヘッドレス Chromium に基づくウェブレンダリングサービスです。URL を指定すると、完全にレンダリングされた HTML（JS 注入の内容を含む）、プレーンテキスト、ページタイトル、最終 URL を返します。 Render は WebExtrator の最も基本的なインターフェースです。**構造化された**抽出結果（記事本文、商品価格、レシピの材料など）が必要な場合は、[`/webextrator/extract`](development_webextrator_extract) を使用してください。これは同じレンダリング基盤の上で、型付き抽出パイプラインを実行します。 ## 申請プロセス WebExtrator サービスページを使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) で API トークンを取得し、バックアップとして保管してください。 ![](https://cdn.acedata.cloud/5hmkdg.jpg) まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。 **1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。** 初回申請時には無料枠が付与され、無料で体験できます。枠が不足した場合は、[コンソール](https://platform.acedata.cloud/console/coin) で共通残高をチャージできます。 > 📘 完全なドキュメント：[WebExtrator サービスページ →](https://platform.acedata.cloud/service/webextrator) ## 認証 すべての WebExtrator インターフェースは、標準の Bearer トークン認証を使用します： ``` Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` ## リクエストパラメータ | フィールド | タイプ | 必須 | デフォルト | 説明 | | ------------------- | --------- | :-: | -------------------------- | -------------------------------------------------------------------------------- | | `url` | string | ✅ | — | レンダリングするページの URL、必ず `http(s)://` である必要があります。 | | `user_agent` | string | ❌ | 内蔵 UA プールのローテーション | カスタム User-Agent。 | | `timeout` | number | ❌ | `30` | 単一ナビゲーションのタイムアウト（**秒**）。 | | `wait_until` | enum | ❌ | `networkidle` | ロード完了イベント：`load` / `domcontentloaded` / `networkidle` / `commit`。 | | `delay` | number | ❌ | `0` | `wait_until` トリガー後の**追加待機秒数**（SPA の二次レンダリングに使用）。 | | `wait_for_selector` | string | ❌ | — | この CSS セレクタが出現するのを待ちます。`networkidle` よりも安定しています。 | | `block_resources` | string\[] | ❌ | `["image","font","media"]` | ブロックするリソースタイプ、オプション：`image` / `font` / `media` / `stylesheet` / `xhr` / `fetch`。 | | `headers` | object | ❌ | — | 追加の HTTP リクエストヘッダー（例：`{"Accept-Language": "en-US"}`）。 | | `cookies` | array | ❌ | — | ナビゲーション前に注入される Cookie、構造は以下の通り。 | | `callback_url` | string | ❌ | — | 非同期モードでのコールバックアドレス、プラットフォームはタスク完了時にこのアドレスに結果を `POST` します。 | | `bypass_cache` | boolean | ❌ | `false` | Redis キャッシュの読み取りをスキップします（ただし、今回の結果はキャッシュに書き戻されます）。 | | `cache_ttl_seconds` | number | ❌ | `3600` | 今回書き込むキャッシュの TTL をカスタマイズします。`0` を指定すると、今回のレスポンスはキャッシュされません。 | | `async` | boolean | ❌ | `false` | `true` に設定すると、すぐに `task_id` を返し、結果は `callback_url` または Tasks API で取得します。 | > プラットフォームの契約はすべて **snake\_case** を使用します。内部レンダリングサービスは camelCase をサポートしていますが、外部呼び出しはすべて snake\_case を使用します。 ### Cookie 構造 ```json theme={null} { "name": "string", "value": "string", "domain": "string", "path": "/", "expires": 1735689600, "httpOnly": false, "secure": true, "sameSite": "Lax" } ``` ## 同期レスポンス ```json theme={null} { "success": true, "task_id": "550e8400-e29b-41d4-a716-446655440000", "trace_id": "550e8400-e29b-41d4-a716-446655440001", "started_at": 1777717800.123, "finished_at": 1777717801.234, "elapsed": 1.111, "data": { "kind": "render", "url": "https://example.com", "finalUrl": "https://example.com/", "title": "Example Domain", "status": 200, "html": "...", "text": "Example Domain\nThis domain is for use in illustrative examples...", "userAgent": "Mozilla/5.0 ...", "elapsedMs": 1108 } } ``` | フィールド | タイプ | 説明 | | -------------------- | -------------- | ------------------------------------------------------------------------ | | `data.kind` | string | 固定 `"render"`。 | | `data.url` | string | 提出した URL。 | | `data.finalUrl` | string | リダイレクト後の最終 URL。 | | `data.title` | string | レンダリング後の `document.title`。 | | `data.status` | number \| null | メインナビゲーションの HTTP ステータスコード。 | | `data.html` | string | 完全なレンダリング後の HTML。 | | `data.text` | string | `document.body.innerText` のスナップショット（よりクリーンな本文が必要な場合は Extract を使用してください）。 | | `data.userAgent` | string | 実際に使用された UA。 | | `data.elapsedMs` | number | ブラウザレンダリングにかかった時間。 | | `data.cached` | boolean? | キャッシュにヒットした場合は `true`。 | | `data.cacheStoredAt` | number? | キャッシュエントリが最初に書き込まれた Unix ミリ秒タイムスタンプ。 | ## 非同期レスポンス `async=true`（または `callback_url` を提供）時に即座に返されます（HTTP 200）： ```json theme={null} { "success": true, "task_id": "550e8400-...", "trace_id": "6ba7b810-...", "started_at": 1777717800.123 } ``` 結果は `callback_url` に `POST` でプッシュされます（設定されている場合）、または [`/webextrator/tasks`](development_webextrator_tasks) で積極的にクエリできます。 ### コールバック構造 プラットフォームは `callback_url` に同期モードと**完全に同じ**エンベロープを `POST` します。 `Content-Type: application/json`。任意の `2xx` を返すと確認されたと見なされます；`5xx` は 指数バックオフで約 5 分間再試行されます。 ## エラーレスポンス | HTTP | `error.code` | 含义 | | ---- | ---------------- | ----------------------------------------------------- | | 400 | `bad_request` | リクエストボディが Zod 検証に失敗しました（`url` が欠落、タイプが不正など）。 | | 401 | `unauthorized` | 無効または欠落している `Authorization: Bearer …`。 | | 402 | (x402) | プラットフォームの残高が不足しており、x402 支払い要求 envelope を返します。 | | 408 | `timeout` | ナビゲーションが `timeout` を超えました。 | | 429 | `queue_busy` | 同期キューが混雑しています。再試行するか、`async=true` を使用してください。 | | 500 | `internal_error` | サーバー側で未処理の例外が発生しました（ブラウザのクラッシュなど）、Worker が自動的に再試行します。 | エラー構造： ```json theme={null} { "success": false, "task_id": "...", "trace_id": "...", "started_at": 1777717800.123, "finished_at": 1777717800.135, "elapsed": 0.012, "error": { "code": "bad_request", "message": "url: 無効な url" } } ``` ## サンプル ### cURL ```bash theme={null} curl -X POST https://api.acedata.cloud/webextrator/render \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "wait_until": "networkidle", "block_resources": ["image", "media", "font"] }' ``` ### Python (requests) ```python theme={null} import os, requests API_KEY = os.environ["ACEDATA_API_KEY"] resp = requests.post( "https://api.acedata.cloud/webextrator/render", headers={ "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", }, json={ "url": "https://example.com", "wait_until": "networkidle", "block_resources": ["image", "media", "font"], }, timeout=60, ) resp.raise_for_status() data = resp.json()["data"] print(data["title"], data["status"], len(data["html"])) ``` ### Node.js (fetch) ```js theme={null} const apiKey = process.env.ACEDATA_API_KEY; const res = await fetch('https://api.acedata.cloud/webextrator/render', { method: 'POST', headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ url: 'https://example.com', wait_until: 'networkidle', block_resources: ['image', 'media', 'font'], }), }); const { data } = await res.json(); console.log(data.title, data.status, data.html.length); ``` ### 非同期 + コールバック ```bash theme={null} curl -X POST https://api.acedata.cloud/webextrator/render \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "async": true, "callback_url": "https://your-app.example.com/hooks/webextrator" }' ``` 即座に `{ "success": true, "task_id": "...", "trace_id": "...", "started_at": 1777717800.123 }` を返します； タスクが完了すると、プラットフォームはあなたの `callback_url` に完全な結果を POST します。 ### キャッシュを強制的にバイパス ```bash theme={null} curl -X POST https://api.acedata.cloud/webextrator/render \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "bypass_cache": true }' ``` ## ヒントと落とし穴 * **`wait_until` の選択は非常に重要です。** `networkidle` は最も安定していますが最も遅い；`domcontentloaded` は速いですが非同期で注入された内容を見逃す可能性があります；`load` は従来の静的ページに適しています。 * **キャッシュキーは `async` を無視します。** 同じ URL の同期と非同期リクエストは同じキャッシュエントリにヒットし、 自由に切り替えても無効になりません。 * **キャッシュキーは `bypass_cache` と `cache_ttl_seconds` を無視します。** これらは操作スイッチであり、 応答内容には影響しません。 * **`cookies` と `headers` はバケットキャッシュを分けます。** これらをカスタマイズすると、最初の同じ組み合わせのヒットが失敗します。 * **重い SPA はデフォルトの 30 秒を超えることがよくあります。** `timeout: 60`、`wait_until: "domcontentloaded"`、`delay: 4` を推奨し、さらに `wait_for_selector` で本当に関心のある 要素を待ちます。 * **`block_resources` は遅延を減らす最も早い方法です。** デフォルトで画像 / フォント / メディアはブロックされています； CSS レイアウトに依存しない抽出を行う場合、`stylesheet` を追加するとさらに速くなります。