用途：为 GA4 Data API 配置认证，提供两条生产级路径，需在开始前选定，中途混用是常见失败原因。
主要能力：路径 A 服务账号，适用于自动化、CI、服务端脚本，令牌长期有效、可限定范围、可撤销，凭据文件默认位于 ~/.config/gcloud/sa-ga4.json。路径 B OAuth 用户凭据，适用于交互式使用、多个 GA4 媒体资源、临时分析，令牌从 ~/.config/gcloud/application_default_credentials.json 刷新。建议管道、报表运行器或智能体使用服务账号，人工操作使用 OAuth，且不要跨机器共享 OAuth 用户凭据。
使用方式：前置条件包括可创建服务账号并启用 API 的 Google Cloud 项目，或可访问目标 GA4 媒体资源的 Google 账号；GA4 媒体资源 ID（纯数字，非 G- 开头的衡量 ID）；gcloud 已认证，Python 验证还需安装 Google Analytics Data API 客户端库。路径 A 步骤：用 gcloud iam service-accounts create 创建服务账号，用 gcloud iam service-accounts keys create 生成密钥；在 GA4 网页界面 Admin → Property → Property Access Management 添加服务账号邮箱并授予 Viewer 角色；用 gcloud services enable analyticsdata.googleapis.com 启用 Data API；再以 GOOGLE_APPLICATION_CREDENTIALS 与 PROPERTY_ID 运行 Python 验证脚本。路径 B 使用 gcloud auth application-default login 并指定 analytics.readonly 与 cloud-platform 范围，浏览器登录后自动生成 ADC 文件，客户端在未设置 GOOGLE_APPLICATION_CREDENTIALS 时自动读取。
限制与注意：GA4 媒体资源 ID 为 9 位数字，需在 Admin → Property Details 获取。切勿提交服务账号 JSON 密钥，应加入 .gitignore，可用 SOPS+age 管理并至少每年轮换密钥。GA4 媒体资源级权限仅授予 Viewer，避免 Editor 或 Administrator 带来的删除风险。常见错误：403 PermissionDenied 表示服务账号未加入媒体资源；403 SERVICE_DISABLED 表示 API 未启用；401 UNAUTHENTICATED 表示凭据文件缺失或不可读；使用 G- 衡量 ID 会报无效媒体资源 ID；默认 Data API 配额为每媒体资源每天 20 万 tokens，超限需检查配额或调整查询。验证成功时会打印日期与活跃用户行。