文档中心
星图
服务端 API
明细数据
查看用户拉流质量和性能明细

查看用户拉流质量和性能明细

更新时间：2025-02-08 10:08

描述

本接口可用于根据用户 ID、时间段、房间 ID 和流 ID 查询拉流质量和设备性能。

接口原型

请求方法：GET
请求地址：https://analytics-api.zego.im/?Action=GetPlayQualityDetail
传输协议：HTTPS
调用频率限制（同一 AppID）：3 次/秒，10000 次/天

请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表请参考调用方式 - 公共请求参数。

参数	类型	是否必选	描述
RoomId	String	是	房间 ID。
UserId	String	是	用户 ID。
StreamId	String	是	流 ID。
Metrics[]	Array of String	是	需要查询的指标列表，详情见拉流质量指标说明。
StartTs	Number	是	开始时间，UTC 时间戳，单位为毫秒。
EndTs	Number	是	结束时间，UTC 时间戳，单位为毫秒。如果推流未结束，则可以用 0 或者当前时间戳表示进行中。

拉流质量指标说明

指标名称	字段名	数据类型	备注
音频码率	audio_bitrate	Int	单位：Kbps
音频接收帧率	audio_network_fps	Float	单位：fps
音频卡顿率	audio_break_percentage	Float	取值范围：0-100
视频码率	video_bitrate	Float	单位：Kbps
视频接收帧率	video_network_fps	Float	单位：fps
视频卡顿率	video_break_percentage	Float	取值范围：0-100
视频解码分辨率	decode_resolution	String	格式：宽*高
端到端延迟	peer_to_peer_delay	Float	单位: ms
端到端丢包	peer_to_peer_plr	Int	取值范围：0-100
下行延迟	downlink_delay	Int	单位: ms
下行丢包	downlink_packet_loss_rate	Int	取值范围：0-100
输出音量	rendered_sound_level	Int	取值范围：0-100
音频体验	mos	Float	取值范围：0-5 大于 4.0 ：优，音质佳，清晰流畅。 3.5-4.0：良，音质较好，偶有音质损伤，但依然清晰。 3.0-3.5：中，音质一般，偶有卡顿，不是非常流畅，需要一点注意力才能听。 2.5-3.0：音质较差，卡顿频繁，需要集中精力才能听清。差： 2.0-2.5：音质很差，偶有杂音，部分语义丢失，难以交流。小于2.0：音质非常差，杂音频现，大量语义丢失，完全无法交流。
系统 CPU 使用率	sys_cpu_used	Int	取值范围：0-100
App CPU使用率	app_cpu_used	Int	取值范围：0-100
系统内存使用量	sys_mem_used	Int	单位：MB
App 内存使用量	app_mem_used	Int	单位：MB

请求示例

https://analytics-api.zego.im/?Action=GetPlayQualityDetail
&RoomId=room
&UserId=userA
&StreamId=streamA
&Metrics[]=audio_bitrate
&Metrics[]=downlink_delay
&StartTs=1672565276000
&EndTs=1672565456000
&<公共请求参数>

响应参数

参数	类型	描述
Code	Number	返回码。
Message	String	操作结果描述。
RequestId	String	请求 ID。
Data	Object	响应数据。
Metrics	Array of Object	指标列表。
Metric	String	指标名。
Values	Array of Object	指标值列表。
Value	见上文拉流质量指标说明	指标值。
Timestamp	Number	UTC 时间戳，单位为毫秒。

响应示例

{
    "Code": 0,
    "Data": {
        "Metrics": [
            {
                "Metric": "audio_bitrate",
                "Values": [
                    {
                        "Timestamp": 1659411660000,
                        "Value": 0
                    },
                    {
                        "Timestamp": 1659411720000,
                        "Value": 0
                    },
                    {
                        "Timestamp": 1659411780000,
                        "Value": 0
                    },
                    {
                        "Timestamp": 1659411840000,
                        "Value": 0
                    },
                    {
                        "Timestamp": 1659411900000,
                        "Value": 0
                    }
                ]
            }
        ]
    },
    "Message": "success",
    "RequestId": 1659512998878671000
}

返回码

返回码	说明	处理意见
0	成功。	-
500	接口错误。	请联系 ZEGO 技术支持。
10001	参数格式错误。	请检查参数。
10002	参数错误或参数无效。	请检查参数。
30002	接口请求频率超过上限。	请确认对应接口的 QPS 限制，降低请求频率。