"""接口能力描述与字段别名映射。""" COL_ALIAS_MAP = { "time": "date", "activation_channel": "ch", "first_ad_conversion_link_id": "id", "utmsrc": "utmsrc", "activation_os": "os", "activation_os_version": "syver", "activation_device_model": "dev", "activation_resolution": "res", "activation_network": "net", "activation_provider": "pvd", "activation_province": "rgn", "activation_country": "cy", "login_type": "login_type", "lang_system": "lang_system", "payment_source": "payment_source", "activation_time": "activation_time", "activation_app_version": "activation_app_version", "first_server": "first_server", "current_server": "current_server", # cost 维度 "dt": "date", "media": "media", "media_source": "msrc", "campaign_id": "camp", "ad_id": "ad", "creative_id": "crtv", "account_id": "acct", "material_id": "mtrl", "medium_id": "mdm", "ad_platform_id": "adplt", "opt_obj": "optobj", "scene": "scene", "scene_final": "scnf", "city": "city", "country": "country", "country_code": "cycd", "province": "province", "os": "os", "channel": "channel", "app_id": "appid", "tap_app_id": "tapid", "google_opt_obj": "gopt", "china_opt_obj": "copt", "project_name": "proj", } COUNTRY_GROUP_DIMS = {"activation_country", "activation_province"} AD_COL_ALIAS_MAP = { "time": "date_", "platform_id": "pf", "advertisement_id": "ad", "tag_id": "tag", "first_ad_sub_channel1": "subc", "first_ad_sub_channel2": "subc", "first_ad_sub_channel3": "subc", "first_ad_sub_channel4": "subc", "first_ad_sub_channel5": "subc", } COST_GROUPS = ( "dt", "media", "media_source", "os", "country", "country_code", "province", "city", "channel", "campaign_id", "ad_id", "creative_id", "account_id", "material_id", "ad_platform_id", "app_id", "tap_app_id", "opt_obj", "scene", "scene_final", "google_opt_obj", "china_opt_obj", "project_name", ) COST_ADVANCED_GROUPS = ( "activation_time", "medium_id", "material_type", "material_mode", "name", "tags_str", "jump_url", "account_alias", ) COST_ALL_GROUPS = COST_GROUPS + COST_ADVANCED_GROUPS COST_ADVANCED_NOTES = { "activation_time": "高级日期字段；默认按 dt 查询，只有需要按激活日期核对时使用", "medium_id": "素材/媒体明细字段；用于素材粒度排查", "material_type": "素材相关字段；用于素材类型拆分", "material_mode": "素材相关字段；用于素材形态拆分", "name": "素材相关字段；通常用于素材名称或明细名称排查", "tags_str": "素材标签字段；适合素材标签排查", "jump_url": "素材落地页/预览链接字段；仅在需要核对链接时使用", "account_alias": "账户相关字段；用于广告账户别名拆分", } # ── 各接口能力描述（基于源码 + 实测验证） ──────────────────── # # 分组/过滤中的"翻译字段"(trans_dims): activation_channel, activation_device_model, # activation_network, activation_provider, activation_province, activation_country, # first_ad_conversion_link_id, lang_system # 这些字段分组时显示的是翻译后的展示名(来自 tapdb_group_dim 表), # 但作为过滤条件时需使用视图中的原始值。 # 其中 lang_system 的过滤值会自动翻译(MergeGroupDimTranConstant), 可直接用展示名。 ENDPOINT_CAPS = { "mani_events": { "description": "运营事件: 获取运营事件列表，不传时间查全部", }, "active": { "description": "活跃数据: DAU/WAU/MAU/HAU", "quotas": ["dau", "wau", "mau", "hau"], "subjects": ["device", "user"], "returned_metrics": { "dau": [ "dau", "dau_new", "dau_2", "dau_3", "dau_7", "dau_14", "dau_30", "dau_new_rate", "dau_2_rate", "dau_3_rate", "dau_7_rate", "dau_14_rate", "dau_30_rate", ], "wau": ["wau", "wau_new", "wau_2", "wau_3", "wau_4", "wau_5"], "mau": ["mau"], "hau": ["hau", "hau_new", "hau_2", "hau_3", "hau_7", "hau_14", "hau_30"], }, "groups": [ "time", "activation_channel", "activation_os", "activation_os_version", "activation_device_model", "activation_resolution", "activation_network", "activation_provider", "activation_province", "activation_country", "first_ad_conversion_link_id", "lang_system", ], "filters": [ "activation_os", "activation_channel", "activation_os_version", "activation_device_model", "activation_resolution", "activation_network", "activation_provider", "activation_province", "activation_country", "first_ad_conversion_link_id", "lang_system", ], "filter_notes": { "activation_device_model": "翻译字段，过滤值需使用原始值（可先 group-by 此字段查看）", "activation_province": "翻译字段，过滤值需使用原始值", "activation_country": "翻译字段，值如'中国'可直接使用；港澳台会自动映射", "first_ad_conversion_link_id": "翻译字段，过滤值需使用原始值（非展示名'自然用户'）", "lang_system": "过滤值会自动翻译，可直接用展示名（如'中文'）", }, "group_notes": { "activation_province": "需传 --language", "activation_country": "需传 --language 和 --group-dim (cy 或 scon)", }, "unsupported_note": ( "不支持 activation_time/utmsrc/login_type/payment_source/activation_app_version/first_server/current_server" ), }, "op_overview": { "description": "运营概览数据: 收入/活跃/新增（新版概览缓存表）", "path": "/ad-plus/api/op/op_overview", "quotas": ["income", "active", "activation"], "intervals": ["minute", "hour", "day", "week", "month"], "required_params": ["project_id", "start_date", "end_date", "interval", "quota"], "notes": [ "minute/hour 粒度需要 compared_date，返回 base_row_data 与 compared_row_data", "day/week/month 粒度返回 row_head 时间轴与 base_row_data 指标序列", "active 在 day/week/month 分别对应 DAU/WAU/MAU", ], }, "retention": { "description": "留存数据: DR1-DR180 / WR / MR", "time_field": "activation_time", "subjects": ["device", "user"], "extra_params": ["interval_unit (day|week|month)", "all_retention (bool)"], "notes": [ "不支持 --group-unit week/month；脚本会直接拦截并返回 error，请用 day 后在答复中汇总", "输出 _query_context 明确标注 subject 及 newDevice/*_newDevice 的账号或设备口径", ], "groups": [ "activation_time", "activation_channel", "activation_os", "activation_os_version", "activation_device_model", "activation_resolution", "activation_network", "activation_provider", "activation_province", "activation_country", "first_ad_conversion_link_id", "lang_system", "activation_app_version", ], "filters": [ "activation_os", "activation_channel", "activation_os_version", "activation_device_model", "activation_resolution", "activation_network", "activation_provider", "activation_province", "activation_country", "first_ad_conversion_link_id", "lang_system", "activation_app_version", ], "filter_notes": { "activation_device_model": "翻译字段，过滤值需使用原始值", "activation_province": "翻译字段，过滤值需使用原始值", "activation_country": "翻译字段", "first_ad_conversion_link_id": "翻译字段，过滤值需使用原始值", "lang_system": "过滤值会自动翻译，可直接用展示名", }, "group_notes": { "activation_province": "需传 --language", "activation_country": "需传 --language 和 --group-dim (cy 或 scon)", }, "unsupported_note": ( "不支持 time/utmsrc/login_type/payment_source/first_server/current_server（retention_view 无此列）" ), }, "income": { "description": "收入/付费数据: 收入/付费人数/ARPU/ARPPU", "returned_metrics": [ "incomes", "pay_times", "refunds", "refund_times", "payers_num", "refunders_num", "active_users", "vp_incomes", "payment_rate", ], "extra_params": ["charge_subject (user|device)"], "groups": [ "time", "activation_channel", "activation_os", "activation_os_version", "activation_device_model", "activation_resolution", "activation_network", "activation_provider", "activation_province", "activation_country", "first_ad_conversion_link_id", "lang_system", "payment_source", "activation_app_version", "first_server", "current_server", ], "filters": [ "activation_os", "activation_channel", "activation_os_version", "activation_device_model", "activation_resolution", "activation_network", "activation_provider", "activation_province", "activation_country", "first_ad_conversion_link_id", "lang_system", "payment_source", "activation_app_version", "first_server", "current_server", ], "filter_notes": { "activation_device_model": "翻译字段，过滤值需使用原始值", "activation_province": "翻译字段，过滤值需使用原始值", "activation_country": "翻译字段", "first_ad_conversion_link_id": "翻译字段，过滤值需使用原始值", "lang_system": "过滤值会自动翻译，可直接用展示名", }, "group_notes": { "activation_province": "需传 --language", "activation_country": "需传 --language 和 --group-dim (cy 或 scon)", }, "unsupported_note": "不支持 activation_time/utmsrc/login_type", }, "source": { "description": "来源数据: 新增设备/用户/转化率/首充/留存", "time_field": "activation_time", "notes": [ "不支持 --group-unit week/month；脚本会直接拦截并返回 error，请用 day 后在答复中汇总", ], "returned_metrics": [ "newDevice", "convertedDevice", "newUser", "newChargeUser", "newTotalChargeAmount", "firstChargeuser", "firstChargeAmount", "DR1", "DR7", "DR1_newDevice", "DR7_newDevice", "converted_rate", "DR1_rate", "DR7_rate", "new_charge_user_rate", "first_charge_user_rate", ], "groups": [ "activation_time", "activation_channel", "activation_os", "activation_os_version", "activation_device_model", "activation_resolution", "activation_network", "activation_provider", "activation_province", "activation_country", "first_ad_conversion_link_id", "lang_system", "activation_app_version", "first_server", ], "filters": [ "activation_os", "activation_channel", "activation_os_version", "activation_device_model", "activation_resolution", "activation_network", "activation_provider", "activation_province", "activation_country", "first_ad_conversion_link_id", "lang_system", "activation_app_version", "first_server", ], "filter_notes": { "activation_device_model": "翻译字段，过滤值需使用原始值（可先 group-by 此字段查看）", "activation_province": "翻译字段，过滤值需使用原始值", "activation_country": "翻译字段，值如'中国'可直接使用", "first_ad_conversion_link_id": "翻译字段，过滤值需使用原始值（非展示名'自然用户'）", "lang_system": "过滤值会自动翻译，可直接用展示名（如'中文'）", }, "group_notes": { "activation_province": "需传 --language", "activation_country": "需传 --language 和 --group-dim (cy 或 scon)", }, "unsupported_note": "不支持 time/utmsrc/login_type/payment_source/current_server 字段（source_view 无此列）", }, "player_behavior": { "description": "玩家行为: 游戏时长/启动次数", "quotas": ["behavior", "duration"], "returned_metrics": { "behavior": ["total_duration", "total_times", "total_users"], "duration": ["duration", "player_num", "play_times"], }, "groups": [ "time", "activation_channel", "activation_os", "activation_os_version", "activation_device_model", "activation_resolution", "activation_network", "activation_provider", "activation_province", "activation_country", "first_ad_conversion_link_id", "lang_system", "first_server", ], "filters": [ "activation_os", "activation_channel", "activation_os_version", "activation_device_model", "activation_resolution", "activation_network", "activation_provider", "activation_province", "activation_country", "first_ad_conversion_link_id", "lang_system", "first_server", ], "filter_notes": { "activation_device_model": "翻译字段，过滤值需使用原始值", "activation_province": "翻译字段，过滤值需使用原始值", "activation_country": "翻译字段", "first_ad_conversion_link_id": "翻译字段，过滤值需使用原始值", "lang_system": "过滤值会自动翻译，可直接用展示名", }, "group_notes": { "activation_province": "需传 --language", "activation_country": "需传 --language 和 --group-dim (cy 或 scon)", }, "unsupported_note": ( "不支持 activation_time/utmsrc/login_type/payment_source/activation_app_version/current_server" ), }, "version_distri": { "description": "版本分布: 各版本活跃/新增设备数（专用接口，忽略 group 参数，固定按版本分组）", "returned_metrics": ["version", "allDevices", "newDevices", "upgradeDevices", "activeDevices", "NUDevices"], }, "user_value": { "description": "用户价值(LTV): N日贡献", "notes": [ "不支持 --group-unit week/month；脚本会直接拦截并返回 error，请用 day 后在答复中汇总", ], "returned_metrics": ["activation", "N_LTV (1-60,90,120,150,180,210,240,270,300,330,360)"], "groups": [ "time", "activation_time", "activation_channel", "activation_os", "activation_os_version", "activation_device_model", "activation_resolution", "activation_network", "activation_provider", "activation_province", "activation_country", "first_ad_conversion_link_id", "lang_system", "activation_app_version", ], "filters": [ "activation_os", "activation_channel", "activation_os_version", "activation_device_model", "activation_resolution", "activation_network", "activation_provider", "activation_province", "activation_country", "first_ad_conversion_link_id", "lang_system", "activation_app_version", "first_server", ], "filter_notes": { "activation_device_model": "翻译字段，过滤值需使用原始值", "activation_province": "翻译字段，过滤值需使用原始值", "activation_country": "翻译字段", "first_ad_conversion_link_id": "翻译字段，过滤值需使用原始值", "lang_system": "过滤值会自动翻译，可直接用展示名", "first_server": "仅支持过滤，不支持分组", }, "group_notes": { "activation_province": "需传 --language", "activation_country": "需传 --language 和 --group-dim (cy 或 scon)", }, "unsupported_note": "不支持 utmsrc/login_type/payment_source/current_server；first_server 仅可用于过滤", }, "whale_user": { "description": "鲸鱼用户: 高付费用户排行（特殊接口，无分组/过滤，直接返回用户列表）", "returned_metrics": [ "user_id", "user_name", "total_charge_amount", "server", "LEVEL", "first_charge_time", "last_charge_time", "last_login_time", ], }, "life_cycle": { "description": "用户生命周期: 付费转化/金额/累计", "quotas": ["payment_cvs_rate", "payment_cvs", "payment_amount", "acc_payment"], "returned_metrics": { "payment_amount": ["newUsers", "PA0", "PA1", "PA2", "...", "PA30"], "acc_payment": ["newUsers", "PA0", "PA1", "PA2", "...", "PA30"], "payment_cvs_rate": ["newUsers", "PR0", "PR1", "PR2", "...", "PR30"], "payment_cvs": ["newUsers", "PC0", "PC1", "PC2", "...", "PC30"], }, "notes": [ "不支持 --group-unit week/month；脚本会直接拦截并返回 error，请用 day 后在答复中汇总", ], "groups": [ "time", "activation_time", "activation_os", ], "filters": [ "activation_os", "activation_channel", "activation_os_version", "activation_device_model", "activation_resolution", "activation_network", "activation_provider", "activation_province", "activation_country", "first_ad_conversion_link_id", "lang_system", ], "filter_notes": { "activation_device_model": "翻译字段，过滤值需使用原始值", "activation_province": "翻译字段，过滤值需使用原始值", "activation_country": "翻译字段", "first_ad_conversion_link_id": "翻译字段，过滤值需使用原始值", "lang_system": "过滤值会自动翻译，可直接用展示名", }, "group_notes": { "activation_os": "仅当 quota=payment_cvs_rate 时支持；（建议改用 time/activation_time）", }, "unsupported_note": ( "分组仅支持 time/activation_time/activation_os；过滤不支持 " "activation_app_version/first_server/current_server/utmsrc/login_type/payment_source" ), }, "cost": { "description": "买量成本数据: 花费/展示/点击/获客/留存/付费/ROI 全链路", "time_field": "dt", "returned_metrics": [ "cost", "real_cost", "show_cnt", "click_cnt", "reserve_cnt", "new_device", "new_user", "new_device_safe", "new_user_safe", "reattr_new_device", "reattr_new_user", "reattr_new_device_safe", "reattr_new_user_safe", "paid_user_uv", "day1_paid_user_uv", "is_trans", "retention_2d", "retention_3d", "retention_7d", "retention_14d", "retention_30d", "retention_60d", "retention_90d", "retention_120d", "retention_150d", "retention_180d", "retention_360d", "retention_720d", "day1_paid_amount", "day2_paid_amount", "day3_paid_amount", "day7_paid_amount", "day14_paid_amount", "day30_paid_amount", "day60_paid_amount", "day90_paid_amount", "day120_paid_amount", "day150_paid_amount", "day180_paid_amount", "day360_paid_amount", "day540_paid_amount", "day720_paid_amount", "day1_paid_amount_reattr", "day2_paid_amount_reattr", "day3_paid_amount_reattr", "day7_paid_amount_reattr", "day14_paid_amount_reattr", "day30_paid_amount_reattr", "day60_paid_amount_reattr", "day90_paid_amount_reattr", "day120_paid_amount_reattr", "day150_paid_amount_reattr", "day180_paid_amount_reattr", "day360_paid_amount_reattr", "day540_paid_amount_reattr", "day720_paid_amount_reattr", "day1_real_income", "day2_real_income", "day3_real_income", "day7_real_income", "day14_real_income", "day30_real_income", "day60_real_income", "day90_real_income", "day120_real_income", "day150_real_income", "day180_real_income", "day360_real_income", "day540_real_income", "day720_real_income", "day1_real_income_reattr", "day2_real_income_reattr", "day3_real_income_reattr", "day7_real_income_reattr", "day14_real_income_reattr", "day30_real_income_reattr", "day60_real_income_reattr", "day90_real_income_reattr", "day120_real_income_reattr", "day150_real_income_reattr", "day180_real_income_reattr", "day360_real_income_reattr", "day540_real_income_reattr", "day720_real_income_reattr", ], "groups": list(COST_ALL_GROUPS), "filters": list(COST_ALL_GROUPS), "group_notes": COST_ADVANCED_NOTES, "filter_notes": COST_ADVANCED_NOTES, "unsupported_note": "不支持现有运营维度(activation_channel等)，使用广告维度(media/campaign_id等)", }, "ad_monet": { "description": ( "广告变现（monet）数据: IAA收入/eCPM/展示次数/展示人数/IPU/展示率/" "ARPU/ARPPU（走 ad-plus /ad_monet/revenue）" ), "returned_metrics": [ "IAA_AMOUNT", "ECPM", "SHOW_TIMES", "SHOW_USERS", "IPU", "SHOW_RATE", "ARPU", "ARPPU", ], "groups": [ "time", "activation_channel", "activation_os", "activation_os_version", "activation_device_model", "activation_resolution", "activation_network", "activation_provider", "activation_province", "activation_country", "first_ad_conversion_link_id", "lang_system", "activation_app_version", "first_server", "ad_network", "ad_union_type", "ad_type", ], "filters": [ "activation_os", "activation_channel", "activation_os_version", "activation_device_model", "activation_resolution", "activation_network", "activation_provider", "activation_province", "activation_country", "first_ad_conversion_link_id", "lang_system", "activation_app_version", "first_server", "ad_network", "ad_union_type", "ad_type", ], "extra_params": [ "charge_subject (user|device)", "exchange_to_currency (str, 如 USD/CNY/JPY，默认CNY)", ], "notes": [ "用户说 monet/monet 数据/monetization 时，默认指广告变现，应优先使用 ad_monet，不要误用 income/充值收入", "脚本直连 /ad-plus/api/ad_monet/revenue，非 /mcp/op/ad_monet", "ad_network/ad_union_type/ad_type 会自动映射为 #ad_network/#ad_union_type/#ad_type", ], }, "ad_data": { "description": "广告投放(买量)数据: 花费/展示/点击/激活/留存/LTV等（仅用户明确要求广告/买量数据时使用）", "quotas": { "cost_display": ["cost", "display"], "click": ["click", "uClick", "clickRate", "clickCost"], "activation": [ "activation", "activeRate", "activationCost", "newUser", "convertRate", "convertDevice", "payUserNew", "payRateNew", "payAmountNew", ], "device_retention": [ "day1Retain", "day1RetainRate", "day6Retain", "day6RetainRate", "day13Retain", "day13RetainRate", "day29Retain", "day29RetainRate", ], "payment": ["income", "payUser", "payRate", "payTimes"], "ltv": [ "day1LTV", "day3LTV", "day7LTV", "day14LTV", "day30LTV", "day60LTV", "day90LTV", "day180LTV", "day360LTV", ], }, "groups": [ "time", "platform_id", "advertisement_id", "tag_id", "first_ad_sub_channel1", "first_ad_sub_channel2", "first_ad_sub_channel3", "first_ad_sub_channel4", "first_ad_sub_channel5", ], "filters": [ "activation_os", "activation_country", "activation_continent", "activation_province", "activation_network", "activation_provider", "activation_device_model", "activation_app_version", "first_ad_platform_id", "first_ad_advertiser_id", "first_campaign_id", "first_adgroup_id", "first_creative_id", "first_ad_conversion_link_id", "activation_channel", ], "extra_params": [ "ad_increment (bool, 默认true: 仅广告增量)", "tz_offset (int, 默认8: 时区偏移)", "sort_field / sort_order (排序字段和顺序)", "charge_subject (user|device, 默认user)", "exchange_to_currency (str, 如 USD/CNY/JPY，默认CNY)", ], "notes": [ "走 /mcp/ad/multiple_display_web 接口，非 /mcp/op/*", "时间粒度固定为 day，不支持 week/month", "cost/display/click 等花费类指标仅在 platform_id/advertisement_id/tag_id 分组时有意义", "响应格式为二维数组（非 dict），脚本内部会转为 dict 列表", "需项目已开通 ad_plus 功能", ], }, }