You need to enable JavaScript to run this app.
导航
视频点播
  • 文档首页
    • /视频点播/API 参考/数据统计/播放统计/GetVodMediaPlayData - 获取播放质量数据
GetVodMediaPlayData - 获取播放质量数据
最近更新时间：2025.03.26 18:02:02首次发布时间：2025.03.26 17:34:38
我的收藏
有用
有用
无用
无用

调用 GetVodMediaPlayData 通过应用 ID 获取音视频在指定时间范围内的播放 QoS 和 QoE 指标数据。

注意事项

  • 本接口的单用户 QPS 限制为 10 次/秒。超过限制，API 调用会被限流，这可能会影响您的业务，请合理调用。更多信息，请参见 QPS 限制。
  • 支持查询最近一年的数据。
  • 单次查询的时间范围不可超过 90 天。

请求说明

  • 请求方式：POST
  • 请求地址：https://vod.volcengineapi.com?Action=GetVodMediaPlayData&Version=2025-03-03

调试

API Explorer
您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。
去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共请求参数。

Query

参数
类型
是否必选
示例值
描述
Action
String
是
GetVodMediaPlayData
接口名称。当前 API 的名称为 GetVodMediaPlayData。
Version
String
是
2025-03-03
接口版本。当前 API 的版本为 2025-03-03。

Body

参数
类型
是否必选
示例值
描述
AppID
String
是
123456
应用 ID。
Platform
String
是
mobile

设备类型，取值如下：

  • mobile: 移动端
  • web: Web 端
  • wxApp: 微信小程序
  • dyApp: 抖音小程序
StartTime
String
是
2025-03-01T10:00:00+08:00
查询的起始时间。遵循 RFC3339 格式的 UTC 时间，精度为秒，格式为：yyyy-MM-ddTHH:mm:ssZ。
EndTime
String
是
2025-03-01T10:00:00+08:00
查询的结束时间。遵循 RFC3339 格式的 UTC 时间，精度为秒，格式为：yyyy-MM-ddTHH:mm:ssZ。
Granularity
Integer
否
300

聚合的时间粒度。单位为秒。该 API 基于 Interval 将 StartTime 和 EndTime 所表示的统计时间段拆分成一系列的时间区间，然后对每个时间区间统计数据。取值如下：

  • 0:（默认）不按照时间聚合
  • 300: 5 分钟
  • 3600: 1 小时
  • 86400: 1 天
Metrics
String[]
是
cnt

指标列表，取值如下：

  • cnt: 播放量
  • vplay_actual_cnt: 实际播放量
  • fail_rate: 播放失败率
  • firstframe_duration_avg: 首帧时间
  • buffer_rate: 卡顿率
  • broken_rate: 中断率
  • leave_without_play_rate: 未起播率
  • buf_time_per_100_sec_avg: 百秒卡顿时长
  • buffer_count_100sec_avg: 百秒卡顿次数
  • video_bsp_avg: 平均播放码率
  • avg_seek_dur: 平均 Seek 时长
  • vplay_finish_cnt: 完播量
  • uv: 播放用户数
  • vplay_finish_rate: 完播率
  • vv_duration_avg: 人均播放时长
  • vv_avg: 人均播放数
  • finish_vv_avg: 人均完播次数
  • watch_dur_avg: 平均播放时长
  • video_dur_avg: 平均视频时长

说明

指标详细介绍请见指标说明。

Dimensions
String[]
否
os

维度列表。取值如下：

  • video_id: 视频 ID，即视频点播服务生成的 vid。
  • os: 系统类型
  • tag: 业务类型
  • subtag: 子业务类型
  • app_version: 应用版本号
  • codec: 视频编码格式
  • os_version: 系统版本
  • source_type: 播放方式
  • vtype: 视频格式
  • is_hw: 是否硬解
  • video_definition: 视频分辨率
  • network: 网络类型
  • cdn_name: CDN 厂商
  • carrier: 运营商
  • province: 省份
  • country: 国家
  • domain: 域名
  • error_code_display: 播放器错误码
  • a_codec: 音频编码格式
  • ttsdk_version: TTSDK 版本号
  • sdk_version: 播放器 SDK 版本

说明

  • 最多可添加 3 个维度。
  • 维度详细介绍请见维度说明。
Filter
Object
是
-
过滤器配置。
Logic
String
是
and

逻辑操作符，取值如下：

  • and: 与关系
  • or: 或关系
Filters
Object[]
是
-
子过滤器配置。
Field
String
是
os

维度。取值如下：

  • video_id: 视频 ID，即视频点播服务生成的 vid。
  • os: 系统类型
  • tag: 业务类型
  • subtag: 子业务类型
  • app_version: 应用版本号
  • codec: 视频编码格式
  • os_version: 系统版本
  • source_type: 播放方式
  • vtype: 视频格式
  • is_hw: 是否硬解
  • video_definition: 视频分辨率
  • network: 网络类型
  • cdn_name: CDN 厂商
  • carrier: 运营商
  • province: 省份
  • country: 国家
  • domain: 域名
  • error_code_display: 播放器错误码
  • a_codec: 音频编码格式
  • ttsdk_version: TTSDK 版本号
  • sdk_version: 播放器 SDK 版本

说明

维度详细介绍请见维度说明。

Op
String
是
in

操作符，取值如下：

  • ">": 大于
  • "<": 小于
  • ">=": 大于等于
  • "<=": 小于等于
  • "like": 模糊匹配
  • "not like": 模糊不匹配
  • "in": 包含
  • "not in": 不包含
Values
String[]
是
Android
与 Field 对应的比较值。例如，当 Field 为 os 时，Values 可设为 Android 或 iOS。长度不超过 100。
Field
String
是
os

维度。取值如下：

  • video_id: 视频 ID，即视频点播服务生成的 vid。
  • os: 系统类型
  • tag: 业务类型
  • subtag: 子业务类型
  • app_version: 应用版本号
  • codec: 视频编码格式
  • os_version: 系统版本
  • source_type: 播放方式
  • vtype: 视频格式
  • is_hw: 是否硬解
  • video_definition: 视频分辨率
  • network: 网络类型
  • cdn_name: CDN 厂商
  • carrier: 运营商
  • province: 省份
  • country: 国家
  • domain: 域名
  • error_code_display: 播放器错误码
  • a_codec: 音频编码格式
  • ttsdk_version: TTSDK 版本号
  • sdk_version: 播放器 SDK 版本

说明

维度详细介绍请见维度说明。

Op
String
是
in

操作符，取值如下：

  • ">": 大于
  • "<": 小于
  • ">=": 大于等于
  • "<=": 小于等于
  • "like": 模糊匹配
  • "not like": 模糊不匹配
  • "in": 包含
  • "not in": 不包含
Values
String[]
是
Android
与 Field 对应的比较值。例如，当 Field 为 os 时，Values 可设为 Android 或 iOS。长度不超过 100。

返回参数

下表仅列出本接口特有的返回参数。更多信息请见公共返回参数。

参数
类型
示例值
描述
TotalPoint
Float
1
总点数
Columns
Object[]
-
详细信息
Name
String
os
指标或维度
Alias
String
系统类型
指标或维度名称
Type
String
Count

数据类型：

  • String: 维度，没有单位
  • Count: 个数
  • percent: 百分比
  • time: 时长
  • bps: 带宽
  • Bytes: 流量
ValueAlias
String
-
维度值别名
Data
Object[]
-
具体数据，会包含指标和维度。如果聚合粒度不为 0，还会包含时间字段。

请求示例

本示例演示如何获取 UV 和播放量。

POST https://vod.volcengineapi.com?Action=GetVodMediaPlayData&Version=2025-03-03
{
  "AppID": "123456",
  "Platform": "mobile",
  "Granularity": 0,
  "Dimensions": [
    "os"
  ],
  "Metrics": [
    "uv",
    "cnt"
  ],
  "StartTime": "2025-03-01T10:00:00+08:00",
  "EndTime": "2025-03-01T15:00:00+08:00",
  "Filter": {
    "Field": "os",
    "Op": "in",
    "Values": [
      "Android"
    ]
  }
}

返回示例

{
  "ResponseMetadata": {
    "RequestId": "02174107400651000000000000000000000ffff0a25346e438493",
    "Action": "GetVodMediaPlayData",
    "Version": "2025-03-03",
    "Service": "vod",
    "Region": "cn-north-1"
  },
  "Result": {
    "Columns": [
      {
        "Name": "os",
        "Alias": "系统类型",
        "Type": "string"
      },
      {
        "Name": "uv",
        "Alias": "播放用户数",
        "Type": "count"
      },
      {
        "Name": "cnt",
        "Alias": "播放量",
        "Type": "count"
      }
    ],
    "Data": [
      {
        "cnt": 6804139,
        "os": "Android",
        "uv": 324493
      }
    ],
    "TotalPoint": 1
  }
}

错误码

下表列举了本接口特有的错误码。如需了解更多错误码，详见视频点播公共错误码。

状态码错误码错误信息说明
400InvalidReqBodyInvalid request body: %s请求内容不合法
400ErrStartGreaterThanEndTimeThe end time should be greater than the start time结束时间应该大于开始时间
400ErrTimeSpanBeyondLimitThe time span is beyond the limit时间跨度超限
400ErrInvalidOsInvalid os系统参数不合法
404MetricNotExistMetric '%s' cannot be found.指标不存在
403AppIDNoAuthUnauthorized appid没有应用的权限
500ServiceFailureThe request processing has failed because of an unknown error服务端异常
404DimensionNotExistDimension: '%s' cannot be found.维度不存在
404GranularityConflictmetric '%s' and dimension '%s' cannot be both found in granularity(%ds), switch to other granularity or other combined condition.指标和维度在指定粒度下不同时存在，尝试其他粒度或组合条件
404GranularityConflictSinglemetric or dimension '%s' cannot be found in granularity(%ds), switch to other granularity and try again.指标或维度在指定粒度下不存在，尝试其他查询粒度