# 查询所有云端播放器 (/zh-CN/api-reference/api-ref/media-pull/list) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 分页查询指定项目下的云端播放器。 - OpenAPI: /openapi/media-pull/media-pull.zh-CN.yaml - Operation ID: get-v1-projects-appId-cloud-player-players - Method: GET - Path: /v1/projects/{appId}/cloud-player/players - Endpoint: https://api.sd-rtn.com/v1/projects/{appId}/cloud-player/players ## Servers - https://api.sd-rtn.com `List` 方法用于分页列出该项目中所有云端播放器。 :::warning[注意] - 使用 `Create` 或 `Delete` 方法创建或销毁云端播放器,且响应状态码为 `504 Gateway Timeout` 时,为防止产生不受管理的云端播放器,声网建议你通过 `List` 方法查询该云端播放器的真实状况。 - 使用 `Create` 方法创建云端播放器并收到请求成功的响应报文后,如需调用 `List` 方法查询云端播放器,建议你等待约 10 秒再使用 `List`,以防出现查询不到任何信息的情况。 ::: ## Authorization This endpoint requires authentication. - `Basic Auth` ## Parameters - `X-Request-ID` (header, optional, string) - UUID(通用唯一识别码),标识本次请求。传入该字段后,声网服务器会在响应 Header 中返回该字段。声网推荐你对 `X-Request-ID` 赋值。如果不赋值,声网服务器会自动生成一个 UUID 传入。 - `filter` (query, optional, string) - 指定过滤条件。声网服务器只列出该项目下符合过滤条件的云端播放器。目前的过滤条件为用户创建播放器时传入的 `channelName`。 假设用户频道名为 `class32`,则将 URL 示例中 `filter={filter}` 改写为 `filter=channelName eq class32`;假设用户频道名为 `bigclass`,则将 URL 示例中 `filter={filter}` 改写为 `filter=channelName eq bigclass`。**eq** 前后有空格,空格需按照 URL 规范进行编码。 - `pageSize` (query, optional, number) - 指定分页大小。取值范围为 1 到 500。默认值为 200,即如果不设值,声网服务器将列出单页内至多 200 个云端播放器。 - `pageToken` (query, optional, string) - 指定页码,标明该页的次序。如果不设值,声网服务器将返回第一页。 **推荐用法**:首次使用 List 时,不向该参数传值,得到首页的查询结果和声网服务器返回的 `nextPageToken` 值。下一次使用 List 时,将 `nextPageToken` 值传入 `pageToken` 查询下一页的云端播放器。使用以上字段后,声网服务器会从指定项目中过滤出符合条件的云端播放器,根据指定的分页大小进行分页并返回结果,直到 `nextPageToken` 为 0,表示已查到一个项目下所有云端播放器。云端播放器根据创建时间(`createTs`)升序排列。 - `appId` (path, required, string) - 声网为每个开发者提供的 **App ID**。在声网控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。 ## Request body No request body. ## Responses ### 200 如果状态码为 2XX,则请求成功。 - `totalSize` (number) - 符合查询条件的云端播放器数量。 - `players` (array) - > [!CAUTION] > 个别 `player` 可能暂时只包含 `id`,`name`,`createTs` 三个字段,你的程序需要能够处理这种情况。 - `players.items` (object) - `players.items.name` (string) - 云端播放器的名字。 - `players.items.streamUrl` (string) - 在线媒体流 URL 地址。 - `players.items.channelName` (string) - 声网频道名称。 - `players.items.uid` (number) - 云端播放器在声网频道内的用户 UID。 - `players.items.account` (string) - 云端播放器在声网频道内的用户 Account。 - `players.items.id` (string) - 云端播放器的 ID。它是声网服务器生成的一个 UUID(通用唯一识别码),标识已创建的一个云端播放器。 - `players.items.createTs` (number) - 云端播放器创建的 Unix 时间戳(秒)。 - `players.items.status` (string) - 云端播放器的运行状态: - `"idle"`:播放未开始。 - `"connecting"`:声网服务器正在连接媒体流地址或正在探测音视频数据。 - `"running"`:正在播放。 - `"failed"`:声网服务器无法连接媒体流地址或该媒体流无法播放。 - `fields` (string) - JSON 编码方式的字段掩码,详见[谷歌 protobuf FieldMask 文档](https://googleapis.dev/nodejs/pubsub/latest/google.protobuf.html#.FieldMask)。用于指定返回 `players` 数组中每个 player 中的字段子集。在使用 `uid` 的示例中,`fields` 指定声网服务器返回 `players` 数组中每个 player 中的 `name`,`streamUrl`,`channelName`,`uid`,`id`,`createTs` 和 `status` 字段子集。 - `nextPageToken` (string) - 本次查询页面的**下一页页码**,方便用户下一次调用 `List` 方法继续查询。如果返回的该字段为空字符串,则本次请求已查询到最后一页。 ### 非 2XX 如果状态码不为 2XX,请求失败。 - `message` (string) - 描述请求失败的具体原因。 ## Response examples ### 200 ```json { "totalSize": 10, "players": [ { "name": "class32_101", "streamUrl": "rtmp://example.agora.io/live/class32/101", "channelName": "class32", "uid": 101, "id": "2a784467d647bb87b60b719f6fa56317", "createTs": 1575508644, "status": "running" }, { "name": "class68_422", "streamUrl": "rtmp://example.agora.io/live/class68/422", "channelName": "class68", "uid": 422, "id": "0b719f6fa563172a784467d647bb87b6", "createTs": 1575588644, "status": "connecting" } ], "fields": "player.name,player.streamUrl,player.channelName,player.uid,player.id,player.createTs,player.status", "nextPageToken": "7b60b7***" } ``` ### 非 2XX ```json { "message": "Invalid authentication credentials." } ```