# 查询所有云端播放器 (/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."
}
```