scrape-scrapy-cloud

Name: scrape-scrapy-cloud
Author: zytedata

github.com/zytedataクラウド・DevOps11153 回インストール2 日前に更新

リポジトリ

scrape-scrapy-cloud について

`shub` と Cloud API で Scrapy Cloud プロジェクトを操作する Claude スキルです。デプロイ、スパイダーの実行予約、ジョブ監視、結果確認を支援し、設定の探索と API キーの保護にも配慮します。

主な機能

01`uvx shub` による Scrapy プロジェクトのデプロイ
02引数や設定を指定したスパイダーの予約
03ジョブの完了待ちと状態確認
04ログ、フィールド網羅率、サンプル項目の確認
05キーを表示せずにプロジェクト設定を探索

活用シーン

01Scrapy プロジェクトの Scrapy Cloud へのデプロイ
02独自の引数を付けたスパイダーの予約
03完了ジョブのログと抽出項目の確認

インストール

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

$npx skills add https://github.com/zytedata/skills --skill scrape-scrapy-cloud

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

同梱ファイル

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

scripts/

auth.py

scrapy_cloud_api.py

wait_for_job.py

詳細

汎用の Scrapy Cloud アシスタントです。プロジェクトのデプロイ、スパイダーのスケジュール設定、ジョブの管理（一覧表示、停止）ができ、アイテムやログを確認するための Web UI へユーザーを案内できます。すべて shub と Scrapy Cloud HTTP API を使用します。

${CLAUDE_SKILL_DIR}/../scrape/references の python-environments.md と docs-access.md を読みます。

ルール

プロジェクト ID、エンドポイント、認証情報、デプロイ先をユーザーに早まって尋ねないでください。 これらは以下の手順に従って確認します（scrapinghub.yml、~/.scrapinghub.yml、環境変数を確認します）。
手順を順番に実行してください — 手順に明示されている場合にのみユーザーに尋ねます。
ユーザーが開いているファイルまたは現在のディレクトリに scrapinghub.yml がある場合は、それを使ってデプロイするプロジェクトを特定します。

入力

生の引数文字列は $ARGUMENTS です — そのまま使用し、空の場合は「引数が指定されていない」として扱います。

project_dir：Scrapy プロジェクトディレクトリのパス（引数文字列が空の場合は現在のディレクトリをデフォルトとします）

手順

重要：セッション中、API キーがエージェントやユーザーに表示または露出しないようにすることが重要です。認証の確認に、キーまたはその値を出力する可能性のあるツール（例：cat ~/.scrapinghub.yml）を使用しないでください。

1. プロジェクトのルートを見つける

project_dir（指定されていない場合は現在のディレクトリ）に移動します。scrapy.cfg が存在することを確認します。

ls scrapy.cfg

現在のディレクトリに scrapy.cfg がない場合は、ディレクトリツリーを上にたどって見つけます。見つかったら、そのディレクトリに cd します — 以降のすべてのコマンドはそこから実行する必要があります。

2. 既存の scrapinghub.yml を確認する

ls scrapinghub.yml 2>/dev/null || echo "(not found)"

ファイルが存在する場合は手順 3 をスキップし、手順 4 に進みます。

3. scrapinghub.yml を作成する

プロジェクト ID を取得する

以前の scrape-zyte-login で保存されたプロジェクト ID があるか確認します。

cat .scrape/.zyte/project-id 2>/dev/null || echo "(not set)"

存在する場合はそれを使用し、質問はスキップします。

存在しない場合は、Zyte のプロジェクトページを開きます。

xdg-open "https://app.zyte.com/o/projects/" 2>/dev/null || open "https://app.zyte.com/o/projects/"

ユーザーに尋ねます：

Please open https://app.zyte.com/o/projects/ and provide the numeric project ID
for this spider (e.g. 12345). If you don't have a project yet, create one first.

ユーザーから数値のプロジェクト ID が提供されるまで待ちます。

requirements を準備する

requirements.txt がすでに存在する場合は、そのまま使用します。

存在しない場合は、依存関係の仕様ファイル（Python の依存関係を宣言する標準的なファイル）を探します。見つかった場合は、自動的な方法でそこから固定バージョンの requirements.txt（すべてのパッケージを == で固定）を生成します。見つからない場合は、プロジェクトのソースからサードパーティーパッケージを特定し、それらを固定バージョンではない依存関係ファイルに書き出してから、自動的な方法でそのファイルから固定バージョンの requirements.txt を生成します。

どの場合でも、scrapinghub.yml は requirements.txt を参照します。

requirements.txt が事前に存在しなかった場合は、生成に使用した正確なコマンドと、依存関係が変更された場合やアップグレードする場合に実行するコマンドをユーザーに伝えます。

Scrapy スタックを指定する

Docker Hub API を使用するかタグページをスクレイピングして、requirements ファイル内の Scrapy バージョンに一致する scrapinghub/scrapinghub-stack-scrapy リポジトリの最新のスタックタグを確認します。

API エンドポイント：https://hub.docker.com/v2/repositories/scrapinghub/scrapinghub-stack-scrapy/tags
Web ページ：https://hub.docker.com/r/scrapinghub/scrapinghub-stack-scrapy/tags

タグの形式は {VERSION}-{YYYYMMDD} です（例：2.14-20260326）。最もバージョン番号が高いタグを選び、バージョンが同じ場合は日付が最も新しいものを選びます。そのタグの前に scrapy: を付けて、scrapinghub.yml の stack の値として使用します（例：scrapy:2.14-20260326）。 requirements ファイルで Scrapy のバージョンが指定されていない場合、または指定されたバージョンに一致するスタックタグがない場合は、全体で最新のタグを使用します。

scrapinghub.yml を書き込む

ファイルを作成します。SCRAPY_CLOUD_ENDPOINT が設定されている場合は、endpoint: キーを追加します。

project: 12345

stack: scrapy:2.14-20260326  # replace with the latest tag fetched above

requirements:
  file: requirements.txt

endpoint: https://app-staging.zyte.com/api/  # include when SCRAPY_CLOUD_ENDPOINT is set

4. デプロイ

プロジェクトのルートから uvx でデプロイを実行します。uvx は必要に応じて shub を取得するため、別途インストールする必要はなく、shub が PATH にあるかどうかにかかわらず動作します。

uvx shub deploy

出力全体をストリーミングして表示します。デプロイが成功すると、次のように表示されます。

Packing version 3af023e-master
Deploying to Scrapy Cloud project "12345"
{"status": "ok", "project": 12345, "version": "3af023e-master", "spiders": 2}
Run your spiders at: https://app.zyte.com/p/12345/

失敗した場合は、エラーを診断し、修正してから再試行します。

Error: Not logged in. Please run 'shub login' first. → 認証されていません。/scrape-zyte-login を呼び出します。
Error: Invalid value for target: Please specify target or configure a default target in scrapinghub.yml. → プロジェクト ID が設定されていません。ユーザーにプロジェクト ID を尋ね、scrapinghub.yml を更新して再試行します。
Authentication error / 403 → API キーが誤っているか、設定されていません。/scrape-zyte-login を呼び出します。
Project N does not exist → プロジェクト ID が誤っています。scrapinghub.yml を修正して再試行します。
Could not find requirements file → scrapinghub.yml の requirements.file のパスが誤っています。パスを修正して再試行します。
No module named scrapy またはビルドエラー → 依存関係が不足しているか、選択したスタックと互換性がありません。requirements ファイルを更新して再試行します。
その他のエラー → エラーメッセージ全体をユーザーに示し、どのように進めるか尋ねます。

5. 成功を報告する

デプロイが成功したことをユーザーに伝え、バージョン、スパイダー数、プロジェクトのリンク（https://app.zyte.com/p//）を記載します。

スタックの Scrapy バージョンが requirements.txt のバージョンより古い場合は、テストジョブの実行を強く推奨し、問題が発生した場合は、スタックとの互換性が根本原因の可能性として考えられるものの、原因と決めつけないことを伝えます。

ジョブのスケジュール

uvx shub schedule を使うと、再デプロイせずに Scrapy Cloud でスパイダーを実行するジョブを開始できます。

ジョブには skill タグを付けます。

基本的なスケジュール設定

uvx shub schedule SPIDER --tag skill

成功すると、shub はジョブ ID と便利なリンクを出力します。

Spider myspider scheduled, job ID: 12345/2/15
Watch the log on the command line:
    shub log -f 2/15
or watch it running in Zyte's web interface:
    https://app.zyte.com/p/12345/job/2/15

スパイダーの引数を指定する場合（`-a`）

引数ごとに -a KEY=VALUE を繰り返します。

uvx shub schedule myspider -a ARG1=VALUE1 -a ARG2=VALUE2 --tag skill

ジョブ固有の Scrapy 設定を指定する場合（`-s`）

uvx shub schedule myspider -s LOG_LEVEL=DEBUG -s CLOSESPIDER_PAGECOUNT=10 --tag skill

特定のプロジェクトを指定する場合

uvx shub schedule 33333/myspider --tag skill

ユニット数と優先度を指定する場合

フラグ	説明
`-u`	使用する Scrapy Cloud ユニット数（1～6）
`-p`	ジョブの優先度：0（最低）～4（最高）

uvx shub schedule myspider -p 3 -u 3 --tag skill

組み合わせ例

uvx shub schedule myspider \
  -a start_url=https://example.com \
  -s LOG_LEVEL=DEBUG \
  -p 2 \
  -u 1 \
  --tag skill

ジョブの完了を待つ

ジョブをスケジュールしたら、結果を検証できるよう、終端状態になるまで待ちます（次のセクションを参照）。同梱のヘルパーを使います。Jobs API をバックオフしながらポーリングするため、手動でポーリングする必要はありません。

uv run ${CLAUDE_SKILL_DIR}/scripts/wait_for_job.py PROJECT/SPIDER/JOB

省略可能なフラグ：--poll-interval SECONDS（初期間隔。デフォルトは 10 で、最大 60 までバックオフします）および --max-wait SECONDS（この時間を過ぎると待機を終了します。デフォルトは 1200）。

ジョブが終端状態に達するか、--max-wait に達するまで処理をブロックし、その後、標準出力に機械可読な行を 1 行だけ出力します。

JOB_FINISHED {...job json...} — ジョブが終端状態に達しました（終了コード 0）。JSON の state、close_reason、errors_count、items_scraped などを解析し、検証に進みます。
JOB_TIMEOUT {...last known job json...} — ジョブがまだ実行中の状態で --max-wait の時間が経過しました（終了コード 1）。ジョブがまだ実行中であることをユーザーに伝え、待機を続ける（より大きな --max-wait を指定して再実行する）か、後で確認するかを提案します。

進捗行は標準エラー出力に送られるため、無視できます。

ジョブの結果を検証する

ジョブの実行後は、デフォルトでこれを行います。結果が適切に見えるまでは、デプロイやスケジュール設定は「完了」ではありません。ユーザーが明示的に不要とした場合に限り省略します（「スケジュールするだけでいい」「完了を待たなくていい」「結果を確認する必要はない」など）。その場合は、ジョブのリンクを報告して終了します。

完了したジョブに対して、以下の確認を行います。

1. エラーと終了理由

JOB_FINISHED のサマリーでは、close_reason は "finished" である必要があります。それ以外の failed、cancelled、または予期しない closespider_* の理由は、調査すべき兆候です。errors_count は証拠ではなく指標として扱ってください。ログレベルによってエラーが抑制されている場合、カウントが 0 でも正常に完了したとは限りません（手順 3 を参照）。

2. ログをローカルで調査する

ログ全体を一度ダウンロードし、ローカルで grep／jq を使って調査してください。HTTP API を1行ずつページネーションするより、はるかに高速です。ログはデフォルトで JSON Lines 形式で返されます。

uv run ${CLAUDE_SKILL_DIR}/scripts/scrapy_cloud_api.py GET \
  "${SCRAPY_CLOUD_STORAGE_ENDPOINT:-https://storage.zyte.com/}logs/PROJECT/SPIDER/JOB" > job.log.jl
# ERROR (40) and CRITICAL (50) entries:
jq -c 'select(.level >= 40)' job.log.jl

各エントリーは {"time": <unix-ms>, "level": <int>, "message": <str>} の形式です。ログレベルについては、「項目とログの表示」の下にある表を参照してください。ページネーションや形式のオプションについては、そこにリンクされているログ API のドキュメントを参照してください。

プロジェクトで Zyte API（scrapy-zyte-api 経由）を使用している場合、終了時に出力される Scrapy の統計情報には scrapy-zyte-api/* カウンター（成功／エラー比率、429、error_types/*、BAN）が含まれます。これらは終了理由が不適切である理由やカバレッジが低い理由の説明になることが多い一方、誤読しやすい情報でもあります。各カウンターの意味については、https://scrapy-zyte-api.readthedocs.io/en/latest/reference/stats.md を参照してください。

3. ログレベル

ログに DEBUG メッセージがない場合、LOG_LEVEL は DEBUG より上に設定されています。利用可能なログから原因を特定できない問題がジョブで発生した場合は、LOG_LEVEL=DEBUG にして再実行してください。

LOG_LEVEL はコード内、または Scrapy Cloud のプロジェクト／スパイダー設定で指定できます。コード内で設定しても効果がない場合は、クラウド設定で上書きされています。設定を読み取ったり変更したりする公開 API はないため、ユーザーに手動で修正してもらってください。

4. フィールドのカバレッジ

項目をすべてダウンロードせずにフィールドごとの入力件数を取得するには、項目統計エンドポイント（下記の「項目統計」を参照）を使用してください。counts[field] を totals.input_values（項目の総数）と比較します。想定されるフィールドを確認します。

このジョブが /scrape ワークフローの一部である場合、想定されるフィールドは .scrape/{site}/{data-type}/spec.json にあります（${CLAUDE_SKILL_DIR}/../scrape/references/extraction-spec.md を参照）。
それ以外の場合は、デプロイ済みプロジェクトの項目クラス／ページオブジェクトクラスを確認してください。

想定されるフィールドのカバレッジが 0％の場合は、問題として報告してください。

カバレッジが 0％から 100％のフィールドについては、そのフィールドが欠けている項目をいくつかダウンロードし（下記の「項目のダウンロード」を参照）、正当に欠けているのか、抽出のバグなのかを判断してください。

5. 項目がリクエストに合致するかを抜き取り確認する

少量のサンプルをダウンロードして内容を確認してください（下記の「項目のダウンロード」を参照）。

uv run ${CLAUDE_SKILL_DIR}/scripts/scrapy_cloud_api.py GET \
  "${SCRAPY_CLOUD_STORAGE_ENDPOINT:-https://storage.zyte.com/}items/PROJECT/SPIDER/JOB" -q count=5

サンプル項目が、ユーザーの実際の依頼（適切なカテゴリ、フィルター、商品タイプ）に合致しているかを判断してください。判断には、仕様のスキーマ／例と開始 URL、または会話内容を参照します。これは判断を要する作業であり、スクリプトで判定するものではありません。

6. 報告

ジョブへのリンク、close_reason、エラー数、フィールドカバレッジの簡潔な表、サンプル確認の判定をまとめます。

問題が見つかった場合

いずれかのチェックで問題が見つかった場合（エラー、低いカバレッジ、カテゴリ違いの項目）、考えられる原因を特定し、プロジェクトのコードを修正して、再デプロイ（uvx shub deploy）し、再スケジュールしてから再検証してください。これを合計 3 回までに制限します（scrape-create-spider のローカル検証ループに合わせます）。3 回試しても問題が解消しない場合は、それ以上繰り返さず、残っている問題を報告してください。

ジョブの管理

ジョブの一覧表示と停止には、Scrapy Cloud Jobs HTTP API を使用します。

ベース URL：${SCRAPY_CLOUD_ENDPOINT:-https://app.zyte.com/api/}

ラッパースクリプト

重要 API リクエストは、認証情報をエージェントに漏らさず処理する scripts/scrapy_cloud_api.py のラッパースクリプトを使って行うことが重要です。認証情報が漏れる可能性のある curl やその他のツールで API リクエストを行わないでください。

uv run ${CLAUDE_SKILL_DIR}/scripts/scrapy_cloud_api.py HTTP_METHOD API_URL [-q QUERY_ARG=VALUE]... [-b BODY_ARG=VALUE]...

エンドポイントに応じて、必要に応じて任意のクエリパラメーター（-q）と本文パラメーター（-b）を指定します。詳細はスクリプトのヘルプメッセージを参照してください。

出力形式：スクリプトは最初の行に HTTP ステータスコードを出力し、残りの行にレスポンス本文を出力します。ステータス行を使ってエラー（例：401／403 の認証エラー）を検出してください。本文だけが必要な場合は、最初の行を無視します。以下に示すレスポンス本文では、先頭のステータス行を省略しています。

ジョブの一覧表示

# All running jobs
uv run ${CLAUDE_SKILL_DIR}/scripts/scrapy_cloud_api.py GET "${SCRAPY_CLOUD_ENDPOINT:-https://app.zyte.com/api/}jobs/list.json" -q project=PROJECT_ID -q state=running

# Latest 3 finished jobs for a specific spider
uv run ${CLAUDE_SKILL_DIR}/scripts/scrapy_cloud_api.py GET "${SCRAPY_CLOUD_ENDPOINT:-https://app.zyte.com/api/}jobs/list.json" -q project=PROJECT_ID -q spider=SPIDER_NAME -q state=finished -q count=3

# Jobs that lack the "consumed" tag
uv run ${CLAUDE_SKILL_DIR}/scripts/scrapy_cloud_api.py GET "${SCRAPY_CLOUD_ENDPOINT:-https://app.zyte.com/api/}jobs/list.json" -q project=PROJECT_ID -q lacks_tag=consumed

使用可能な state の値：pending、running、finished、deleted。使用可能なフィルターパラメーター：job、spider、state、has_tag、lacks_tag、count。

ジョブの停止

uv run ${CLAUDE_SKILL_DIR}/scripts/scrapy_cloud_api.py POST "${SCRAPY_CLOUD_ENDPOINT:-https://app.zyte.com/api/}jobs/stop.json" -b project=PROJECT_ID -b job=PROJECT_ID/SPIDER_ID/JOB_ID

アイテムとログの表示

アイテムとログを確認するには、Scrapy Cloud のウェブ UI をユーザーに案内します。

SCRAPY_CLOUD_ENDPOINT から末尾の /api/ パスを取り除いて、ウェブ UI のベース URL を導き出します（デフォルト：https://app.zyte.com）。

アイテムページ

${SCRAPY_CLOUD_ENDPOINT%api/}p/PROJECT_ID/SPIDER_ID/JOB_ID/items

次の URL を開きます：

BASE_UI="${SCRAPY_CLOUD_ENDPOINT%api/}"
xdg-open "${BASE_UI:-https://app.zyte.com/}p/PROJECT_ID/SPIDER_ID/JOB_ID/items" 2>/dev/null \
  || open "${BASE_UI:-https://app.zyte.com/}p/PROJECT_ID/SPIDER_ID/JOB_ID/items"

アイテム統計（HTTP API）

すべてのアイテムをダウンロードせずにアイテム数とフィールドのカバレッジをすばやく把握するには、統計エンドポイントを直接使用します：

uv run ${CLAUDE_SKILL_DIR}/scripts/scrapy_cloud_api.py GET "${SCRAPY_CLOUD_ENDPOINT:-https://app.zyte.com/api/}items/PROJECT_ID/SPIDER_ID/JOB_ID/stats"
# Response: {"counts":{"field1":9350,"field2":514},"totals":{"input_bytes":14390294,"input_values":10000}}

レスポンスのフィールド：

フィールド	説明
`counts[field]`	各フィールドに値が設定された回数。
`totals.input_bytes`	すべてのアイテムの合計サイズ（バイト単位）。
`totals.input_values`	アイテムの合計数。

アイテムのダウンロード（HTTP API）

アイテム自体を読み取るには、ラッパースクリプトを通じてストレージ API から取得します（curl は使用しないでください。ラッパーを使えば認証情報が軌跡に含まれません）。デフォルトのレスポンス形式は JSON Lines で、1 行につき 1 アイテムです：

# All items
uv run ${CLAUDE_SKILL_DIR}/scripts/scrapy_cloud_api.py GET "${SCRAPY_CLOUD_STORAGE_ENDPOINT:-https://storage.zyte.com/}items/PROJECT_ID/SPIDER_ID/JOB_ID"

# A bounded sample (recommended for spot-checks)
uv run ${CLAUDE_SKILL_DIR}/scripts/scrapy_cloud_api.py GET "${SCRAPY_CLOUD_STORAGE_ENDPOINT:-https://storage.zyte.com/}items/PROJECT_ID/SPIDER_ID/JOB_ID" -q count=5

# Specific items by index (repeat -q index=N for each)
uv run ${CLAUDE_SKILL_DIR}/scripts/scrapy_cloud_api.py GET "${SCRAPY_CLOUD_STORAGE_ENDPOINT:-https://storage.zyte.com/}items/PROJECT_ID/SPIDER_ID/JOB_ID" -q index=0 -q index=1

ファイルにリダイレクトして、ざっと確認するだけでなければ jq／grep を使ってローカルで調べます。ページネーション（start、startafter）、フィールドのフィルタリング、gzip、その他の形式（-q format=json）については、以下にリンクされているアイテム API ドキュメントを参照してください。

ログページ

${SCRAPY_CLOUD_ENDPOINT%api/}p/PROJECT_ID/SPIDER_ID/JOB_ID/log