# 查询云端录制状态 (/zh-CN/api-reference/api-ref/cloud-recording/query)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

查询云端录制任务的当前状态。

- OpenAPI: /openapi/cloud-recording/cloud-recording.zh-CN.yaml
- Operation ID: query-cloud-recording
- Method: GET
- Path: /v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/query
- Endpoint: https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/query

## Servers

- https://api.sd-rtn.com

`query` 方法用于查询云端录制状态。

开始录制后，你可以调用 `query` 方法查询录制状态。


:::warning[注意]
`query` 请求仅在会话内有效。如果录制启动错误，或录制已结束，调用 `query` 将返回 `404`。
:::

## Authorization

This endpoint requires authentication.

- `Basic Auth`

## Parameters

- `Authorization` (header, required, string) - 声网云端录制 RESTful API 仅支持 HTTPS 协议。发送请求时，你需要使用声网提供的客户 ID 和客户密钥生成 Base64 编码凭证，并填入请求头部的 `Authorization` 字段中。详见[实现 HTTP 基本认证](/zh-CN/realtime-media/cloud-recording/build/setup-and-access/http-basic-auth)。
  - Example: `Basic <credentials>`
- `Content-Type` (header, optional, string) - `application/json`。
- `appid` (path, required, string) - 你的项目使用的 [App ID](/zh-CN/realtime-media/cloud-recording/build/setup-and-access/enable-service#获取-app-id)。

- 对于页面录制模式，只需输入开通了云端录制服务的 App ID。
- 对于单流和合流录制模式，必须使用和待录制的频道相同的 App ID，且该 App ID 需要开通云端录制服务。
- `resourceid` (path, required, string) - 通过 [`acquire`](./acquire) 请求获取到的 Resource ID。
- `sid` (path, required, string) - 通过 [`start`](./start) 获取的录制 ID。
- `mode` (path, required, string) - 录制模式：

- `raw`：[单流录制模式](/zh-CN/realtime-media/cloud-recording/build/recording-modes/individual-mode/set-individual)。
- `mix`：[合流录制模式](/zh-CN/realtime-media/cloud-recording/build/recording-modes/mix-mode/set-composite)。
- `web`：[页面录制模式](/zh-CN/realtime-media/cloud-recording/build/recording-modes/web-mode/set-webpage-recording)。

## Request body

No request body.

## Responses

### 200

如果返回的 HTTP 状态码为 `200`，表示请求成功。

- `resourceId` (string) - 云端录制使用的 Resource ID。
- `sid` (string) - 录制 ID。
- `serverResponse` (object) - **页面录制**模式下会返回的字段。
  - `serverResponse.status` (number) - 当前云服务的状态：
- `0`：没有开始云服务。
- `1`：云服务初始化完成。
- `2`：云服务组件开始启动。
- `3`：云服务部分组件启动完成。
- `4`：云服务所有组件启动完成。
- `5`：云服务正在进行中。
- `6`：云服务收到停止请求。
- `7`：云服务所有组件均停止。
- `8`：云服务已退出。
- `20`：云服务异常退出。
  - `serverResponse.fileListMode` (string) - `fileList` 字段的数据格式：
- `"string"`：`fileList` 为 String 类型。合流录制模式下，如果 `avFileType` 设置为 `["hls"]`，`fileListMode` 为 `"string"`。
- `"json"`：`fileList` 为 JSON Array 类型。单流或合流录制模式下 `avFileType` 设置为 `["hls","mp4"]` 时，`fileListMode` 为 `"json"`。
  - `serverResponse.fileList` (string) - 录制产生的 M3U8 文件的文件名。
    - `serverResponse.fileList.items` (object)
      - `serverResponse.fileList.items.fileName` (string) - 录制产生的 M3U8 文件和 MP4 文件的文件名。
      - `serverResponse.fileList.items.trackType` (string) - 录制文件的类型。
- `"audio"`：纯音频文件。
- `"video"`：纯视频文件。
- `"audio_and_video"`：音视频文件。
      - `serverResponse.fileList.items.uid` (string) - 用户 UID，表示录制的是哪个用户的音频流或视频流。合流录制模式下，`uid` 为 `"0"`。
      - `serverResponse.fileList.items.mixedAllUser` (boolean) - 用户是否是分开录制的。
- `true`：所有用户合并在一个录制文件中。
- `false`：每个用户分开录制。
      - `serverResponse.fileList.items.isPlayable` (boolean) - 是否可以在线播放。
- `true`：可以在线播放。
- `false`：无法在线播放。
      - `serverResponse.fileList.items.sliceStartTime` (number) - 该文件的录制开始时间，Unix 时间戳，单位为毫秒。
  - `serverResponse.sliceStartTime` (number) - 录制开始的时间，Unix 时间戳，单位为毫秒。
  - `serverResponse.extensionServiceState` (array)
    - `serverResponse.extensionServiceState.items` (object)
      - `serverResponse.extensionServiceState.items.payload` (object) - 页面录制时会返回如下字段。
        - `serverResponse.extensionServiceState.items.payload.outputs` (array)
          - `serverResponse.extensionServiceState.items.payload.outputs.items` (object)
            - `serverResponse.extensionServiceState.items.payload.outputs.items.rtmpUrl` (string) - CDN 推流地址。
            - `serverResponse.extensionServiceState.items.payload.outputs.items.status` (string) - 页面录制当前的推流状态：
- `"connecting"`：正在连接 CDN 服务器。
- `"publishing"`：正在推流。
- `"onhold"`：暂停推流。
- `"disconnected"`：连接 CDN 服务器失败，声网建议你更换 CDN 推流地址。
        - `serverResponse.extensionServiceState.items.payload.state` (string) - 将订阅内容上传至扩展服务的状态：
- `"init"`：服务正在初始化。
- `"inProgress"`：服务启动完成，正在进行中。
- `"exit"`：服务退出。
        - `serverResponse.extensionServiceState.items.payload.fileList` (array)
          - `serverResponse.extensionServiceState.items.payload.fileList.items` (object)
            - `serverResponse.extensionServiceState.items.payload.fileList.items.filename` (string) - 录制产生的 M3U8 文件和 MP4 文件的文件名。
            - `serverResponse.extensionServiceState.items.payload.fileList.items.sliceStartTime` (number) - 该文件的录制开始时间，Unix 时间戳，单位为毫秒。
        - `serverResponse.extensionServiceState.items.payload.onhold` (boolean) - 页面录制是否处于暂停状态：
- `true`：处于暂停状态。
- `false`：处于运行状态。
      - `serverResponse.extensionServiceState.items.serviceName` (string) - 扩展服务的名称：
- `web_recorder_service`：代表扩展服务为**页面录制**。
- `rtmp_publish_service`：代表扩展服务为**转推页面录制到 CDN**。
- `cname` (string) - 录制的频道名。
- `uid` (string) - 字符串内容为云端录制服务在 RTC 频道内使用的 UID，用于标识频道内的录制服务。
### 非 200

如果 HTTP 状态码不为 `200`，请参考[响应状态码](/zh-CN/realtime-media/cloud-recording/reference/response-code)排查问题。

No schema.

## Response examples

### 200

```json
{
  "resourceId": "云端录制使用的 Resource ID。",
  "sid": "录制 ID。",
  "serverResponse": {
    "status": 0,
    "extensionServiceState": [
      {
        "payload": {
          "fileList": [
            {
              "filename": "录制产生的 M3U8 文件和 MP4 文件的文件名。",
              "sliceStartTime": 0
            }
          ],
          "onhold": true,
          "state": "将订阅内容上传至扩展服务的状态：\n- `\"init\"`：服务正在初始化。\n- `\"inProgress\"`：服务启动完成，正在进行中。\n- `\"exit\"`：服务退出。"
        },
        "serviceName": "扩展服务的名称：\n- `web_recorder_service`：代表扩展服务为**页面录制**。\n- `rtmp_publish_service`：代表扩展服务为**转推页面录制到 CDN**。"
      }
    ]
  },
  "cname": "录制的频道名。",
  "uid": "字符串内容为云端录制服务在 RTC 频道内使用的 UID，用于标识频道内的录制服务。"
}
```