gogcli 实战使用gog sites get获取 Google Site 元数据——命令参考、Flags 全解析与源码实现解读【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本指南以 gogcliGoogle Workspace in your terminal中的gog sites get命令为核心完整讲解其用法、全部可用 Flags、可编程输出能力并结合仓库源码深入解析其底层实现原理Drive API 调用、siteId 归一化、MIME 类型校验、字段掩码机制帮助你快速上手在终端中获取任意 Google Site新版 SitesDrive 后端的元数据并能举一反三理解gog sites家族命令的设计思路。命令定位gog sites get在 gogcli 中的角色gog sites get是 gogcli 的gog sitesGoogle SitesDrive-backed命令组下的核心查询命令用于获取 Google Site 元数据。它解决的核心问题是新版 Google SitesNew Sites本身没有独立的管理 API其站点数据以 Drive 文件的形式存在MIME 类型为application/vnd.google-apps.site因此 gogcli 选择通过Drive API来读写 Sites 元数据。gog sites get正是这一设计下最直接的查单条入口——给定一个站点 ID 或编辑 URL即可返回该站点的名称、类型、修改时间与访问链接等元数据。从源码结构看gog sites命令组共包含四个子命令见 internal/cmd/sites.gogog sites list别名ls列出 Drive 中可见的 Google Sitesgog sites search别名find按文本或 Drive 查询语言搜索站点gog sites get别名info、show获取单个站点的元数据即本文主角gog sites url别名open打印站点编辑 URL。get命令在整个命令组中承担精准定位 详情查看的职责与list/search的批量浏览形成互补。命令语法与位置参数gog sites (site) get (info,show) siteId [flags]get是子命令名info与show是官方注册的别名三者等价siteId是必填的位置参数其合法取值有两种形式源码帮助文本见 internal/cmd/sites.go站点对应的 Drive 文件 ID例如1ABCxyz...sites.google.com 编辑 URL例如https://sites.google.com/d/fileId/edit。无论传入哪种形式命令内部都会先经过 ID 归一化处理详见下文siteId 归一化小节再发起 API 请求因此日常使用中可以直接复制浏览器地址栏里的编辑器 URL 粘贴给命令无需手动提取 ID。典型用法示例# 直接使用 Drive 文件 ID gog sites get 1ABCxyz... # 使用 sites.google.com 编辑器 URL自动提取 ID gog sites get https://sites.google.com/d/1ABCxyz.../edit # 使用别名并输出 JSON 供脚本消费 gog sites show --json https://sites.google.com/d/1ABCxyz.../edit # 只取 id、name、webViewLink 三个字段机器可读格式 gog sites get --fields id,name,webViewLink -p 1ABCxyz...全部 Flags 详解gog sites get继承了 gogcli 的统一全局 Flags并提供了命令专属的--fields。下表完整列出该命令支持的全部 Flags与官方命令文档 docs/commands/gog-sites-get.md 一致Flag类型默认值说明--access-tokenstring直接使用提供的访问令牌绕过存储的 refresh token令牌约 1 小时过期-a--account--acctstring指定账号邮箱、别名或auto用于已认证的 Google API 命令--clientstringOAuth 客户端名称选择对应的已存凭据与 token bucket--colorstringauto颜色输出模式auto|always|never--disable-commandsstring逗号分隔的禁用命令列表支持点路径-n--dry-run--dryrun--noop--previewbool不执行变更打印预期动作后成功退出--enable-commandsstring逗号分隔的启用命令前缀列表支持点路径限制 CLI 可用范围--enable-commands-exactstring逗号分隔的精确启用命令列表点路径模式下父命令不会启用子命令--fieldsstringDrive API 字段掩码覆盖默认字段集例如id,name,webViewLink-y--force--assume-yes--yesbool跳过破坏性命令的确认提示--gmail-no-sendboolfalse阻止 Gmail 发送操作Agent 安全开关-h--helpkong.helpFlag显示上下文相关的帮助信息--homestring覆盖 gogcli 的 config/data/state/cache 根目录等价于GOG_HOME环境变量-j--json--machineboolfalse向 stdout 输出 JSON最适合脚本化--no-input--non-interactive--noninteractivebool绝不交互提示遇到需要输入时直接失败适用于 CI-p--plain--tsvboolfalse向 stdout 输出稳定、可解析的文本TSV无颜色--quota-projectstring指定用于计费 API 用量的 Google Cloud 项目作为X-Goog-User-Project头发送部分 API 在配合--access-token或 ADC 时需要--readonlyboolfalse在运行时阻止所有变更型 API 请求auth add也会仅请求只读 OAuth scope--results-onlybool在 JSON 模式下只输出主结果丢弃nextPageToken等信封字段--select--pick--projectstring在 JSON 模式下选择逗号分隔的字段尽力而为支持点路径。更推荐的做法是对多数命令使用--fields-v--verbosebool开启详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalse在 JSON/raw 输出中将获取到的文本字段包裹在外部不可信内容标记中命令专属 Flag--fields--fields是本命令最值得关注的专属参数。它直接透传给 Drive API 的files.get请求作为字段掩码field mask用于控制返回哪些元数据字段。gogcli 为get命令提供了一套默认字段集driveFileGetFields定义于 internal/cmd/drive_fields.goid, name, mimeType, size, modifiedTime, createdTime, parents, webViewLink, description, starred, driveId, hasThumbnail, thumbnailLink, shortcutDetails(targetId,targetMimeType,targetResourceKey)当显式传入--fields时该默认值会被整体覆盖例如--fields id,name,webViewLink只返回三个字段。合理收窄字段既能减少响应体积也能降低不必要的 API 数据暴露而默认字段集已覆盖常用元数据日常直接省略--fields即可。典型 Flag 组合场景# 非交互、JSON 输出适合定时任务或脚本管道 gog sites get --json --no-input siteId # 只读安全模式下查看不会发起任何变更请求 gog sites get --readonly siteId # 使用指定账号与配额项目 gog sites get --account workexample.com --quota-project my-billing-project siteId输出格式表格文本与 JSONgog sites get默认以键值文本行输出每行一个key\tvalue字段至少包含id、name、type、modified四个字段并在站点存在webViewLink时额外输出link行id 1ABCxyz... name Team Site type application/vnd.google-apps.site modified 2026-05-09T10:00:00Z link https://sites.google.com/d/1ABCxyz.../edit在-j/--json模式下输出改为包裹在site键下的完整 JSON 对象便于与jq、yq等工具串联{ site: { id: 1ABCxyz..., name: Team Site, mimeType: application/vnd.google-apps.site, modifiedTime: 2026-05-09T10:00:00Z, webViewLink: https://sites.google.com/d/1ABCxyz.../edit } }从实现看命令通过outfmt.IsJSON(ctx)判断输出模式JSON 路径调用outfmt.WriteJSON写出map[string]any{site: f}文本路径则逐行打印各字段见 internal/cmd/sites.go。测试 internal/cmd/sites_test.go 验证了 JSON 模式下site.id字段的解析结果可作为脚本消费该输出的参照。源码实现深度解析1. 调用链从命令到 Drive APISitesGetCmd.Run的执行流程internal/cmd/sites.go大致为通过requireSitesDriveService解析账号并创建 Drive API 客户端内部先调用requireAccount(flags)确定账号再经sitesDriveService建立服务对siteId做去空格与 URL 归一化normalizeGoogleID空值直接报empty siteId用法错误确定字段掩码--fields为空时使用默认driveFileGetFields否则使用用户提供的掩码调用svc.Files.Get(siteID)并设置SupportsAllDrives(true)与Fields(mask)发起请求对返回结果做MIME 类型校验见下文按当前输出模式JSON 或文本渲染结果。其中服务创建最终落在internal/googleapi/sites.go的NewSitesDrive它通过newGoogleServiceForAccount(ctx, email, googleauth.ServiceSites, sites, drive.NewService)构造 Drive v3 客户端。也就是说gog sites get底层完全复用 Drive API并没有独立的 Sites 服务端点。2. siteId 归一化URL 也能当 ID 用normalizeGoogleID实现见 internal/cmd/googleid.go负责把常见 Google URL 转换为纯文件 ID对sites.google.com域名的路径如/d/id/edit、/site/name/page提取/d/后面的片段作为 ID对drive.google.com支持?id查询参数、/file/d/id/view、/drive/folders/id等形态对docs.google.com支持/document/d/id/edit、/spreadsheets/d/id/edit、/presentation/d/id/edit等对无 scheme 的粘贴文本如sites.google.com/d/...会自动补全https://后再解析无法识别的输入原样返回仅去首尾空白因此直接传 Drive 文件 ID 也完全可用。这一设计让gog sites get在交互场景中非常顺手从浏览器复制的新版 Sites 编辑 URL 可直接粘贴使用。3. MIME 类型校验拒绝非站点文件命令在拿到files.get的返回后会检查f.MimeType如果非空且不等于application/vnd.google-apps.site常量driveMimeGoogleSite定义于 internal/cmd/drive.go则直接报错file siteId is not a Google Site (mimeTypeapplication/vnd.google-apps.doc)该校验由测试TestSitesGetRejectsNonSite覆盖internal/cmd/sites_test.go传入一个 MIME 类型为文档driveMimeGoogleDoc的 ID 时命令返回包含not a Google Site的错误。这意味着即使你手滑传入了普通文档、表格的 ID命令也会以明确的错误提示拒绝而不是输出误导性的元数据。4. 认证与授权范围gog sites系列命令的认证服务注册名为sitesgoogleauth.ServiceSites见 internal/googleauth/service.go其授权设计要点使用 scopehttps://www.googleapis.com/auth/drive完整 Drive 读写权限见ServiceSites配置internal/googleauth/service.go与测试TestScopes_SitesUsesDriveScopeinternal/googleauth/service_test.go依赖的 Google API 为 Drive APIdrive.googleapis.com认证方式支持OAuth 客户端凭据默认、--access-token直传令牌、ADCApplication Default Credentials配合--quota-project指定计费项目等均由 gogcli 的统一认证框架处理。因此使用gog sites get前需确保当前账号已完成认证且已授权sitesDrive服务可用gog auth status/gog auth services查看已授权服务状态。相关命令与延伸gog sites list别名ls列出可见站点支持--max默认 20、--page翻页、--all-drives/--no-all-drives、--drive限定共享盘、--query追加 Drive 过滤条件gog sites search别名find按文本搜索内部转为fullText contains ...或通过--raw-query直接传 Drive 查询语言gog sites url别名open批量打印站点编辑 URL未返回webViewLink时回退为https://sites.google.com/d/id/edit见 internal/cmd/sites.go。值得注意的约束gogcli 在gog drive download中对 Google Sites 的处理是拒绝导出并提示google sites cannot be exported through Drive; use gog sites url to open the site见 internal/cmd/drive_download.go。这从侧面印证了 Sites 元数据查询与编辑 URL 打印才是 gogcli 对该类型文件的正确操作方式而gog sites get正是这一操作链的起点。另外gog sites list与gog sites search在构造查询时都会强制附加mimeType application/vnd.google-apps.site与trashed false两个约束buildSitesQueryinternal/cmd/sites.go保证结果始终是未删除的站点这一约束行为有专门测试覆盖internal/cmd/sites_test.go可以理解为整个gog sites家族只面向站点文件的一致性保证get命令的 MIME 校验与之一脉相承。小结gog sites get用一条命令解决了在终端获取 Google Site 元数据的诉求支持 Drive 文件 ID 与编辑 URL 两种输入形式默认输出稳定的文本字段也可切换 JSON 供脚本消费配合--fields可精确控制返回字段。其底层复用 Drive API 的files.get接口辅以normalizeGoogleID的 URL 归一化与严格的 MIME 校验保证输入容错与结果可信。若你需要进一步查看 gogcli 的安装与认证配置可参考仓库 README.md 与 docs/commands/README.md 的命令索引本文涉及的关键源码与测试也可在 internal/cmd/sites.go、internal/cmd/googleid.go、internal/googleapi/sites.go 与 internal/cmd/sites_test.go 中深入研读。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考