mcpField
S
scrape-zyte-api-stats

scrape-zyte-api-stats

github.com/zytedata数据与数据库11145 次安装2 天前更新
代码仓库

关于 scrape-zyte-api-stats

Claude skill 通过随附脚本查询历史 Zyte API 使用统计，并从项目配置解析组织信息，返回 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 响应；由 Agent 负责向用户展示这些数据。

此技能用于查询已发生的历史使用情况，不用于预测、推断、仪表板设置、文档或配置帮助。

始终先运行项目查找辅助程序来解析 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

封装脚本

使用 uv 运行封装脚本，并将查询参数作为 JSON 对象传入：

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

使用技能运行时提供的 ${CLAUDE_SKILL_DIR}。不要在同一条命令前加上内联的 CLAUDE_SKILL_DIR=... 赋值，因为脚本路径可能会在该临时赋值生效前展开。

直接根据 Stats API 文档构建 --params。封装脚本不会替你转换或验证参数名称。

封装脚本会输出原始的 Stats API JSON 对象。请读取该对象，并自行整理结果供用户查看。面向用户的陈述必须以返回的 JSON 为依据。不要假设存在 API 未返回的字段。

当用户指定了明确的相对时间范围，例如 last 7 days、last 30 days 或 this month，请计算一组具体的 UTC start_time / end_time，并将其值传入 --params。保持工作流简单：必要时优先用一个简洁的计算步骤，避免反复进行探索性 shell 重试。

当用户询问 recent 用量但未指定时间范围时，完全省略 start_time 和 end_time，以使用 API 的默认范围。

如果 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