gogcli 的 YouTube 终端工作流从 API Key 配置到订阅与播放列表管理【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog即 gogcli将 Google Workspace 能力带入终端其中gog youtube别名gog yt子命令专门用于读取 YouTube 公开数据与管理账号级订阅、播放列表。本文以 docs/youtube.md 为主线结合仓库源码讲解如何配置访问权限、读取频道/视频/播放列表/评论/搜索数据、管理订阅与播放列表以及如何在自动化脚本中安全使用--dry-run、--force与结构化输出。命令总览与访问模型gog youtube在源码中由 internal/cmd/youtube.go 中的YouTubeCmd结构体定义包含 7 个子命令并各自带有别名子命令别名功能activitiesactivity列出频道动态activity资源videosvideo按 ID、热门榜或“我的评分”列出/获取视频playlistsplaylist管理播放列表及其中的视频项commentscomment列出视频或频道下的评论线程channelschannel按 ID 或“我的频道”列出频道searchfind搜索视频、频道或播放列表subscriptionssubscription管理账号订阅的频道整体访问模型分为两条路径对应 internal/googleapi/youtube.go 中的两个客户端工厂API Key 路径读取公开数据按channelId、videoId、playlistId列出等通过NewYouTubeWithAPIKey构造服务底层使用option.WithAPIKey注入 key并包一层NewRetryTransport重试传输见 internal/googleapi/youtube.go#L23-L48。OAuth 账号路径用于mine类操作当前用户频道、播放列表、动态以及所有写操作通过NewYouTubeForAccount等工厂基于账号令牌构造服务见 internal/googleapi/youtube.go#L52-L97。命令解析器在运行时按需选择服务getYouTubeReadService会先判断是否显式指定了账号--account、GOG_ACCOUNT环境变量或直接访问令牌有则走 OAuth否则走 API Key而my-rating等按用户读取的操作则强制走账号路径见 internal/cmd/youtube.go#L163-L173 与 internal/cmd/youtube_services.go。配置访问公开读取用 API Key私有操作用 OAuth公开读取开启 YouTube Data API v3 并配置 API Key对于频道、视频、动态、播放列表、评论与搜索等公开数据的读取需要先在 Google Cloud Console 开启 YouTube Data API v3获取 API Key 后写入 gog 配置gog config set youtube_api_key YOUR_API_KEY gog yt videos list --chart mostPopular --region US --max 5API Key 的读取优先级与存储细节在 internal/config/keys.go 中定义配置键名为youtube_api_key对应配置文件字段youtube_api_key见 internal/config/config.go#L18该键被标记为Sensitive: true配置写出与 dry-run 预览会对其脱敏但保留已存储的原值若环境变量GOG_YOUTUBE_API_KEY存在则优先于配置文件中的值未设置时getYouTubeAPIKey会返回提示“set config youtube_api_key KEY or GOG_YOUTUBE_API_KEY”见 internal/cmd/youtube_services.go#L11-L21。--max参数全局校验范围为 1 到 50validateYouTubeMax见 internal/cmd/youtube.go#L966-L971。账号读取默认youtube.readonly作用域账号级读取默认使用youtube.readonly只读作用域。先添加账号授权再执行--mine类命令gog auth add yougmail.com --services youtube gog yt activities list --mine --account yougmail.comactivities list的实现会请求snippet、contentDetails两个 part并依据--channel-id或--mine决定调用ChannelId(...)还是Mine(true)见 internal/cmd/youtube.go#L63-L87。写操作需要显式添加youtube.force-ssl额外作用域订阅与播放列表等变更操作要求youtube.force-ssl额外作用域。授权时通过--extra-scopes显式声明并用--force-consent强制重新走同意流程gog auth add yougmail.com --services youtube \ --extra-scopes https://www.googleapis.com/auth/youtube.force-ssl \ --force-consent从源码看该作用域字符串在 internal/cmd/youtube.go#L17 中定义为youtubeForceSSLOAuthScope与 internal/googleapi/youtube.go#L18 的scopeYouTubeForceSSL一致。写操作客户端NewYouTubeWriteForAccount与评论读取客户端NewYouTubeCommentsForAccount都会显式请求该作用域因为 Google 要求commentThreads.list也必须使用youtube.force-ssl仅youtube.readonly不足见 internal/googleapi/youtube.go#L66-L97。若账号因缺少该作用域而触发insufficientPermissions或ACCESS_TOKEN_SCOPE_INSUFFICIENT类错误wrapYouTubeForceSSLError会给出重新授权的完整提示命令见 internal/cmd/youtube.go#L1083-L1104。前提限制账号必须先拥有 YouTube 频道。若 API 返回youtubeSignupRequired需先在 youtube.com 初始化频道后重试。读取播放列表与“我喜欢的视频”列出频道或当前用户的播放列表gog yt playlists list --channel-id UC_x5XG1OV2P6uZZ5FSM9Ttw gog yt playlists list --mine --account yougmail.complaylists list请求snippet、contentDetails两个 part--channel-id与--mine互斥见 internal/cmd/youtube.go#L213-L237。表格输出包含ID、TITLE、CHANNEL、VIDEO_COUNT、PUBLISHED_AT列见 internal/cmd/youtube_presentation.go#L57-L77。查看播放列表内的视频playlists items listgog yt playlists items list --playlist-id PLAYLIST_ID --all gog yt playlists items list --playlist-id LL --account yougmail.com --all关键行为对应 internal/cmd/youtube.go#L250-L311公开播放列表可用 API Key 读取私有播放列表以及特殊的LL即“我喜欢的视频”收藏列表必须使用账号 OAuth——源码中playlistID LL时强制走账号路径--all别名--all-pages、allpages通过loadPagedItems自动翻页拉取全部数据适合大播放列表不指定--all时仅返回一页并提示用--all获取后续页每页条数由--max控制默认 50源码中Max字段默认值50JSON 模式下输出items与nextPageToken两个字段便于脚本续页。表格输出包含VIDEO_ID、TITLE、CHANNEL、POSITION、ITEM_ID、PUBLISHED_AT列见 internal/cmd/youtube_presentation.go#L105-L142。直接读取点赞/点踩视频videos list --my-rating--my-rating是按用户读取因此始终走账号 OAuth源码中myRating ! 分支强制requireAccount见 internal/cmd/youtube.go#L163-L173gog yt videos list --my-rating like --account yougmail.com --max 50 gog yt videos list --my-rating dislike --account yougmail.com --json--my-rating仅接受like或dislike且不能与--id、--chart同时使用多模式互斥校验见 internal/cmd/youtube.go#L133-L157。这两类读取都只依赖默认的youtube.readonly作用域无需额外授权。选择视频字段--parts的三种用法videos list保持了紧凑的历史默认字段snippet、contentDetails、statistics。这在源码中由youtubeVideoDefaultParts常量定义见 internal/cmd/youtube.go#L19-L23。可以通过--parts自定义gog yt videos list --id VIDEO_ID --parts all --json gog yt videos list --id YOUR_VIDEO_ID --parts snippet,fileDetails --account yougmail.com --json--parts的解析逻辑resolveParts见 internal/cmd/youtube.go#L103-L122不指定使用默认三件套snippet,contentDetails,statistics--parts all展开为youtubeVideoAllNonOwnerParts中列出的全部非属主字段——contentDetails、id、liveStreamingDetails、localizations、paidProductPlacementDetails、player、recordingDetails、snippet、statistics、status、topicDetails见 internal/cmd/youtube.go#L28-L40。all刻意排除了属主专属的fileDetails、processingDetails、suggestions三个 part显式逗号分隔列表原样透传已认证的属主可借此请求自己上传视频的属主专属字段all不能与其他 part 名混用否则报 usage 错误。管理订阅订阅相关操作都属于账号私有数据必须带--account# 列出一页订阅 gog yt subscriptions list --max 50 --account yougmail.com # 拉取全部订阅并输出 JSON gog yt subscriptions list --all --account yougmail.com --jsonsubscriptions list默认每页 50 条源码Max默认50使用--all自动翻页表格输出列为ID、CHANNEL_ID、TITLE、SUBSCRIBED_AT见 internal/cmd/youtube.go#L785-L848。订阅一个频道只需提供--channel-id底层通过Subscriptions.Insert构造youtube#channel类型的ResourceId完成见 internal/cmd/youtube.go#L854-L896gog yt subscriptions subscribe \ --channel-id UC_x5XG1OV2P6uZZ5FSM9Ttw \ --account yougmail.com退订有两种方式见 internal/cmd/youtube.go#L898-L964使用subscriptions list返回的订阅 ID 直接退订使用--channel-idgog 会先调用Subscriptions.ListMine(true)ForChannelId自动查出订阅 ID 再删除若未订阅该频道会返回 “not subscribed to channel” 错误。gog yt subscriptions unsubscribe --id SUBSCRIPTION_ID \ --account yougmail.com --force gog yt subscriptions unsubscribe --channel-id UC_x5XG1OV2P6uZZ5FSM9Ttw \ --account yougmail.com --force管理播放列表创建、添加、移除与删除创建播放列表新播放列表默认可见性为private。仅当确实需要更广可见性时才显式设置--privacy unlisted或--privacy public。源码中Privacy字段默认private枚举限定为public,unlisted,private见 internal/cmd/youtube.go#L313-L317。gog yt playlists create --title Research \ --description Videos to review \ --account yougmail.com --json创建时向snippet、status两个 part 发起Playlists.Insert携带标题、描述与可见性状态--title为必填见 internal/cmd/youtube.go#L319-L366。向播放列表添加视频gog yt playlists add --playlist-id PLAYLIST_ID --video-id VIDEO_ID \ --position 0 --account yougmail.com--position为 0 起始的插入位置不设置时追加到末尾源码默认-1表示追加设置后通过ForceSendFields确保 0 位也被发送见 internal/cmd/youtube.go#L368-L436。移除播放列表中的视频两种方式见 internal/cmd/youtube.go#L438-L515# 直接按已知的播放列表项 ID 移除 gog yt playlists remove --item-id PLAYLIST_ITEM_ID \ --account yougmail.com --force # 让 gog 按播放列表 视频 ID 自动查找该项再移除 gog yt playlists remove --playlist-id PLAYLIST_ID --video-id VIDEO_ID \ --account yougmail.com --force后者会先以PlaylistItems.ListPlaylistIdVideoIdMaxResults(1)做查找找不到则报错--video-id与--item-id二选一。删除播放列表gog yt playlists delete PLAYLIST_ID --account yougmail.com --forcedelete以位置参数接收播放列表 ID调用Playlists.Delete完成见 internal/cmd/youtube.go#L517-L555。自动化与安全dry-run、确认与结构化输出所有变更操作都支持--dry-run订阅与播放列表的每个变更命令都支持--dry-run。关键特性是dry-run 不会创建 API 服务、也不会发起任何网络请求dryRunExit在服务构造之前就返回见 internal/cmd/dryrun.go#L14。测试用例TestYouTubeMutationDryRunsAreOffline专门验证了这一行为——它注入一个“一旦被调用就失败”的假服务并断言 dry-run 下根本不会创建服务见 internal/cmd/youtube_mutations_test.go#L96-L153。gog yt playlists add --playlist-id PLAYLIST_ID --video-id VIDEO_ID \ --account yougmail.com --dry-run --jsondry-run 会输出将要执行的op与请求参数如playlistId、videoId、position方便脚本先行校验参数。由于youtube_api_key与 OAuth 凭据属于敏感字段dry-run 预览与配置写出均会脱敏。破坏性操作需要确认或--forceunsubscribe、播放列表项移除、播放列表删除这三类破坏性操作在执行前都会弹出确认提示dryRunAndConfirmDestructive见 internal/cmd/confirm.go#L55。使用方式交互场景先核对目标再确认自动化场景确认目标无误后使用--force或在刻意设计的流程中组合--no-input --force跳过交互提示。从源码看这类命令在拿到最终目标 ID 后才进行确认/dry-run例如按--channel-id退订时先查找订阅 ID、再确认删除见 internal/cmd/youtube.go#L932-L948。输出格式与 stdout/stderr 分离--json结构化 JSON适合管道处理列表类命令统一输出items与nextPageToken字段。--plain稳定的 TSV 输出如创建播放列表时输出id、title、privacy三行键值适合脚本解析。人类可读的进度信息、提示与警告始终输出到stderr不会污染 stdout 的数据流从而保证管道下游拿到的只有干净数据。延伸搜索、频道与评论读取除文档主线的订阅/播放列表外gog yt还提供同属YouTubeCmd的搜索、频道与评论读取可作为公开数据读取的补充# 搜索视频默认类型也可搜频道/播放列表 gog yt search list golang tutorial --type video --max 10 gog yt search list golang --type channel,playlist --order viewCount # 按 ID 查频道或查当前用户频道 gog yt channels list --id UC_x5XG1OV2P6uZZ5FSM9Ttw gog yt channels list --mine --account yougmail.com # 列出视频评论线程 gog yt comments list --video-id VIDEO_ID gog yt comments list --channel-id UC_x5XG1OV2P6uZZ5FSM9Ttw --max 25search的--type限定为video,channel,playlist可逗号分隔--order支持relevance,date,rating,title,videoCount,viewCount返回结果会按类型二次过滤见 internal/cmd/youtube.go#L696-L771。channels list请求snippet、statistics、contentDetails三个 part表格输出含SUBS、VIDEOS、VIEWS统计列见 internal/cmd/youtube_presentation.go#L178-L212。评论读取comments list使用CommentThreads.List请求snippetpart若走账号路径会使用带youtube.force-ssl的专用客户端见 internal/googleapi/youtube.go#L66-L80。完整参考每个子命令的全部参数可查阅仓库中的生成式命令参考文档gog-youtube-subscriptions.md 及 gog-youtube-playlists.md 覆盖订阅与播放列表的全部 flag按资源分别有 gog-youtube-activities.md、gog-youtube-videos.md、gog-youtube-channels.md、gog-youtube-comments.md、gog-youtube-search.md命令级参考如 gog-youtube-playlists-create.md、gog-youtube-playlists-add.md、gog-youtube-playlists-remove.md、gog-youtube-subscriptions-subscribe.md、gog-youtube-subscriptions-unsubscribe.md 等包含每个 flag 的默认值与说明。核心实现可进一步阅读 internal/cmd/youtube.go命令解析与业务逻辑、internal/cmd/youtube_services.go服务选择、internal/cmd/youtube_presentation.go输出列定义与 internal/googleapi/youtube.goAPI 客户端工厂与作用域管理。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考