更新指定 Converter
更新时间不可用
在项目中更新指定 Converter 的配置。
https://api.sd-rtn.com/{region}/v1/projects/{appId}/rtmp-converters/{converterId}鉴权
regionstringConverter 所在的区域，必须与创建 Converter 时设置的 region 一致。
appIdstring声网为每个开发者提供的 App ID。在声网控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。
converterIdstringConverter 的 ID。
sequencenumberUpdate 请求的序列号。取值需要大于或等于 0。请确保后一次 Update 请求的序列号大于前一次 Update 请求的序列号。序列号可以确保声网服务器按照你指定的最新配置来更新 Converter。
推荐用法：声网推荐你在第一次调用 Update 时，将 sequence 填 0。在第二次调用 Update 时，将 sequence 填 1。在第三次调用 Update 时，将 sequence 填 2。依次类推。声网服务器会按照最新 Update 请求（即最大的序列号）更新 Converter。
Content-Typestringapplication/json
X-Request-IDstringUUID（通用唯一识别码），标识本次请求。推荐你赋值，赋值后，声网服务器会在响应 Header 中返回一个对应的 X-Custom-Request-ID 字段，你可以用此进行问题排查。如果你不赋值，那么声网服务器会自动生成一个 UUID 并在响应 Header 中返回一个对应的 X-Request-ID 字段。
Update 请求可更新转码推流和不转码推流的 Converter。
注意
Update 不支持更新 Converter 的如下配置：
nameidleTimeOuttranscodeOptions.rtcChanneltranscodeOptions.audioOptions.codecProfiletranscodeOptions.audioOptions.sampleRatetranscodeOptions.audioOptions.bitratetranscodeOptions.audioOptions.audioChannelstranscodeOptions.videoOptions.codectranscodeOptions.videoOptions.codecProfile
转码推流的配置。
Converter 的音频转码配置。
rtcStreamUidsarray<number>指定参与混音的用户 UID。
注意：
- 如果
audioOptions中无该字段，声网将频道内所有用户音频进行混音。 - 如果
audioOptions中存在该字段且值为空，则代表不混合任何用户的音频流。
参与混音的用户音量。
注意：发起 Update 请求更新指定用户音量时，每次请求成功都会将其他用户（非指定用户）的音量恢复成默认音量 100。
rtcStreamUidnumber待设置音量的混音用户 UID。
注意：填入的 UID 需要存在于 rtcStreamUids（参与混音的用户 UID 数组）中，否则请求失败。
volumenumber指定的混音用户的音量。取值范围为 [0,200]。
Converter 的视频转码配置。
视频画布的配置。
widthnumber画布的宽度 (pixel)。取值范围为 [66,1920]。
heightnumber画布的高度 (pixel)。取值范围为 [66,1920]。
colornumber画布的背景色。RGB 颜色值，以十进制数表示。如 255 代表蓝色。取值范围为 [0,16777215]。默认值为 0，即黑色。
画布上各用户的视频画面的配置。
注意
仅需在 layoutType 为自定义布局时设置 layout 字段。
rtcStreamUidnumber用户 UID。
用户视频画面在画布上的显示区域。超出画布的视频画面会被裁剪。
xPosnumber画面在画布上的 x 坐标 (pixel)。以画布左上角为原点，x 坐标为画面左上角相对于原点的横向位移。
yPosnumber画面在画布上的 y 坐标 (pixel)。以画布左上角为原点，y 坐标为画面左上角相对于原点的纵向位移。
zIndexnumber画面的图层编号。取值范围为 [0,100]。0 代表最下层的图层。100 代表最上层的图层。
widthnumber画面的宽度 (pixel)。
heightnumber画面的高度 (pixel)。
placeholderImageUrlstring用户画面的背景图 URL 地址。支持 JPG、PNG 和 GIF 格式的图片。当频道内用户停止发布视频流，如果设置了该字段，用户的视频画面将切换为该背景图，否则会显示为画布背景色。
alphanumber透明度。0.0 代表完全透明，1.0 代表完全不透明。
画布上视频图片的配置。画布上视频图片可充当水印。
注意
仅需在 layoutType 为自定义布局时设置 layout 字段。
imageUrlstring图片的 URL，以 http 或 https 开头。支持 JPG 和 PNG 格式的图片。
图片在画布上的显示区域。超出画布的图片会被裁剪。
xPosnumber图片在画布上的 x 坐标 (pixel)。以画布左上角为原点，x 坐标为图片左上角相对于原点的横向位移。
yPosnumber图片在画布上的 y 坐标 (pixel)。以画布左上角为原点，y 坐标为图片左上角相对于原点的纵向位移。
zIndexnumber图片的图层编号。取值范围为 [0,100]。0 代表最下层的图层。100 代表最上层的图层。
widthnumber图片的宽度 (pixel)。
heightnumber图片的高度 (pixel)。
alphanumber透明度。0.0 代表完全透明，1.0 代表完全不透明。
defaultPlaceholderImageUrlstring默认的用户画面背景图 URL 地址。支持 JPG、PNG 和 GIF 格式的图片。当频道内用户停止发布视频流时，背景图的行为如下：
- 如果设置了该字段，用户的视频画面将切换为该背景图。
- 如果未设置该字段，用户的视频画面先显示为该用户视频最后一帧，布局刷新后显示为画布背景色。
bitratenumber输出视频的编码码率 (Kbps)。取值范围为 [1,10000]。推荐取值详见常用视频属性。
frameRatenumber输出视频的编码帧率 (fps)。取值范围为 [1,30]。推荐取值详见常用视频属性。
gopnumber输出视频的 GOP。默认值为 framerate 的 2 倍。
设置携带的用户 SEI（Supplemental Enhancement Information）信息。默认为空。不设置则不携带用户 SEI 信息。
设置 SEI 信息的数据来源。默认为空。
metadataboolean是否传入 Metadata 类型的 SEI 信息。
true：传入。false：不传入。
datastreamboolean是否传入 Datastream 类型的 SEI 信息。
true：传入。false：不传入。
prefixForAgoraSeistring自定义 SEI 信息的 payload 前缀。长度必须在 32 个字符以内。默认为空。
payloadstring自定义 SEI 信息的 payload。长度必须在 4096 个字符以内。默认为空。
自定义 SEI 信息会被转换为声网 SEI 规范的 SEI 信息。此处设置的 payload 会被转换至声网 SEI 规范中定义的 app_data 中。
设置输出的 SEI 信息。默认为空。
typenumber输出 SEI 信息的 payload 的 type。
rtmpUrlstringCDN 推流地址。必须为有效的 RTMP 地址，且长度在 1024 个字符以内。如果你从 OBS 推流更换为旁路推流，需要按照 {server}/{stream_key} 的规则来拼接 RTMP URL。
jitterBufferSizeMsnumber音频接收端到网络抖动缓冲端的网络延迟 (ms)。取值范围 [0,1000]。旁路推流服务会根据你设置的值，以 100 为单位向上取整。
注意：声网建议你不要设为 0。设为 0 表示不使用抖动缓冲延迟，弱网情况下可能导致音画质量问题，
fieldsstringJSON 编码方式的字段掩码，详见谷歌 protobuf FieldMask 文档。用于描述更新的 converter object 中包含的字段集合。
示例：
{
"converter": {
"rtmpUrl": "rtmp://example.agora.io/live/show68_backup"
},
"fields": "rtmpUrl"
}
在本示例中，fields 描述 converter object 中更新 rtmpUrl 字段。
注意：更新多个字段时，fields 中填写的各字段必须用英文逗号分隔，且逗号后无空格。例如，"fields": "a,b"。
rtmpUrlstringCDN 推流地址。必须为有效的 RTMP 地址，且长度在 1024 个字符以内。如果你从 OBS 推流更换为旁路推流，需要按照 {server}/{stream_key} 的规则来拼接 RTMP URL。
fieldsstringJSON 编码方式的字段掩码，详见谷歌 protobuf FieldMask 文档。用于描述更新的 converter object 中包含的字段集合。
示例：
{
"converter": {
"rtmpUrl": "rtmp://example.agora.io/live/show68_backup"
},
"fields": "rtmpUrl"
}
在本示例中，fields 描述 converter object 中更新 rtmpUrl 字段。
注意：更新多个字段时，fields 中填写的各字段必须用英文逗号分隔，且逗号后无空格。例如，"fields": "a,b"。
响应
如果状态码为 2XX，请求成功。
响应 Header
响应 Body
idstringConverter 的 ID，是声网服务器生成的一个 UUID（通用唯一识别码），标识一个已创建的 Converter。
createTsstring创建 Converter 时的 Unix 时间戳（秒）。
updateTsstring最近一次更新 Converter 配置时的 Unix 时间戳（秒）。
statestringConverter 的运行状态：
"connecting": 正在连接声网推流服务器和 CDN 服务器。"running": 正在进行推流。"failed": 推流失败。
fieldsstringJSON 编码方式的字段掩码，详见谷歌 protobuf FieldMask 文档。用于描述返回的 converter object 中包含的字段集合。
示例：
{
"converter": {
"id": "4c014467d647bb87b60b719f6fa57686",
"createTs": 1591786766,
"updateTs": 1591788746,
"state": "running"
},
"fields": "id,createTs,updateTs,state"
}
在本示例中，fields 描述返回的 converter object 中包含 id、createTs、updateTs、state 字段。
请求示例
curl --request PATCH \
--url "https://api.sd-rtn.com/:region/v1/projects/:appId/rtmp-converters/:converterId" \
--header 'Authorization: Basic <credentials>' \
--header 'X-Request-ID: <string>' \
-H 'Content-Type: application/json' \
-d '{
"converter": {
"rtmpUrl": "rtmp://example.agora.io/live/show68_backup"
},
"fields": "rtmpUrl"
}'响应示例
{
"converter": {
"id": "Converter 的 ID，是声网服务器生成的一个 UUID（通用唯一识别码），标识一个已创建的 Converter。",
"createTs": "创建 Converter 时的 Unix 时间戳（秒）。",
"updateTs": "最近一次更新 Converter 配置时的 Unix 时间戳（秒）。",
"state": "Converter 的运行状态：\n- `\"connecting\"`: 正在连接声网推流服务器和 CDN 服务器。\n- `\"running\"`: 正在进行推流。\n- `\"failed\"`: 推流失败。"
},
"fields": "JSON 编码方式的字段掩码，详见[谷歌 protobuf FieldMask 文档](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask)。用于描述返回的 `converter` object 中包含的字段集合。<p>\n示例：\n```json\n{\n \"converter\": {\n \"id\": \"4c014467d647bb87b60b719f6fa57686\",\n \"createTs\": 1591786766,\n \"updateTs\": 1591788746,\n \"state\": \"running\"\n },\n \"fields\": \"id,createTs,updateTs,state\"\n}\n```\n在本示例中，`fields` 描述返回的 `converter` object 中包含 `id`、`createTs`、`updateTs`、`state` 字段。"
}