knowhow_base.md 6.32 KB

YouTube 数据抓取专家 - 领域知识库

一、YouTube Data API v3 核心能力

1.1 API 端点概览

端点 功能 配额成本 批量支持
videos.list 获取视频详情(标题、描述、统计、时长) 1 unit 最多 50 个 ID
channels.list 获取频道详情(订阅、统计、品牌) 1 unit 最多 50 个 ID
search.list 搜索视频、频道、播放列表 100 units 最多 50 结果
playlistItems.list 获取播放列表中的视频 1 unit 最多 50 结果
commentThreads.list 获取视频评论 1 unit 最多 100 结果
comments.list 获取评论回复 1 unit 最多 100 结果

1.2 核心数据字段

视频数据 (videos)

{
  id: "视频ID",
  snippet: {
    title: "标题",
    description: "描述",
    publishedAt: "发布时间",
    channelId: "频道ID",
    channelTitle: "频道名称",
    thumbnails: { default, medium, high, standard, maxres },
    tags: ["标签1", "标签2"],
    categoryId: "分类ID",
    defaultLanguage: "默认语言"
  },
  contentDetails: {
    duration: "PT15M33S", // ISO 8601 格式
    dimension: "2d",
    definition: "hd",
    caption: "true|false",
    licensedContent: true,
    regionRestriction: { allowed: [], blocked: [] }
  },
  statistics: {
    viewCount: "观看数",
    likeCount: "点赞数",
    commentCount: "评论数",
    favoriteCount: "收藏数"
  }
}

频道数据 (channels)

{
  id: "频道ID",
  snippet: {
    title: "频道名称",
    description: "频道描述",
    publishedAt: "创建时间",
    thumbnails: { ... },
    country: "国家",
    defaultLanguage: "默认语言"
  },
  statistics: {
    subscriberCount: "订阅数",
    viewCount: "总观看数",
    videoCount: "视频总数",
    hiddenSubscriberCount: false
  },
  brandingSettings: {
    channel: { keywords, unsubscribedTrailer, defaultTab },
    image: { bannerExternalUrl }
  },
  contentDetails: {
    relatedPlaylists: { uploads, likes, favorites, watchHistory, watchLater }
  }
}

二、优秀 YouTube 数据抓取技能的标准

2.1 功能完整性 (40分)

功能模块 必需 说明
视频详情获取 ✅ 支持批量获取,字段完整
频道详情获取 ✅ 支持批量获取,处理隐藏订阅数
搜索功能 ✅ 关键词、频道、时间范围筛选
播放列表获取 ✅ 获取频道上传列表
评论获取 ⭕ 可选,用于情感分析
数据导出 ✅ JSON/CSV 格式
分页处理 ✅ 自动处理 nextPageToken
配额追踪 ✅ 实时显示 API 配额使用

2.2 技术实现 (30分)

批量请求优化

  • 使用逗号分隔的 ID 列表批量获取(最多50个)
  • 优先使用 channels.list 和 videos.list 而非多次 search.list
  • 合理设置 part 参数,只获取需要的字段

错误处理 | 错误码 | 处理策略 | |--------|----------| | 400 | 参数错误,检查并重试 | | 403 | 配额耗尽或权限不足,停止并报告 | | 404 | 资源不存在,跳过并记录 | | 429 | 限速,指数退避重试 | | 500+ | 服务器错误,延迟重试 |

边界处理

  • videoCount = 0: 返回空数据,避免除零错误
  • hiddenSubscriberCount = true: 使用 viewCount/videoCount 估算
  • viewCount = 0: 标记为新视频
  • 超长描述/标题: 截断处理

2.3 数据质量 (20分)

字段完整性检查

  • 必需字段: id, title, publishedAt, channelId
  • 统计字段: viewCount, likeCount (可能为0或缺失)
  • 可选字段: description, tags, thumbnails

数据清洗

  • ISO 8601 时长转秒: PT15M33S → 933
  • 数字字符串转整数
  • 去除 HTML 标签
  • 统一编码 (UTF-8)

数据验证

  • URL 格式验证
  • 日期格式验证
  • 数值范围验证

2.4 性能与配额管理 (10分)

配额分配策略 (10,000 units/天)

场景 配额分配
小规模分析 ( search: 500, channels: 100, videos: 200, buffer: 200
中规模分析 (100-1000视频) search: 1000, channels: 200, videos: 500, buffer: 500
大规模分析 (>1000视频) 需要多天配额或申请增加配额

缓存策略

  • 频道信息缓存 (24小时)
  • 视频信息缓存 (变化频繁,建议短缓存)
  • 本地文件缓存避免重复请求

三、行业最佳实践

3.1 数据抓取流程

输入: 目标 (频道/视频/关键词)
│
▼ Step 1: 发现阶段
- 如果是关键词 → search.list 获取候选
- 如果是频道 → channels.list 获取详情
- 如果是视频列表 → 直接获取视频ID
│
▼ Step 2: 批量获取
- 分割 ID 列表 (每批 ≤50)
- 并发请求 (建议 3-5 并发)
- 处理错误和重试
│
▼ Step 3: 数据清洗
- 解析和转换字段
- 处理缺失值
- 计算衍生指标
│
▼ Step 4: 输出
- 结构化数据输出
- 生成统计摘要
- 导出文件

3.2 常见使用场景

场景 方法 关键参数
获取频道最新视频 playlistItems.list(uploads) playlistId={uploadsPlaylistId}
搜索某主题热门视频 search.list q={keyword}, order=viewCount, type=video
批量获取视频详情 videos.list id=id1,id2,id3...
获取频道对比数据 channels.list id=ch1,ch2,ch3...

3.3 数据导出格式

JSON 格式 (推荐)

{
  "metadata": {
    "exported_at": "2026-04-03T12:00:00Z",
    "api_version": "v3",
    "quota_used": 523,
    "total_items": 100
  },
  "data": [ ... ]
}

CSV 格式

  • 扁平化字段
  • 数组字段 JSON 编码或展开
  • 时间统一 ISO 8601

四、质量标准

一个优秀的 YouTube 数据抓取技能应满足:

  1. 准确性: API 调用正确,数据解析无误,边界处理完善
  2. 完整性: 覆盖视频、频道、搜索、列表等核心功能
  3. 效率性: 合理使用配额,支持批量请求,有缓存机制
  4. 可靠性: 完善的错误处理,自动重试,日志记录
  5. 易用性: 清晰的接口设计,完善的文档,输出协议规范

五、参考资源