mcpField
S
scrape-zyte-api-stats

scrape-zyte-api-stats

github.com/zytedataデータ・データベース11145 回インストール2 日前に更新
リポジトリ

scrape-zyte-api-stats について

同梱スクリプトで過去の Zyte API 使用統計を取得する Claude スキルです。プロジェクト設定から組織を特定し、Stats API の応答を提示用に返します。

主な機能

  1. 01プロジェクト設定から組織を特定
  2. 02過去の使用統計を照会
  3. 03期間とフィルターを指定
  4. 04ページネーションと空の結果に対応

活用シーン

  1. 01指定期間の使用状況を確認
  2. 02対応フィルターで統計を照会
  3. 03複数ページにわたって結果を取得

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/zytedata/skills --skill scrape-zyte-api-stats

インストール後、Claude Code で/scrape-zyte-api-statsを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

scripts/
auth.py
project_org_lookup.py
zyte_api_stats.py
tests/
test_project_org_lookup.py

詳細

このスキルに同梱されているラッパーを使って、過去の Zyte API 使用状況の統計を照会します。 同梱のスクリプトが認証、プロジェクトの検索、再試行を処理するため、API キーがモデルに公開されることはありません。統計ラッパーは Stats API の生の JSON レスポンスを返します。エージェントは、そのデータをユーザーに提示する責任があります。

このスキルは、すでに発生した過去の使用状況を照会するためのものであり、予測、ダッシュボードの設定、ドキュメント、設定方法の案内を目的としたものではありません。

必ず最初にプロジェクト検索ヘルパーを実行して organization_id を特定してください。

  1. プロジェクト検索ヘルパーを実行します。
uv run --no-project "${CLAUDE_SKILL_DIR}/scripts/project_org_lookup.py"
  1. JSON のステータスを確認し、次の分岐に従います。
    • resolved_project_with_organization：返された organization_id を統計クエリに使用します。ペイロードに projects リストも含まれている場合、ヘルパーは同じ組織に属する設定済みプロジェクトを複数検出し、安全にまとめています。
    • multiple_projects_found：ペイロードに organizations リストが含まれている場合は、検出された安全な組織の選択肢から選ぶようユーザーに依頼します。プロジェクト名から選ばせたり、生の組織 ID や生のプロジェクト ID を入力させたりしないでください。各選択肢は、返されたとおりの organization_id で提示し、対応する selection の値は非公開のまま保持して、ヘルパーを --project 付きで再実行してください。organizations リストがない場合は、提示されたプロジェクトに基づいて選択してもらいます。
    • no_project_configured または organization_lookup_failed：プロジェクトと認証情報を設定するために /scrape-zyte-login を使用してから、クエリを再試行するようユーザーに伝えてください。最終的にユーザーへ提示するメッセージでは、/scrape-zyte-login を明示してください。これらの分岐では、生の組織 ID や生のプロジェクト ID を代替手段として提示しないでください。

プロジェクト検索ヘルパーは、標準の shub 設定（プロジェクトルートの scrapinghub.yml、~/.scrapinghub.yml、または環境変数）からプロジェクト ID を読み取り、Zyte のプロジェクトエンドポイントを呼び出して organization_id を特定します。このスキルでは、これが許可されています。認証情報の値を直接読み取ったり、表示したりしないでください。

検出された複数の組織またはプロジェクトの選択肢からユーザーが選んだ場合は、対応する selection またはプロジェクトの値を指定してヘルパーを再実行します。

uv run --no-project "${CLAUDE_SKILL_DIR}/scripts/project_org_lookup.py" --project 2

Wrapper

uv でラッパーを実行し、クエリパラメーターを JSON オブジェクトとして渡します。

uv run --no-project "${CLAUDE_SKILL_DIR}/scripts/zyte_api_stats.py" \
	--params '{"organization_id": 3}'

スキルのランタイムから提供される ${CLAUDE_SKILL_DIR} を使用してください。一時的な代入が適用される前にスクリプトのパスが展開される可能性があるため、同じコマンドの先頭にインラインの CLAUDE_SKILL_DIR=... を付けないでください。

--params は Stats API のドキュメントに基づいて直接作成してください。ラッパーはパラメーター名を変換したり、検証したりしません。

ラッパーは Stats API の生の JSON オブジェクトを出力します。内容を読み取り、結果は自分でユーザー向けに整えてください。ユーザー向けの説明は、返された JSON の内容に基づくものにしてください。API が返したもの以外のフィールドが存在すると想定しないでください。

ユーザーが last 7 days、last 30 days、this month のように明示的な相対期間を指定した場合は、具体的な UTC の start_time／end_time の組み合わせを 1 つ算出し、その値を --params に渡してください。このワークフローはシンプルに保ち、必要に応じて簡潔な算出手順を 1 回だけ行い、シェルでの試行を繰り返さないでください。

ユーザーが期間を指定せずに recent の利用状況を尋ねた場合は、API のデフォルト期間が適用されるように start_time と end_time を完全に省略してください。

JSON の results リストが空の場合、要約を捏造せず、そのクエリに該当するデータがなかったことをユーザーに伝えてください。

page、page_size、total_result_count などの API フィールドを使って、ページがほかにもあるか判断してください。次のページを取得する場合は、ほかのクエリパラメーターをすべてそのままにして、page だけをインクリメントしてください。

説明はラッパーの出力に基づいてください。ラッパーがデータとして返していない日付、原因、機能に関する解釈、その他の結論を追加しないでください。JSON の応答が明示的に裏付けていない限り、コストの変化、応答時間、ステータスコードの内訳から、キャッシュ、記事のサイズ、サイトの可用性、障害の原因、その他の運用上の説明を推測しないでください。

520 などのステータスコードには Zyte 固有の意味があります。応答またはドキュメントで明示されていない限り、別の意味に読み替えないでください。

どちらのスクリプトも shub を使って Scrapy Cloud API キーを解決します。認証が利用可能かどうか確認する必要がある場合に限り、--check-key を使用してください。

uv run --no-project "${CLAUDE_SKILL_DIR}/scripts/zyte_api_stats.py" --check-key

キーが見つからない場合は、shub login を実行するか、scrape-zyte-login スキルを使うようユーザーに伝えてください。

Stats API のパラメーター

対応しているパラメーター、フィルター、グループ化オプション、レスポンスフィールドについては、公式ドキュメントを参照してください。

Reference セクションのみを使用し、ダッシュボードの設定に関する内容は無視してください。

フィルターとグループ化を使った例：

uv run --no-project "${CLAUDE_SKILL_DIR}/scripts/zyte_api_stats.py" \
	--params '{"organization_id": 3, "start_time": "2026-03-01T00:00:00Z", "end_time": "2026-03-31T23:59:59Z", "page": 1, "groupby_time": "day", "extraction_type": "article", "extraction_from": "browserHtml"}'

コメント

Markdown 対応