xcrawl-map

XCrawl Map

概要

このスキルは XCrawl Map API を使用して、サイトの URL を検出します。 デフォルトの動作は、生のレスポンスをそのまま返すことです。上流 API のレスポンス本文を変更せずに返します。

必須のローカル設定

このスキルを使用する前に、ユーザーはローカル設定ファイルを作成し、XCRAWL_API_KEY を記述する必要があります。

パス：~/.xcrawl/config.json

{
  "XCRAWL_API_KEY": "<your_api_key>"
}

API キーはローカル設定ファイルからのみ読み込みます。グローバル環境変数は要求しないでください。

クレジットとアカウントの設定

XCrawl API を使用するとクレジットを消費します。 アカウントを持っていない場合、または利用可能なクレジットがない場合は、https://dash.xcrawl.com/ での登録を案内してください。 登録後、リクエストを実行する前に無料の 1000 クレジットプランを有効化できます。

ツールの権限ポリシー

curl と node の実行時権限のみを要求してください。 Python、シェルヘルパースクリプト、その他の実行時権限は要求しないでください。

API の概要

• マップタスクを開始：POST /v1/map
• ベース URL：https://run.xcrawl.com
• 必須ヘッダー：Authorization: Bearer <XCRAWL_API_KEY>

使用例

cURL

API_KEY="$(node -e "const fs=require('fs');const p=process.env.HOME+'/.xcrawl/config.json';const k=JSON.parse(fs.readFileSync(p,'utf8')).XCRAWL_API_KEY||'';process.stdout.write(k)")"

curl -sS -X POST "https://run.xcrawl.com/v1/map" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{"url":"https://example.com","filter":"/docs/.*","limit":2000,"include_subdomains":true,"ignore_query_parameters":false}'

Node

node -e '
const fs=require("fs");
const apiKey=JSON.parse(fs.readFileSync(process.env.HOME+"/.xcrawl/config.json","utf8")).XCRAWL_API_KEY;
const body={url:"https://example.com",filter:"/docs/.*",limit:3000,include_subdomains:true,ignore_query_parameters:false};
fetch("https://run.xcrawl.com/v1/map",{
  method:"POST",
  headers:{"Content-Type":"application/json",Authorization:`Bearer ${apiKey}`},
  body:JSON.stringify(body)
}).then(async r=>{console.log(await r.text());});
'

リクエストパラメーター

リクエストエンドポイントとヘッダー

• エンドポイント：POST https://run.xcrawl.com/v1/map
• ヘッダー：
• Content-Type: application/json
• Authorization: Bearer <api_key>

リクエストボディ：トップレベルのフィールド

フィールド	型	必須	デフォルト	説明
url	string	はい	-	サイトのエントリー URL
filter	string	いいえ	-	URL に適用する正規表現フィルター
limit	integer	いいえ	5000	URL の最大数（最大 100000）
include_subdomains	boolean	いいえ	true	サブドメインを含める
ignore_query_parameters	boolean	いいえ	true	クエリパラメーターを含む URL を無視する

レスポンスパラメーター

フィールド	型	説明
map_id	string	タスク ID
endpoint	string	常に map
version	string	バージョン
status	string	completed
url	string	エントリー URL
data	object	URL リストのデータ
started_at	string	開始時刻（ISO 8601）
ended_at	string	終了時刻（ISO 8601）
total_credits_used	integer	使用したクレジットの合計

data のフィールド：

• links：URL リスト
• total_links：URL 数
• credits_used：使用したクレジット
• credits_detail：クレジットの内訳

ワークフロー

1. マッピングの目的を確認します。

• 検出のみ、選択的なクロールの計画、または構造分析。

2. POST /v1/map を構築して実行します。

• フィルターは明示的かつ再現可能な状態にします。

3. 生の API レスポンスをそのまま返します。

• 要求されない限り、URL ファミリーの要約を作成しないでください。

出力契約

以下を返します。

• 使用したエンドポイント（POST /v1/map）
• リクエストに使用した request_payload
• map 呼び出しの生のレスポンス本文
• リクエストが失敗した場合はエラーの詳細

ユーザーが明示的に要約を要求しない限り、要約を生成しないでください。

ガードレール

• limit に達した場合、サイト全体を網羅したと主張しないでください。
• 推測した URL と返された URL を混在させないでください。
• コアロジックにプロバイダー固有のツールスキーマをハードコードしないでください。