feat(scripts): 添加批量生成 YouTube Studio 内容管理器 URL 的脚本
This commit is contained in:
297
skills/yt-studio-url-builder/scripts/build_studio_urls.py
Normal file
297
skills/yt-studio-url-builder/scripts/build_studio_urls.py
Normal file
@@ -0,0 +1,297 @@
|
||||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*-
|
||||
"""
|
||||
根据需求清单（CSV/Excel）批量拼接 YouTube Studio 内容管理器 explore URL。
|
||||
|
||||
用法:
|
||||
python build_studio_urls.py -i 需求清单.csv -o 输出.csv
|
||||
python build_studio_urls.py -i 需求清单.xlsx -o 输出.csv
|
||||
|
||||
输入列（支持中英文别名，未填可留空）:
|
||||
所有者名称 : 所有者名称 / owner_name
|
||||
所有者ID : 所有者ID / owner_id / o
|
||||
实体名称 : 实体名称 / 群组名称 / 频道名称 / 节目名称 / entity_name / group_name
|
||||
实体ID : 实体ID / 群组ID / group_id / entity_id / id
|
||||
实体类型 : 实体类型 / 类型 / entity_type (群组/所有者/频道/节目，或 GROUP/CONTENT_OWNER/CHANNEL/VIDEO)
|
||||
数据周期 : 数据周期 / 周期 / period / time_period (yyyy.mm.dd-yyyy.mm.dd 或 yyyy.m.d-yyyy.m.d)
|
||||
国家 : 国家 / 国家/地区 / country / countries (一个或多个，中文名或 ISO 两位代码)
|
||||
|
||||
说明:
|
||||
- 数据周期起止日期均包含在数据范围内，time_period 结束值取结束日后一天的日界线。
|
||||
- 国家为多个时，ur_values 以 '%27' 包裹、'%7C' 连接（如 美国,日本 -> %27US%27%7C%27JP%27）。
|
||||
- 中文国家名 -> ISO 代码的映射放在同目录 countries.json（可自行扩充）；已是两位代码的原样透传。
|
||||
- 固定参数（metric/granularity/dimension/t_metrics 等）在本文件 CONFIG 中统一配置。
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
from datetime import date
|
||||
|
||||
import pandas as pd
|
||||
from urllib.parse import quote
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 固定参数（所有需求共用，按需修改）
|
||||
# ---------------------------------------------------------------------------
|
||||
CONFIG = {
|
||||
"explore_type": "TABLE_AND_CHART",
|
||||
"metric": "SUBSCRIBERS_NET_CHANGE", # 主指标
|
||||
"granularity": "DAY", # DAY / WEEK / MONTH / YEAR
|
||||
"dimension": "USER", # 细分维度
|
||||
"t_metrics": [ # 表格列指标（可多个）
|
||||
"SUBSCRIBERS_NET_CHANGE",
|
||||
"VIDEO_COUNT_FIRST_PUBLISHED",
|
||||
"ENGAGED_VIEWS",
|
||||
"EXTERNAL_VIEWS",
|
||||
"EXTERNAL_WATCH_TIME",
|
||||
"AVERAGE_WATCH_TIME",
|
||||
"TOTAL_ESTIMATED_EARNINGS",
|
||||
],
|
||||
"o_column": "SUBSCRIBERS_NET_CHANGE", # 排序字段
|
||||
"o_direction": "ANALYTICS_ORDER_DIRECTION_DESC", # DESC / ASC
|
||||
"comparison_type": "NONE",
|
||||
}
|
||||
|
||||
# 实体类型 中文/代码 -> URL 参数值（可扩充）
|
||||
ENTITY_TYPE_MAP = {
|
||||
"群组": "GROUP", "GROUP": "GROUP",
|
||||
"所有者": "CONTENT_OWNER", "账号": "CONTENT_OWNER", "CONTENT_OWNER": "CONTENT_OWNER",
|
||||
"频道": "CHANNEL", "CHANNEL": "CHANNEL",
|
||||
"节目": "VIDEO", "视频": "VIDEO", "VIDEO": "VIDEO",
|
||||
}
|
||||
DEFAULT_ENTITY_TYPE = "GROUP"
|
||||
|
||||
# 日界线锚点 + 整日偏移（见 docs/adr/0001）
|
||||
ANCHOR_DATE = date(2026, 6, 15)
|
||||
ANCHOR_MS = 1781506800000
|
||||
MS_PER_DAY = 86400000
|
||||
|
||||
# 数据周期正则：支持 2026.07.01-2026.08.01 / 2026.7.1-2026.8.1 / 2026-07-01~2026-08-01
|
||||
PERIOD_RE = re.compile(
|
||||
r"(\d{4})[.\-/](\d{1,2})[.\-/](\d{1,2})\s*[-~～]\s*(\d{4})[.\-/](\d{1,2})[.\-/](\d{1,2})"
|
||||
)
|
||||
|
||||
# 输入列名 -> 规范字段（键为去空白、转小写后的列名）
|
||||
COLUMN_ALIASES = {
|
||||
# 所有者
|
||||
"所有者名称": "owner_name", "ownername": "owner_name", "owner_name": "owner_name",
|
||||
"所有者": "owner_name",
|
||||
"所有者id": "owner_id", "ownerid": "owner_id", "owner_id": "owner_id", "o": "owner_id",
|
||||
# 实体
|
||||
"实体名称": "entity_name", "entity_name": "entity_name",
|
||||
"群组名称": "entity_name", "group_name": "entity_name", "groupname": "entity_name",
|
||||
"频道名称": "entity_name", "节目名称": "entity_name",
|
||||
"实体id": "entity_id", "entity_id": "entity_id", "entityid": "entity_id",
|
||||
"群组id": "entity_id", "group_id": "entity_id", "groupid": "entity_id",
|
||||
"群组": "entity_id", "id": "entity_id",
|
||||
"实体类型": "entity_type", "entity_type": "entity_type", "entitytype": "entity_type",
|
||||
"类型": "entity_type", "type": "entity_type",
|
||||
# 数据周期
|
||||
"数据周期": "period", "周期": "period", "period": "period",
|
||||
"time_period": "period", "timeperiod": "period", "日期范围": "period",
|
||||
# 国家
|
||||
"国家": "countries", "国家/地区": "countries", "国家地区": "countries",
|
||||
"countries": "countries", "country": "countries", "筛选国家": "countries", "地区": "countries",
|
||||
}
|
||||
|
||||
|
||||
def ts(y, m, d):
|
||||
"""日期 -> 日界线 Unix 毫秒（锚点 + 整日偏移）。"""
|
||||
return ANCHOR_MS + (date(y, m, d) - ANCHOR_DATE).days * MS_PER_DAY
|
||||
|
||||
|
||||
def normalize_columns(df):
|
||||
"""按别名把输入列映射到规范字段。返回 (field->column_index, 未识别列名列表)。"""
|
||||
mapping = {}
|
||||
unknown = []
|
||||
for col in df.columns:
|
||||
key = str(col).strip().lower()
|
||||
field = COLUMN_ALIASES.get(key)
|
||||
if field:
|
||||
mapping[field] = col
|
||||
else:
|
||||
unknown.append(str(col))
|
||||
return mapping, unknown
|
||||
|
||||
|
||||
def parse_period(text):
|
||||
"""解析数据周期，返回 (start_ms, end_ms)，起止日期均含。"""
|
||||
text = str(text).strip()
|
||||
m = PERIOD_RE.search(text)
|
||||
if not m:
|
||||
raise ValueError("无法解析数据周期: %r（应为 yyyy.mm.dd-yyyy.mm.dd）" % text)
|
||||
y1, m1, d1, y2, m2, d2 = (int(g) for g in m.groups())
|
||||
start_ms = ts(y1, m1, d1)
|
||||
end_ms = ts(y2, m2, d2) + MS_PER_DAY # 结束日包含
|
||||
return start_ms, end_ms
|
||||
|
||||
|
||||
def load_country_map(path):
|
||||
"""加载 中文国家名 -> ISO 代码 映射。文件缺失则仅支持两位代码透传。"""
|
||||
if not os.path.exists(path):
|
||||
print("[提示] 未找到国家映射文件 %s，仅支持直接填写两位 ISO 代码" % path, file=sys.stderr)
|
||||
return {}
|
||||
with open(path, "r", encoding="utf-8-sig") as f:
|
||||
data = json.load(f)
|
||||
return {str(k).strip(): str(v).strip().upper() for k, v in data.items()}
|
||||
|
||||
|
||||
def parse_countries(text, country_map):
|
||||
"""解析国家列（一个或多个，中文名或 ISO 代码），返回 ISO 代码列表。"""
|
||||
if text is None or (isinstance(text, float) and str(text) == "nan"):
|
||||
return []
|
||||
raw = str(text)
|
||||
parts = re.split(r"[,，、;；\s|]+", raw)
|
||||
codes = []
|
||||
for part in parts:
|
||||
p = part.strip().strip("'\"").strip()
|
||||
if not p:
|
||||
continue
|
||||
upper = p.upper()
|
||||
if re.fullmatch(r"[A-Z]{2}", upper): # 已是两位 ISO 代码
|
||||
codes.append(upper)
|
||||
elif p in country_map:
|
||||
codes.append(country_map[p])
|
||||
else:
|
||||
raise ValueError("未识别的国家: %r（不在映射文件中，也不是两位 ISO 代码）" % p)
|
||||
return codes
|
||||
|
||||
|
||||
def resolve_entity_type(text):
|
||||
"""实体类型 -> URL 参数值。空则用默认群组。"""
|
||||
if text is None or (isinstance(text, float) and str(text) == "nan") or str(text).strip() == "":
|
||||
return DEFAULT_ENTITY_TYPE
|
||||
key = str(text).strip()
|
||||
if key in ENTITY_TYPE_MAP:
|
||||
return ENTITY_TYPE_MAP[key]
|
||||
raise ValueError("未识别的实体类型: %r（应为 群组/所有者/频道/节目 或 GROUP/CONTENT_OWNER/CHANNEL/VIDEO）" % key)
|
||||
|
||||
|
||||
def build_url(row, country_map):
|
||||
"""根据一行需求生成 URL。返回 (url, 状态, 错误信息)。"""
|
||||
owner_id = row.get("owner_id", "").strip()
|
||||
entity_type = resolve_entity_type(row.get("entity_type", ""))
|
||||
entity_id = row.get("entity_id", "").strip()
|
||||
|
||||
if not owner_id:
|
||||
return None, "error", "缺少所有者ID"
|
||||
if not entity_id:
|
||||
if entity_type == "CONTENT_OWNER":
|
||||
entity_id = owner_id # 账号整体场景回退
|
||||
else:
|
||||
return None, "error", "缺少实体ID"
|
||||
|
||||
period = row.get("period", "").strip()
|
||||
if not period:
|
||||
return None, "error", "缺少数据周期"
|
||||
start_ms, end_ms = parse_period(period)
|
||||
|
||||
codes = parse_countries(row.get("countries", ""), country_map)
|
||||
|
||||
base = "https://studio.youtube.com/owner/%s/analytics/tab-overview/period-default/explore" % owner_id
|
||||
params = []
|
||||
params.append("o=%s" % owner_id)
|
||||
params.append("entity_type=%s" % entity_type)
|
||||
params.append("entity_id=%s" % entity_id)
|
||||
if codes:
|
||||
ur_values = quote("|".join("'%s'" % c for c in codes), safe="") # 'US'|'JP' -> %27US%27%7C%27JP%27
|
||||
params.append("ur_dimensions=COUNTRY")
|
||||
params.append("ur_values=%s" % ur_values)
|
||||
params.append("ur_inclusive_starts=")
|
||||
params.append("ur_exclusive_ends=")
|
||||
params.append("time_period=%d%%2C%d" % (start_ms, end_ms))
|
||||
params.append("explore_type=%s" % CONFIG["explore_type"])
|
||||
params.append("metric=%s" % CONFIG["metric"])
|
||||
params.append("granularity=%s" % CONFIG["granularity"])
|
||||
for m in CONFIG["t_metrics"]:
|
||||
params.append("t_metrics=%s" % m)
|
||||
params.append("dimension=%s" % CONFIG["dimension"])
|
||||
params.append("o_column=%s" % CONFIG["o_column"])
|
||||
params.append("o_direction=%s" % CONFIG["o_direction"])
|
||||
params.append("comparison_type=%s" % CONFIG["comparison_type"])
|
||||
|
||||
url = base + "?" + "&".join(params)
|
||||
return url, "ok", ""
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description="批量拼接 YouTube Studio explore URL")
|
||||
parser.add_argument("-i", "--input", required=True, help="需求清单文件（.csv / .xlsx / .xls）")
|
||||
parser.add_argument("-o", "--output", default=None, help="输出 CSV 路径（默认：输入同目录 studio_urls_output.csv）")
|
||||
parser.add_argument("--countries", default=None, help="国家映射 JSON 路径（默认：脚本同目录 countries.json）")
|
||||
args = parser.parse_args()
|
||||
|
||||
if not os.path.exists(args.input):
|
||||
print("错误：输入文件不存在: %s" % args.input, file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
ext = os.path.splitext(args.input)[1].lower()
|
||||
if ext == ".csv":
|
||||
try:
|
||||
df = pd.read_csv(args.input, encoding="utf-8-sig")
|
||||
except UnicodeDecodeError:
|
||||
df = pd.read_csv(args.input, encoding="gbk") # Excel 另存的 ANSI/GBK
|
||||
elif ext in (".xlsx", ".xls"):
|
||||
df = pd.read_excel(args.input)
|
||||
else:
|
||||
print("错误：不支持的输入格式: %s（支持 .csv/.xlsx/.xls）" % ext, file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
df = df.dropna(how="all") # 去掉全空行
|
||||
|
||||
mapping, unknown = normalize_columns(df)
|
||||
if unknown:
|
||||
print("[提示] 未识别的列（忽略）: %s" % ", ".join(unknown), file=sys.stderr)
|
||||
missing = [f for f in ("owner_id", "period") if f not in mapping]
|
||||
if missing:
|
||||
print("错误：输入缺少必要列: %s" % ", ".join(missing), file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
countries_file = args.countries or os.path.join(os.path.dirname(os.path.abspath(__file__)), "countries.json")
|
||||
country_map = load_country_map(countries_file)
|
||||
|
||||
records = []
|
||||
errors = []
|
||||
for idx, raw in df.iterrows():
|
||||
row = {f: ("" if pd.isna(raw[mapping[f]]) else str(raw[mapping[f]])) for f in mapping}
|
||||
try:
|
||||
url, status, msg = build_url(row, country_map)
|
||||
except ValueError as e:
|
||||
url, status, msg = None, "error", str(e)
|
||||
if status == "ok":
|
||||
start_ms, end_ms = parse_period(row.get("period", ""))
|
||||
codes = parse_countries(row.get("countries", ""), country_map)
|
||||
records.append({
|
||||
"所有者名称": row.get("owner_name", ""),
|
||||
"所有者ID": row.get("owner_id", ""),
|
||||
"实体类型": row.get("entity_type", ""),
|
||||
"实体名称": row.get("entity_name", ""),
|
||||
"实体ID": row.get("entity_id", ""),
|
||||
"数据周期": row.get("period", ""),
|
||||
"国家": row.get("countries", ""),
|
||||
"国家代码": ",".join(codes),
|
||||
"开始时间戳": start_ms,
|
||||
"结束时间戳": end_ms,
|
||||
"URL": url,
|
||||
})
|
||||
else:
|
||||
errors.append((idx + 2, row.get("owner_name", ""), row.get("entity_name", ""), msg))
|
||||
|
||||
out_path = args.output or os.path.join(
|
||||
os.path.dirname(os.path.abspath(args.input)), "studio_urls_output.csv")
|
||||
out_df = pd.DataFrame(records)
|
||||
out_df.to_csv(out_path, index=False, encoding="utf-8-sig")
|
||||
print("已生成 %d 条 URL -> %s" % (len(records), out_path))
|
||||
|
||||
if errors:
|
||||
print("\n以下 %d 行生成失败：" % len(errors), file=sys.stderr)
|
||||
for r in errors:
|
||||
print(" 第%d行 所有者=%s 实体=%s：%s" % r, file=sys.stderr)
|
||||
sys.exit(2)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
24
skills/yt-studio-url-builder/scripts/countries.json
Normal file
24
skills/yt-studio-url-builder/scripts/countries.json
Normal file
@@ -0,0 +1,24 @@
|
||||
{
|
||||
"美国": "US", "日本": "JP", "英国": "GB", "德国": "DE", "法国": "FR",
|
||||
"意大利": "IT", "西班牙": "ES", "加拿大": "CA", "澳大利亚": "AU", "韩国": "KR",
|
||||
"巴西": "BR", "墨西哥": "MX", "印度": "IN", "俄罗斯": "RU", "荷兰": "NL",
|
||||
"瑞典": "SE", "挪威": "NO", "芬兰": "FI", "丹麦": "DK", "比利时": "BE",
|
||||
"瑞士": "CH", "奥地利": "AT", "波兰": "PL", "葡萄牙": "PT", "爱尔兰": "IE",
|
||||
"新西兰": "NZ", "新加坡": "SG", "马来西亚": "MY", "泰国": "TH", "越南": "VN",
|
||||
"印度尼西亚": "ID", "菲律宾": "PH", "土耳其": "TR", "沙特阿拉伯": "SA",
|
||||
"阿联酋": "AE", "以色列": "IL", "南非": "ZA", "阿根廷": "AR", "智利": "CL",
|
||||
"哥伦比亚": "CO", "秘鲁": "PE", "埃及": "EG", "尼日利亚": "NG", "中国": "CN",
|
||||
"中国台湾": "TW", "台湾": "TW", "中国香港": "HK", "香港": "HK", "中国澳门": "MO", "澳门": "MO",
|
||||
"乌克兰": "UA", "希腊": "GR", "捷克": "CZ", "匈牙利": "HU", "罗马尼亚": "RO",
|
||||
"保加利亚": "BG", "克罗地亚": "HR", "斯洛伐克": "SK", "斯洛文尼亚": "SI",
|
||||
"立陶宛": "LT", "拉脱维亚": "LV", "爱沙尼亚": "EE", "塞尔维亚": "RS", "冰岛": "IS",
|
||||
"卢森堡": "LU", "马耳他": "MT", "塞浦路斯": "CY", "巴基斯坦": "PK",
|
||||
"孟加拉国": "BD", "斯里兰卡": "LK", "哈萨克斯坦": "KZ", "卡塔尔": "QA",
|
||||
"科威特": "KW", "巴林": "BH", "阿曼": "OM", "约旦": "JO", "黎巴嫩": "LB",
|
||||
"摩洛哥": "MA", "阿尔及利亚": "DZ", "突尼斯": "TN", "肯尼亚": "KE",
|
||||
"加纳": "GH", "坦桑尼亚": "TZ", "埃塞俄比亚": "ET", "玻利维亚": "BO",
|
||||
"厄瓜多尔": "EC", "乌拉圭": "UY", "巴拉圭": "PY", "委内瑞拉": "VE",
|
||||
"巴拿马": "PA", "哥斯达黎加": "CR", "古巴": "CU", "多米尼加": "DO",
|
||||
"波多黎各": "PR", "危地马拉": "GT", "洪都拉斯": "HN", "萨尔瓦多": "SV",
|
||||
"尼加拉瓜": "NI"
|
||||
}
|
||||
Reference in New Issue
Block a user