文档首页/ 实时音视频 SparkRTC/ API参考/ 合流任务管理/ 修改合流任务

更新时间：2024-10-18 GMT+08:00

修改合流任务

功能介绍

调用此接口更新合流任务布局。

URI

PUT /v2/apps/{app_id}/mix-stream-jobs/{job_id}

表1 路径参数
参数	是否必选	参数类型	描述
app_id	是	String	应用id
job_id	是	String	任务编号

请求参数

表2 请求Header参数
参数	是否必选	参数类型	描述
Content-Type	是	String	内容类型。
X-Auth-Token	否	String	用户Token。使用Token鉴权方式时必选。通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。
Authorization	否	String	使用AK/SK方式认证时必选，携带的鉴权信息。
X-Sdk-Date	否	String	使用AK/SK方式认证时必选，请求的发生时间。
X-Project-Id	否	String	使用AK/SK方式认证时必选，携带项目ID信息。

表3 请求Body参数
参数	是否必选	参数类型	描述
mix_param	是	UpdateMixParam object	合流参数

表4 UpdateMixParam
参数	是否必选	参数类型	描述
layout_template	否	String	视频布局模板编号，仅支持自定义模板之间的更新。
background_image	否	String	画布背景图地址，图片先上传obs。默认使用等比缩放裁剪，保证铺满。格式s3://bucket/object，如：s3://rtc-bucket-cn-north-4/img/testImg.jpg
default_user_background_image	否	String	默认用户背景图地址，图片先上传obs，格式s3://bucket/object，如：s3://rtc-bucket-cn-north-4/img/testImg.jpg。默认使用等比缩放裁剪，保证铺满。
screen_background_image	否	String	共享屏幕的背景图地址，图片先上传obs，格式s3://bucket/object，如：s3://rtc-bucket-cn-north-4/img/testImg.jpg。在一大多小的布局场景下，无论大窗是显示非指定用户（屏幕共享人的桌面）还是指定用户的共享桌面，都通过该字段指定背景图。
max_idle_time	否	Integer	最长空闲频道时间。取值范围：[5，43200]，默认值为30。单位：秒。如果频道内无连麦方的状态持续超过该时间，录制程序会自动退出。退出后，再次调用start请求，会产生新的录制任务。连麦方指：joiner或者publisher的用户。
layout_panes	否	Array of MixLayoutPane objects	需要混流的视频列表。若不需要视频混流，则可不传递该参数。
user_background_images	否	Array of MixUserBackgroundImage objects	指定用户背景图，优先级大于default_user_background_image

表5 MixLayoutPane
参数	是否必选	参数类型	描述
id	否	Integer	窗口id，从1开始编号
user_id	否	String	加入房间的用户id
video_type	否	String	标识视频流的类型，可选摄像头流或者屏幕分享流。 CAMERASTREAM：摄像头视频流 SCREENSTREAM：屏幕分享视频流默认为CAMERASTREAM。
x	否	Float	坐标x，归一化百分比，画布上该画面左上角的横坐标的相对值，范围是 [0.0,1.0]。从左到右布局，0.0在最左端，1.0在最右端，小数取值范围在float内，自定义布局场景下填写本字段。
y	否	Float	坐标y，归一化百分比，画布上该画面左上角的纵坐标的相对值，范围是 [0.0,1.0]。从上到下布局，0.0在最上端，1.0在最下端，小数取值范围在float内，自定义布局场景下填写本字段。
width	否	Float	窗格宽，归一化百分比，小数取值范围在float内，自定义布局场景下填写本字段。
height	否	Float	窗格高，归一化百分比，小数取值范围在float内，自定义布局场景下填写本字段。
zorder	否	Integer	叠放顺序，0为最底层，1层在0层之上，以此类推，最大支持25层，自定义布局场景下填写本字段。
crop_mode	否	String	裁剪模式，自定义布局场景下填写本字段，支持两种模式： KEEP_RATIO_PADDING ：保持比例留边。 KEEP_RATIO_CROP ：保持比例裁剪。
filling_policy	否	String	填充策略，仅限屏幕共享模板(包括screen_share_right、screen_share_left)场景下填写本字段，支持两种模式： FIXED_USER ：固定用户填充。 SHARED_SCREEN ：共享屏幕填充。

表6 MixUserBackgroundImage
参数	是否必选	参数类型	描述
user_id	是	String	需要设置背景图的用户ID
image_uri	是	String	需要设置背景图的地址，图片先上传obs，格式s3://bucket/object，如：s3://rtc-bucket-cn-north-4/img/testImg.jpg

响应参数

状态码： 200

表7 响应Header参数
参数	参数类型	描述
X-request-Id	String	此字段携带请求ID号，以便任务跟踪。

表8 响应Body参数
参数	参数类型	描述
job_id	String	任务编号，可以用于修改、查看和停止合流任务
stream_name	String	流名
app_id	String	应用id
room_id	String	房间id
mix_param	MixParam object	合流参数
record_param	RecordParam object	录制参数
create_time	String	任务创建的时间，形如“2006-01-02T15:04:05.075Z”，时区为：UTC
update_time	String	任务中的布局更新的时间，形如“2006-01-02T15:04:05.075Z”，时区为：UTC
state	String	任务状态。 INIT：任务正在初始化 RUNNING：任务正在运行 STOPPED：任务已停止
stop_reason	String	任务结束原因 TENANT_STOP EXCEED_MAX_IDLE_TIME INTERNAL_ERROR
description	String	状态描述，对state字段的一些补充说明，可用于人工查阅。
start_time	String	任务开始时间，形如“2006-01-02T15:04:05.075Z”，时区为：UTC
stop_time	String	任务结束时间，形如“2006-01-02T15:04:05.075Z”，时区为：UTC

表9 MixParam
参数	参数类型	描述
room_id	String	房间id
encode_template	String	输出编码模板名称 19201080_30_4620：输出流是1080p，帧率30，码率4.62Mbps 19201080_30_3150：输出流是1080p，帧率30，码率3.15Mbps 19201080_15_3460：输出流是1080p，帧率15，码率3.46Mbps 19201080_15_2080：输出流是1080p，帧率15，码率2.08Mbps 1280720_30_3420：输出流是720p，帧率30，码率3.42Mbps 1280720_30_1710：输出流是720p，帧率30，码率1.71Mbps 1280720_15_2260：输出流是720p，帧率15，码率2.26Mbps 1280720_15_1130：输出流是720p，帧率15，码率1.13Mbps 640480_30_1500：输出流是480p，帧率30，码率1.50Mbps 640480_15_500：输出流是480p，帧率15，码率500Kbps 640480_30_1000 输出流是480p，帧率30，码率1000Kbps 480360_30_490：输出流是360p，帧率30，码率490Kbps 480*360_15_320：输出流是360p，帧率15，码率320Kbps
max_idle_time	Integer	最长空闲频道时间。取值范围：[5，43200]，默认值为30。单位：秒。如果频道内无连麦方的状态持续超过该时间，录制程序会自动退出。退出后，再次调用start请求，会产生新的录制任务。连麦方指：joiner或者publisher的用户。
layout_template	String	视频布局模板编号，不混视频的时候，不需要带。 nine_grids_view：九宫格模板（自适应模板） screen_share_left：主视图在左边的屏幕共享模板（自适应模板） screen_share_right：主视图在右边的屏幕共享模板（自适应模板） custom：自定义布局
default_user_background_image	String	默认用户背景图地址，图片先上传obs，格式s3://bucket/object，如：s3://rtc-bucket-cn-north-4/img/testImg.jpg。默认使用等比缩放裁剪，保证铺满。
screen_background_image	String	共享屏幕的背景图地址，图片先上传obs，格式s3://bucket/object，如：s3://rtc-bucket-cn-north-4/img/testImg.jpg。在一大多小的布局场景下，无论大窗是显示非指定用户（屏幕共享人的桌面）还是指定用户的共享桌面，都通过该字段指定背景图。
background_image	String	画布背景图地址，使用背景图功能需先上传图片到obs，填写此字段要求格式为s3://bucket/object，其中bucket和object指图片所在的桶和路径，如：s3://rtc-bucket-cn-north-4/img/testImg.jpg。默认使用等比缩放裁剪，保证铺满。
layout_panes	Array of MixLayoutPane objects	需要混流的视频列表。若不需要混流视频，则可不传递该参数。 nine_grids_view模板不需要填写本字段。
user_background_images	Array of MixUserBackgroundImage objects	指定用户背景图，优先级大于default_user_background_image

**表10** MixLayoutPane
参数	参数类型	描述
id	Integer	窗口id，从1开始编号
user_id	String	加入房间的用户id
video_type	String	标识视频流的类型，可选摄像头流或者屏幕分享流。 CAMERASTREAM：摄像头视频流 SCREENSTREAM：屏幕分享视频流默认为CAMERASTREAM。
x	Float	坐标x，归一化百分比，画布上该画面左上角的横坐标的相对值，范围是 [0.0,1.0]。从左到右布局，0.0在最左端，1.0在最右端，小数取值范围在float内，自定义布局场景下填写本字段。
y	Float	坐标y，归一化百分比，画布上该画面左上角的纵坐标的相对值，范围是 [0.0,1.0]。从上到下布局，0.0在最上端，1.0在最下端，小数取值范围在float内，自定义布局场景下填写本字段。
width	Float	窗格宽，归一化百分比，小数取值范围在float内，自定义布局场景下填写本字段。
height	Float	窗格高，归一化百分比，小数取值范围在float内，自定义布局场景下填写本字段。
zorder	Integer	叠放顺序，0为最底层，1层在0层之上，以此类推，最大支持25层，自定义布局场景下填写本字段。
crop_mode	String	裁剪模式，自定义布局场景下填写本字段，支持两种模式： KEEP_RATIO_PADDING ：保持比例留边。 KEEP_RATIO_CROP ：保持比例裁剪。
filling_policy	String	填充策略，仅限屏幕共享模板(包括screen_share_right、screen_share_left)场景下填写本字段，支持两种模式： FIXED_USER ：固定用户填充。 SHARED_SCREEN ：共享屏幕填充。

**表11** MixUserBackgroundImage
参数	参数类型	描述
user_id	String	需要设置背景图的用户ID
image_uri	String	需要设置背景图的地址，图片先上传obs，格式s3://bucket/object，如：s3://rtc-bucket-cn-north-4/img/testImg.jpg

**表12** RecordParam
参数	参数类型	描述
record_rule_id	String	录制规则id。

状态码： 400

**表13** 响应Header参数
参数	参数类型	描述
X-request-Id	String	此字段携带请求ID号，以便任务跟踪。

**表14** 响应Body参数
参数	参数类型	描述
error_code	String	错误码
error_msg	String	错误描述

状态码： 404

**表15** 响应Header参数
参数	参数类型	描述
X-request-Id	String	此字段携带请求ID号，以便任务跟踪。

**表16** 响应Body参数
参数	参数类型	描述
error_code	String	错误码
error_msg	String	错误描述

状态码： 500

**表17** 响应Header参数
参数	参数类型	描述
X-request-Id	String	此字段携带请求ID号，以便任务跟踪。

**表18** 响应Body参数
参数	参数类型	描述
error_code	String	错误码
error_msg	String	错误描述

请求示例

修改指定应用id和任务编号的合流录制任务，修改后布局为九宫格

PUT https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/mix-stream-jobs/{job_id}

{
  "mix_param" : {
    "layout_template" : "nine_grids_view"
  }
}

响应示例

状态码： 200

修改成功

{
  "job_id" : "607824b4fa163e19fe301cc817dda855",
  "stream_name" : "m_607824b4fa163e19fe301cc817dda855_gigu",
  "app_id" : "123456789abcdefghijklmno",
  "room_id" : "gigu",
  "mix_param" : {
    "room_id" : "gigu",
    "encode_template" : "1920x1080_30_4620",
    "max_idle_time" : 0,
    "layout_template" : "nine_grids_view"
  },
  "record_param" : {
    "record_rule_id" : "5f5e172b9016ed5b0961a43"
  },
  "create_time" : "2021-04-16T16:22:44Z",
  "update_time" : "2021-04-16T16:22:44Z",
  "state" : "INIT",
  "start_time" : "2021-04-16T16:22:44Z",
  "stop_time" : "0001-01-01T00:00:00Z"
}

状态码： 400

修改失败，语义有误，当前请求无法被服务器理解，或参数有误

{
  "error_code" : "RTC.00001003",
  "error_msg" : "InvalidParameterValue"
}

状态码： 404

修改失败，应用不存在

{
  "error_code" : "RTC.00001003",
  "error_msg" : "InvalidParameterValue"
}

状态码： 500

修改失败，服务器错误

{
  "error_code" : "RTC.00002xxx",
  "error_msg" : "InternalError"
}

状态码

状态码	描述
200	修改成功
400	修改失败，语义有误，当前请求无法被服务器理解，或参数有误
404	修改失败，应用不存在
500	修改失败，服务器错误

错误码

请参见错误码。

父主题： 合流任务管理

上一篇：查询合流任务

下一篇：停止合流任务

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消