youtube_crawler.py 13.3 KB
"""
YouTube Trending Video Crawler
使用 YouTube Data API v3 获取热门视频数据

Usage:
    from youtube_crawler import YouTubeTrendingCrawler

    crawler = YouTubeTrendingCrawler()
    result = crawler.get_trending(region_code="US", max_results=10)

Requires:
    pip install requests urllib3
    export YOUTUBE_API_KEY="your_api_key_here"
"""

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 获取当日最热门视频列表

    Attributes:
        api_key: YouTube Data API Key
        quota_used: 已使用的 API 配额
        session: 带重试机制的 HTTP session
    """

    # 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 读取

        Raises:
            ValueError: 当 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 响应数据 (JSON)

        Raises:
            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)
                params_copy = {k: v for k, v in params.items() if k != "key"}
                return self._make_request(endpoint, params_copy)

            response.raise_for_status()

            # 统计配额使用
            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:
            包含视频列表和分页信息的字典:
            {
                "region_code": str,
                "category_id": Optional[int],
                "videos": List[Dict],
                "total_results": int,
                "next_page_token": Optional[str],
                "quota_used": int
            }
        """
        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)

        return {
            "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,
        }

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

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

        Returns:
            标准化的视频信息字典,或 None (解析失败时)
        """
        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 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

        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,
        }


if __name__ == "__main__":
    # 简单的自测
    print("YouTube Trending Crawler 模块加载成功")
    print(f"支持的分类: {list(YouTubeTrendingCrawler.VIDEO_CATEGORIES.keys())}")