调用YouTube Analytics API获取受众留存数据返回空rows问题咨询

以下是该问题的常见触发原因和对应修复方式，按排查优先级排序：

• 隐私阈值拦截
  YouTube Analytics API对细分维度下的低样本数据有强制隐私保护规则：当你指定的筛选维度（比如单独的ORGANIC/AD_INSTREAM受众类型）下，有效观看样本量低于最低阈值时，接口会直接返回空rows，不会返回具体指标值。而YouTube后台导出到Google Sheets时，会对低样本数据做模糊聚合处理后展示，二者的返回规则不一致。
  排查方式：先移除filters中的audienceType筛选条件，拉取该视频全受众类型的留存数据，如果此时能正常返回结果，就说明你指定的单种受众类型样本量未达API返回要求。
• 日期范围参数错误
  你当前直接将视频发布日期作为startDate传入，存在两个常见问题：
  1. 发布不满48小时的视频，非实时留存数据还未同步到API服务层，后台展示的实时数据和API可拉取的离线数据存在24-48小时的固定延迟
  2. 日期参数必须使用UTC时区的YYYY-MM-DD格式，如果直接传入本地时区的日期，会导致实际查询的时间范围偏移，没有覆盖到有效数据周期
• 筛选条件不匹配
  如果目标视频从来没有产生过对应类型的广告流量，传入audienceType==AD_INSTREAM筛选时必然返回空结果。建议先做两步校验：
  1. 仅保留video=={视频ID}的筛选条件，确认基础留存接口可以正常返回数据
  2. 对同一个视频分别查询两种audienceType下的views指标，确认对应受众类型确实存在有效观看数据后，再叠加elapsedVideoTimeRatio维度查询留存
• 鉴权参数冲突
  你同时传入了OAuth Bearer令牌和API Key，当使用channel==MINE做身份标识时，接口会优先校验OAuth令牌的权限，如果API Key所属的谷歌云项目和OAuth授权的项目不匹配，可能会导致部分细分数据被拦截。排查时可以先移除key参数，仅用OAuth令牌发起请求测试。

参考调试请求示例 #

headers = {
    'Accept': 'application/json', 
    'Authorization': f'Bearer {access_token}'
}

# 先跑通基础请求，再逐步叠加筛选条件
params = {
    'dimensions': 'elapsedVideoTimeRatio',
    'ids': 'channel==MINE',
    'metrics': 'audienceWatchRatio',
    'startDate': utc_formatted_publish_date, # 替换为UTC格式YYYY-MM-DD的发布日期
    'endDate': utc_formatted_execute_date, # 替换为UTC格式YYYY-MM-DD的查询截止日期
    'filters': f'video=={youtube_video_id}'
    # 调试阶段先不传key、不指定audienceType
}

补充说明：短视频的留存点位密度更低，对样本量的阈值要求更高；如果视频总观看量低于100次，大概率会触发API的隐私拦截规则返回空结果。

内容的提问来源于stack exchange，提问作者Dũng Nguyễn