SKILL.md 21.1 KB

SKILL: YouTube Trending Video Crawler

概述

YouTube 热门视频数据抓取专家技能。支持通过 YouTube Data API v3 获取当日最热门视频列表,包含多地区、多分类批量获取能力。

  • ID: youtube-crawler
  • 类型: data-collection
  • 版本: 1.0.0
  • 状态: training
  • 目标分数: 95/100

核心能力

  • 获取 YouTube 当日热门视频列表
  • 支持多地区批量获取 (US/JP/KR/CN/...)
  • 支持视频分类过滤 (Music/Gaming/Entertainment/...)
  • 数据导出为 JSON / CSV 格式
  • 智能配额管理与错误重试机制

技术实现

完整代码 (Python)

"""
YouTube Trending Video Crawler
使用 YouTube Data API v3 获取热门视频数据
"""

import os
import json
import csv
import time
import logging
from datetime import datetime
from typing import List, Dict, Optional, Union
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

# 配置日志
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger(__name__)


class YouTubeTrendingCrawler:
    """
    YouTube 热门视频爬虫

    使用 YouTube Data API v3 获取当日最热门视频列表
    """

    # API 端点
    API_BASE_URL = "https://www.googleapis.com/youtube/v3"

    # 视频分类映射
    VIDEO_CATEGORIES = {
        1: "Film & Animation",
        2: "Autos & Vehicles",
        10: "Music",
        17: "Sports",
        20: "Gaming",
        22: "People & Blogs",
        23: "Comedy",
        24: "Entertainment",
        25: "News & Politics",
        27: "Education",
        28: "Science & Technology",
    }

    # 常见地区代码
    REGION_CODES = ["US", "JP", "KR", "CN", "GB", "DE", "FR", "IN", "BR", "RU"]

    def __init__(self, api_key: Optional[str] = None):
        """
        初始化爬虫

        Args:
            api_key: YouTube Data API Key,默认从环境变量 YOUTUBE_API_KEY 读取
        """
        self.api_key = api_key or os.getenv("YOUTUBE_API_KEY")
        if not self.api_key:
            raise ValueError(
                "API Key 未提供。请传入 api_key 参数或设置 YOUTUBE_API_KEY 环境变量"
            )

        # 创建带重试机制的 session
        self.session = requests.Session()
        retry_strategy = Retry(
            total=3,
            backoff_factor=1,
            status_forcelist=[429, 500, 502, 503, 504],
        )
        adapter = HTTPAdapter(max_retries=retry_strategy)
        self.session.mount("https://", adapter)

        # 配额使用统计
        self.quota_used = 0

    def _make_request(self, endpoint: str, params: Dict) -> Dict:
        """
        发送 API 请求

        Args:
            endpoint: API 端点路径
            params: 请求参数

        Returns:
            API 响应数据

        Raises:
            requests.exceptions.HTTPError: HTTP 错误
            ValueError: API 返回错误
        """
        url = f"{self.API_BASE_URL}/{endpoint}"
        params["key"] = self.api_key

        try:
            response = self.session.get(url, params=params, timeout=30)

            # 处理特定错误码
            if response.status_code == 403:
                error_data = response.json()
                error_reason = error_data.get("error", {}).get("errors", [{}])[0].get("reason", "")
                if error_reason == "quotaExceeded":
                    raise ValueError("API 配额已耗尽,请明日再试或申请更高配额")
                elif error_reason in ["keyInvalid", "badRequest"]:
                    raise ValueError(f"API Key 无效: {error_reason}")
                else:
                    raise ValueError(f"访问被拒绝: {error_reason}")

            elif response.status_code == 429:
                # 配额限制或速率限制
                logger.warning("触发速率限制,等待后重试...")
                time.sleep(5)
                return self._make_request(endpoint, {k: v for k, v in params.items() if k != "key"})

            response.raise_for_status()

            # 统计配额使用 (mostPopular 请求消耗 1 unit)
            self.quota_used += 1

            return response.json()

        except requests.exceptions.Timeout:
            raise ValueError("请求超时,请检查网络连接")
        except requests.exceptions.ConnectionError:
            raise ValueError("网络连接错误,请检查网络设置")
        except requests.exceptions.RequestException as e:
            raise ValueError(f"请求失败: {str(e)}")

    def get_trending(
        self,
        region_code: str = "US",
        category_id: Optional[int] = None,
        max_results: int = 50,
        page_token: Optional[str] = None
    ) -> Dict:
        """
        获取指定地区的热门视频

        Args:
            region_code: ISO 3166-1 alpha-2 地区代码,如 US, JP, KR
            category_id: 视频分类 ID (可选)
            max_results: 返回结果数量 (1-50)
            page_token: 分页令牌 (可选)

        Returns:
            包含视频列表和分页信息的字典
        """
        if not 1 <= max_results <= 50:
            raise ValueError("max_results 必须在 1-50 之间")

        params = {
            "part": "snippet,statistics,contentDetails",
            "chart": "mostPopular",
            "regionCode": region_code,
            "maxResults": max_results,
        }

        if category_id:
            params["videoCategoryId"] = category_id
        if page_token:
            params["pageToken"] = page_token

        logger.info(f"获取 {region_code} 地区热门视频 (category={category_id or 'all'})")

        data = self._make_request("videos", params)

        videos = []
        for item in data.get("items", []):
            video_info = self.extract_video_info(item)
            if video_info:
                videos.append(video_info)

        result = {
            "region_code": region_code,
            "category_id": category_id,
            "videos": videos,
            "total_results": len(videos),
            "next_page_token": data.get("nextPageToken"),
            "quota_used": self.quota_used,
        }

        logger.info(f"成功获取 {len(videos)} 条视频数据")
        return result

    def extract_video_info(self, item: Dict) -> Optional[Dict]:
        """
        从 API 响应中提取视频信息

        Args:
            item: API 返回的单个视频数据

        Returns:
            标准化的视频信息字典
        """
        try:
            video_id = item.get("id")
            snippet = item.get("snippet", {})
            statistics = item.get("statistics", {})
            thumbnails = snippet.get("thumbnails", {})

            return {
                "videoId": video_id,
                "url": f"https://youtube.com/watch?v={video_id}",
                "title": snippet.get("title", ""),
                "description": snippet.get("description", ""),
                "channelTitle": snippet.get("channelTitle", ""),
                "channelId": snippet.get("channelId", ""),
                "publishedAt": snippet.get("publishedAt", ""),
                "categoryId": snippet.get("categoryId", ""),
                "categoryName": self.VIDEO_CATEGORIES.get(
                    int(snippet.get("categoryId", 0)), "Unknown"
                ),
                "viewCount": int(statistics.get("viewCount", 0)),
                "likeCount": int(statistics.get("likeCount", 0)) if statistics.get("likeCount") else 0,
                "commentCount": int(statistics.get("commentCount", 0)) if statistics.get("commentCount") else 0,
                "duration": item.get("contentDetails", {}).get("duration", ""),
                "thumbnails": {
                    "default": thumbnails.get("default", {}).get("url", ""),
                    "medium": thumbnails.get("medium", {}).get("url", ""),
                    "high": thumbnails.get("high", {}).get("url", ""),
                    "standard": thumbnails.get("standard", {}).get("url", ""),
                    "maxres": thumbnails.get("maxres", {}).get("url", ""),
                },
                "tags": snippet.get("tags", []),
                "liveBroadcastContent": snippet.get("liveBroadcastContent", "none"),
            }
        except Exception as e:
            logger.warning(f"解析视频数据失败: {str(e)}")
            return None

    def get_multi_region_trending(
        self,
        regions: List[str],
        category_id: Optional[int] = None,
        max_results: int = 50
    ) -> Dict[str, Dict]:
        """
        批量获取多个地区的热门视频

        高效使用配额:每个地区仅消耗 1 unit

        Args:
            regions: 地区代码列表,如 ["US", "JP", "KR"]
            category_id: 视频分类 ID (可选)
            max_results: 每个地区返回结果数量

        Returns:
            以地区代码为键的结果字典
        """
        results = {}

        logger.info(f"开始批量获取 {len(regions)} 个地区的热门视频")

        for region in regions:
            try:
                result = self.get_trending(
                    region_code=region,
                    category_id=category_id,
                    max_results=max_results
                )
                results[region] = result

                # 请求间隔,避免触发速率限制
                time.sleep(0.5)

            except Exception as e:
                logger.error(f"获取 {region} 地区数据失败: {str(e)}")
                results[region] = {"error": str(e), "videos": []}

        logger.info(f"批量获取完成,总配额使用: {self.quota_used} units")
        return results

    def get_all_categories_trending(
        self,
        region_code: str = "US",
        max_results: int = 50
    ) -> Dict[int, Dict]:
        """
        获取指定地区所有分类的热门视频

        Args:
            region_code: 地区代码
            max_results: 每个分类返回结果数量

        Returns:
            以分类 ID 为键的结果字典
        """
        results = {}

        for category_id in self.VIDEO_CATEGORIES.keys():
            try:
                result = self.get_trending(
                    region_code=region_code,
                    category_id=category_id,
                    max_results=max_results
                )
                results[category_id] = result
                time.sleep(0.5)
            except Exception as e:
                logger.error(f"获取分类 {category_id} 数据失败: {str(e)}")
                results[category_id] = {"error": str(e), "videos": []}

        return results

    def save_to_json(
        self,
        data: Union[Dict, List],
        filepath: Optional[str] = None,
        region: Optional[str] = None
    ) -> str:
        """
        保存数据为 JSON 文件

        Args:
            data: 要保存的数据
            filepath: 文件路径 (可选,默认自动生成)
            region: 地区代码 (用于生成文件名)

        Returns:
            保存的文件路径
        """
        if filepath is None:
            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
            region_suffix = f"_{region}" if region else ""
            filepath = f"youtube_trending{region_suffix}_{timestamp}.json"

        # 确保目录存在
        os.makedirs(os.path.dirname(filepath) if os.path.dirname(filepath) else ".", exist_ok=True)

        with open(filepath, "w", encoding="utf-8") as f:
            json.dump(data, f, ensure_ascii=False, indent=2)

        logger.info(f"数据已保存到: {filepath}")
        return filepath

    def save_to_csv(
        self,
        videos: List[Dict],
        filepath: Optional[str] = None,
        region: Optional[str] = None
    ) -> str:
        """
        保存视频列表为 CSV 文件

        Args:
            videos: 视频数据列表
            filepath: 文件路径 (可选)
            region: 地区代码 (用于生成文件名)

        Returns:
            保存的文件路径
        """
        if filepath is None:
            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
            region_suffix = f"_{region}" if region else ""
            filepath = f"youtube_trending{region_suffix}_{timestamp}.csv"

        # 确保目录存在
        os.makedirs(os.path.dirname(filepath) if os.path.dirname(filepath) else ".", exist_ok=True)

        if not videos:
            logger.warning("没有数据可保存")
            return filepath

        # 定义 CSV 字段
        fieldnames = [
            "videoId", "url", "title", "channelTitle", "channelId",
            "viewCount", "likeCount", "commentCount", "publishedAt",
            "categoryId", "categoryName", "duration", "thumbnail_high"
        ]

        with open(filepath, "w", newline="", encoding="utf-8") as f:
            writer = csv.DictWriter(f, fieldnames=fieldnames)
            writer.writeheader()

            for video in videos:
                row = {
                    "videoId": video.get("videoId", ""),
                    "url": video.get("url", ""),
                    "title": video.get("title", ""),
                    "channelTitle": video.get("channelTitle", ""),
                    "channelId": video.get("channelId", ""),
                    "viewCount": video.get("viewCount", 0),
                    "likeCount": video.get("likeCount", 0),
                    "commentCount": video.get("commentCount", 0),
                    "publishedAt": video.get("publishedAt", ""),
                    "categoryId": video.get("categoryId", ""),
                    "categoryName": video.get("categoryName", ""),
                    "duration": video.get("duration", ""),
                    "thumbnail_high": video.get("thumbnails", {}).get("high", ""),
                }
                writer.writerow(row)

        logger.info(f"CSV 数据已保存到: {filepath}")
        return filepath

    def get_quota_status(self) -> Dict:
        """
        获取配额使用状态

        Returns:
            配额使用信息
        """
        return {
            "quota_used": self.quota_used,
            "quota_limit": 10000,
            "quota_remaining": 10000 - self.quota_used,
            "usage_percentage": (self.quota_used / 10000) * 100,
        }


# ==================== 使用示例 ====================

def main():
    """使用示例"""

    # 初始化爬虫
    crawler = YouTubeTrendingCrawler()

    # 示例 1: 获取美国热门视频
    print("=== 获取美国热门视频 ===")
    us_trending = crawler.get_trending(region_code="US", max_results=10)
    print(f"获取到 {us_trending['total_results']} 条视频")
    print(f"配额使用: {us_trending['quota_used']} units")

    # 示例 2: 获取日本音乐类热门视频
    print("\n=== 获取日本音乐类热门视频 ===")
    jp_music = crawler.get_trending(region_code="JP", category_id=10, max_results=5)
    print(f"获取到 {jp_music['total_results']} 条音乐视频")

    # 示例 3: 多地区批量获取
    print("\n=== 批量获取多地区热门视频 ===")
    multi_region = crawler.get_multi_region_trending(
        regions=["US", "JP", "KR"],
        max_results=5
    )
    for region, data in multi_region.items():
        if "error" not in data:
            print(f"{region}: {data['total_results']} 条视频")

    # 示例 4: 保存数据
    print("\n=== 保存数据 ===")
    crawler.save_to_json(us_trending, region="US")
    crawler.save_to_csv(us_trending["videos"], region="US")

    # 示例 5: 查看配额状态
    print("\n=== 配额状态 ===")
    quota = crawler.get_quota_status()
    print(f"已使用: {quota['quota_used']}/{quota['quota_limit']} ({quota['usage_percentage']:.2f}%)")


if __name__ == "__main__":
    main()

API 使用规范

环境变量配置

export YOUTUBE_API_KEY="your_api_key_here"

获取 API Key

  1. 访问 Google Cloud Console
  2. 创建新项目或选择现有项目
  3. 启用 YouTube Data API v3
  4. 创建凭据 → API 密钥
  5. 限制密钥使用范围(推荐)

关键参数说明

参数 类型 必填 说明
part string 是 snippet,statistics,contentDetails
chart string 是 固定值 mostPopular
regionCode string 否 ISO 3166-1 alpha-2 代码,如 US, JP, KR
videoCategoryId string 否 视频分类 ID
maxResults integer 否 1-50,默认 5
pageToken string 否 分页令牌

配额管理

请求类型 消耗配额
videos.list (mostPopular) 1 unit
每日配额上限 10,000 units

配额优化策略:

  • 使用 get_multi_region_trending() 批量获取多个地区数据
  • 合理设置 max_results (默认 50)
  • 添加缓存机制,避免频繁请求

视频分类 ID 映射

ID 分类名称
10 Music
20 Gaming
24 Entertainment
28 Science & Technology
1 Film & Animation
17 Sports
22 People & Blogs
23 Comedy
25 News & Politics
27 Education

错误处理

错误码说明

HTTP 状态码 含义 处理方式
200 成功 正常处理数据
400 请求参数错误 检查 regionCode 是否有效
403 权限错误 检查 API Key 是否有效或配额是否耗尽
429 速率限制 指数退避重试
500+ 服务器错误 稍后重试

异常类型

# 无效 API Key
ValueError: API Key 无效: keyInvalid

# 配额耗尽
ValueError: API 配额已耗尽,请明日再试或申请更高配额

# 网络超时
ValueError: 请求超时,请检查网络连接

输出数据格式

JSON 格式

{
  "region_code": "US",
  "category_id": null,
  "videos": [
    {
      "videoId": "dQw4w9WgXcQ",
      "url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
      "title": "Video Title",
      "description": "Video description...",
      "channelTitle": "Channel Name",
      "channelId": "UC...",
      "publishedAt": "2024-01-15T10:00:00Z",
      "categoryId": "10",
      "categoryName": "Music",
      "viewCount": 1500000,
      "likeCount": 50000,
      "commentCount": 2000,
      "duration": "PT3M45S",
      "thumbnails": {
        "default": "https://i.ytimg.com/vi/.../default.jpg",
        "medium": "https://i.ytimg.com/vi/.../mqdefault.jpg",
        "high": "https://i.ytimg.com/vi/.../hqdefault.jpg"
      },
      "tags": ["tag1", "tag2"],
      "liveBroadcastContent": "none"
    }
  ],
  "total_results": 50,
  "next_page_token": "CA8QAA",
  "quota_used": 5
}

CSV 格式

videoId,url,title,channelTitle,channelId,viewCount,likeCount,commentCount,publishedAt,categoryId,categoryName,duration,thumbnail_high
dQw4w9WgXcQ,https://youtube.com/watch?v=dQw4w9WgXcQ,Video Title,Channel Name,UC...,1500000,50000,2000,2024-01-15T10:00:00Z,10,Music,PT3M45S,https://i.ytimg.com/vi/.../hqdefault.jpg

输入参数

参数 类型 必填 默认值 说明
region_code string 否 "US" 地区代码 (ISO 3166-1 alpha-2)
category_id integer 否 null 视频分类 ID
max_results integer 否 50 返回数量 (1-50)
page_token string 否 null 分页令牌

输出字段

字段 类型 说明
videoId string YouTube 视频 ID
url string 完整视频链接
title string 视频标题
channelTitle string 频道名称
viewCount integer 播放次数
thumbnails object 各尺寸封面 URL
publishedAt string 发布时间 (ISO 8601)
categoryId string 视频分类 ID
categoryName string 分类名称

高级用法

分页获取

crawler = YouTubeTrendingCrawler()

# 第一页
result = crawler.get_trending(region_code="US", max_results=50)
next_token = result.get("next_page_token")

# 第二页
if next_token:
    result_page2 = crawler.get_trending(
        region_code="US",
        max_results=50,
        page_token=next_token
    )

全部分类获取

# 获取某地区所有分类的热门视频
all_categories = crawler.get_all_categories_trending(region_code="US")

for category_id, data in all_categories.items():
    print(f"分类 {category_id}: {data['total_results']} 条视频")

自定义请求参数

# 只获取 snippet 部分(节省配额,但字段较少)
result = crawler._make_request("videos", {
    "part": "snippet",
    "chart": "mostPopular",
    "regionCode": "US",
    "maxResults": 10
})

依赖安装

pip install requests urllib3

最佳实践

  1. API Key 安全: 始终通过环境变量读取,不要硬编码
  2. 错误处理: 生产环境务必添加 try-except 包裹调用
  3. 配额监控: 定期检查配额使用情况,避免服务中断
  4. 请求间隔: 批量获取时添加适当延迟 (0.5-1 秒)
  5. 数据缓存: Trending 数据 15-30 分钟内变化不大,建议缓存

版本历史

版本 分数 日期 主要改进
v1.0 TBD 2026-04-01 初始版本,Python 完整实现