logo
控制台登录/注册
文档
服务端 API
云端播放器
API 概览
调用方法
在线调试服务端 API
POST
创建云端播放器
POST
更新云端播放器
POST
销毁云端播放器
POST
查询云端播放器列表
POST
创建上传任务
POST
取消上传任务
POST
查询上传任务
回调说明
全局返回码
当前页

DescribePlayers

POST

https://cloud-player-api.zego.im/

调用本接口查询 AppID 下所有的云端播放器任务列表，包含已创建、正在运行中、已销毁等所有状态；或查询指定云端播放器的任务信息。

说明
调用频率限制：20 次/秒

Request

Query Parameters

    Action string必填

    可选值: [DescribePlayers]

    接口原型参数

    https://cloud-player-api.zego.im?Action=DescribePlayers

    AppId uint32必填

    💡公共参数。应用 Id，由 ZEGO 分配的用户唯一凭证。可从 ZEGO 控制台 获取。

    SignatureNonce string必填

    💡公共参数。16 位 16 进制随机字符串（8 字节随机数的 hex 编码）。生成算法可参考 签名示例。

    Timestamp int64必填

    💡公共参数。当前 Unix 时间戳，单位为秒。生成算法可参考 签名示例，最多允许 10 分钟的误差。

    SignatureVersion string必填

    可选值: [2.0]

    默认值: 2.0

    💡公共参数。签名版本号。

    Signature string必填

    💡公共参数。签名，用于验证请求的合法性。请参考签名机制生成。

Body

required
    RoomId string

    可选值: <= 128 characters

    查询指定房间 ID，长度在 128 字节以内。 如果填写了 RoomId，请确保 RoomId 是已存在的，否则查询结果可能为空。

    注意

    • RoomId 和 PlayerId 都不填写时，调用本接口会返回 AppId 下所有的云端播放器任务列表。
    • RoomId 填写、PlayerId 不填写时，调用本接口会返回 AppId 下该房间 RoomId 内的所有的云端播放器任务列表。
    • PlayerId 填写（RoomId 填或不填均可）时，调用本接口会返回该 PlayerId 对应的云端播放器任务信息。
    PlayerId string

    云端播放器唯一标识 ID，通过 CreatePlayer 返回。 如果填写了 PlayerId，请确保 PlayerId 是已存在的，否则查询结果可能为空。

    注意

    • RoomId 和 PlayerId 都不填写时，调用本接口会返回 AppId 下所有的云端播放器任务列表。
    • RoomId 填写、PlayerId 不填写时，调用本接口会返回 AppId 下该房间 RoomId 内的所有的云端播放器任务列表。
    • PlayerId 填写（RoomId 填或不填均可）时，调用本接口会返回该 PlayerId 对应的云端播放器任务信息。
    PageSize number

    分页大小，取值范围 (0, 50]，默认为 50 个/页，指调用本接口一次最多返回的任务列表数量。 超过 PageSize 取值的任务列表，需要根据前一次调用本接口时、返回结果中的 NextPageToken（查询任务列表分页起始位）取值，再次调用本接口进行查询。

    例如，当前有 123 个云端播放器任务，PageSize 取值为 50，调用本接口查询时：

    • 第一次调用本接口，入参 PageToken 传空，查询第 1 ～ 50 的播放器任务；返回结果中 NextPageToken 值假设为 "pagetoken1"。
    • 第二次调用本接口，入参 PageToken 取值为 "pagetoken1"，查询第 51 ～ 100 的播放器任务；返回结果中 NextPageToken 值假设为 "pagetoken2"。
    • 第三次调用本接口，入参 PageToken 取值为 "pagetoken2"，查询第 101 ～ 123 的播放器任务；查询完毕，返回结果中 NextPageToken 为空。
    PageToken string

    查询任务列表分页起始位，该参数不填写时，默认返回查询到的第一页任务列表。

    每次调用本接口发起请求时，响应结果中都会返回 NextPageToken，开发者需要判断是否查询到最后一页。

Responses​

OK
Schema
    Code number

    错误码。

    以下仅列出了接口业务逻辑相关的返回码，完整返回码请参考 全局返回码。

    返回码说明处理建议
    0成功。-
    100000004签名过期。请重新生成签名。
    100000005签名错误。请确认生成签名的参数是否正确。
    350006001接口请求频率超过上限。请确认对应接口的 QPS 限制，降低请求频率。
    350006002网关校验失败。请联系 ZEGO 技术支持处理。
    350006003无效的输入参数。请根据 Message 提示，调整对应参数的取值。
    350006006服务未开通。请联系 ZEGO 技术支持，开通服务权限。
    350010000系统错误。请联系 ZEGO 技术支持处理。
    Message string

    错误描述。

    RequestId string

    请求 ID。

    Data object
    返回的具体信息。
    TotalSize number

    查询到的云端播放器任务总数。

    NextPageToken string

    本次查询的下一页页码。NextPageToken 为空时，表示已查询到最后一页。

    Players object[]
    查询到的云端播放器任务信息。
  • Array[
    • PlayerId string

    云端播放器唯一标识 ID。

    RoomId string

    房间 ID。

    StreamId string

    推流到指定房间的流 ID。

    CreateTime number

    播放器创建时间，Unix 时间戳，单位为秒。

    PlayTime number

    开始播放媒体资源的时间，Unix 时间戳，单位为秒。

    PlayerName string

    云端播放器的名称。

    StreamUrl string

    播放的媒体资源的地址。

    Status number

    可选值: [1, 2, 3, 4, 5, 6, 7, 8]

    云端播放器的状态。

    • 1：创建中。
    • 2：连接媒体资源中。
    • 3：等待播放。
    • 4：播放中。
    • 5：暂停中。
    • 6：连接媒体资源失败。
    • 7：播放结束。
    • 8：已销毁。
    DestroyReason number

    可选值: [1, 2, 3, 4, 5]

    云端播放器销毁的原因。

    • 1：调用了 DeletePlayer 接口主动销毁。
    • 2：处于空闲状态的时长超过了 MaxIdleTime。
    • 3：媒体资源播放已结束。
    • 4：推流失败。
    • 5：进入房间失败或被踢出房间。
    StreamUrlList string[]

    播放的媒体资源列表。

    PlayIndex number

    当前播放的媒体资源下标。播放器销毁后返回 0。

  • ]

Previous

销毁云端播放器

Next

创建上传任务

当前页

返回到顶部