You need to enable JavaScript to run this app.
导航

查询单流转推任务状态 GetPushSingleStreamToCDNTask

最近更新时间2024.01.12 17:07:37

首次发布时间2023.10.31 17:39:58

本文档 API 接口为最新版本接口,后续相关功能的新增都会在此更新,推荐使用最新版本接口。旧版接口文档请参考历史版本
你可以使用此接口查询指定单流转推任务的相关信息。

使用说明

接口行为

你可以调用GetPushSingleStreamToCDNTask接口,指定你所属的 AppId,查询指定 RoomId 下的单流任务。

你可以查询由客户端或服务端发起的单流转推任务,但返回的参数结构均为服务端的参数结构。

通过此接口仅能查询距今 72 小时内开始的单流转推任务。

前置条件

在查询前,你必须已经在控制台上开通转推直播服务。

调用接口

关于调用接口的请求结构、公共参数、签名算法和返回结构,参看调用方法

注意事项

请求频率:QPS 不得超过 60。

请求说明

  • 请求方式:GET
  • 请求地址:https://rtc.volcengineapi.com?Action=GetPushSingleStreamToCDNTask&Version=2023-06-01

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数

Query

参数类型是否必选示例值描述
ActionStringGetPushSingleStreamToCDNTask接口名称。当前 API 的名称为 GetPushSingleStreamToCDNTask
VersionString2023-06-01接口版本。当前 API 的版本为 2023-06-01
AppIdStringYour_AppId你的音视频应用的唯一标志
RoomIdStringYour_RoomId房间的 ID,是房间的唯一标志

TaskId

String

Your_TaskId

要查询的转推直播任务 ID。通过服务端发起时,该值为调用 OpenAPI 时传入的 TaskId。通过客户端 SDK 发起时,TaskId 是按照 userId@@taskId 格式拼接而成的字符串;当传入的 taskId 为空时,这里的 TaskId 为 userId
TaskId 和 UserId 均为非必填参数,但是你需要至少填一个参数以保证可以正常发起请求。

UserId

String

Your_UserId

客户端发起转推任务的用户 ID。
你在客户端发起多个任务,当使用该接口进行查询时:

  • 查询第一个任务时,UserId 可以传入发起转推任务的用户 UserIdTaskId 传入空字符串;或直接将该用户的 UserId 传入 TaskId
  • 查询第二个以上任务时,UserIdTaskId 为发起转推任务的用户 UserIdTaskId

返回参数

下表仅列出本接口特有的返回参数,公共返回参数请参见返回结构

参数类型示例值描述
PushSingleStreamToCDNTaskObject of PushSingleStreamToCDNTask-单流转推任务信息

PushSingleStreamToCDNTask

参数类型示例值描述
StartTimeLong1677205841000任务开始时间戳,Unix 时间,单位为毫秒
EndTimeLong1677205914000任务结束时间戳,Unix 时间,单位为毫秒。0 表示任务未结束

Status

Long

3

任务状态。

  • 0: 未知异常状态
  • 1: 未开始
  • 2: 运行中
  • 3: 已结束
  • 4: 任务运行失败

StopReason

String

StopByAPI

任务停止的原因

  • 返回为空:表示任务未结束
  • UnknownStopReason:未知停止原因
  • StopByAPI:用户主动调用 服务端 OpenAPI 停止
  • StartTaskFailed:任务启动失败
  • IdleTimeOut:任务超过最大空闲时间
  • UserDisconnect:客户端用户主动退房/调用停止转推接口

PushStreamState

Integer

6

推流状态

  • 0:未获取到任务状态。建议稍后重新查询
  • 1:未开始推流
  • 2:首次连接 CDN 服务
  • 3:正在重连 CDN 服务
  • 4:连接 CDN 服务成功,正在尝试推流。
  • 5:连接 CDN 服务成功,推流成功
  • 6:已停止推流。
    仅当Status=2 时,PushStreamState 有实际意义;当Status=3 时,PushStreamState=6; status 为其他值时,PushStreamState 均为0
StreamObject of SingleStream房间内转推的流
PushURLStringrtmp://xxxxx推流地址。目前仅支持 rtmp 协议
ControlObject of SingleControl配置选项

SingleStream

参数类型示例值描述
UserIdString Your_UserId用户Id,表示这个流所属的用户。
StreamTypeInteger0流的类型,值可以取01,默认值为00表示普通音视频流,1表示屏幕流。

SingleControl

参数类型示例值描述
MediaTypeInteger0流的类型,用于全局控制订阅的流的类型。默认值为 0,可以取010表示音视频,1表示纯音频,暂不支持纯视频。值不合法时,自动调整为默认值。
MaxIdleTimeInteger180任务的空闲超时时间,超过此时间后,任务自动终止。单位为秒。取值范围为 [10, 86400], 默认值为 180

请求示例

GET https://rtc.volcengineapi.com?Action=GetPushSingleStreamToCDNTask&Version=2023-06-01&AppId=Your_AppId&RoomId=Your_RoomId&TaskId=Your_TaskId&UserId=Your_UserId

返回示例

{
    "Result": {
        "PushSingleStreamToCDNTask": {
            "StartTime": 1677205841000,
            "EndTime": 1677205914000,
            "Status": 3,
            "StopReason": "StopByAPI",
            "PushStreamState": "6",
            "PushURL": "rtmp://xxxxx",
            "Stream": {
                "Index": 0,
                "UserId": "user1",
                "StreamType": 1
            },
            "Control": {
                "MediaType": 1,
                "MaxIdleTime": 180
            }
        }
    },
    "ResponseMetadata": {
        "RequestId": "Your_RequestId",
        "Action": "GetPushSingleStreamToCDNTask",
        "Version": "2023-06-01",
        "Service": "rtc",
        "Region": "cn-north-1"
    }
}

错误码

您可访问公共错误码,获取更多错误码信息。