场景模板配置

更新时间：2025-04-15 17:17

1 描述

Express 支持自定义场景模版配置，用于登录到对应配置的场景。当系统预置的配置模板无法满足您的业务需求时，您可以通过该服务端 API 创建自定义模板，设置相关参数。

自定义模板上限为 50，如果您需要更多的模板数量，请联系 ZEGO 技术支持。

2 接口原型

请求方法：GET
请求地址：metaworld-api.zego.im
Action：SetSceneTemplate
传输协议：HTTPS
调用频率限制：50

3 请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表请参考调用方式中的 “2.1 公共请求参数”。

测试环境下（详见调用方式中的 “2 公共参数” 中的 IsTest 的参数说明），流 ID 需要加上 “zegotest-AppId-” 前缀。例如，流 ID 为 “test”，在 AppId 为 “123456789” 的测试环境下，流 ID 应为 “zegotest-123456789-test”。

参数	类型	是否必选	描述
AppId	Number	是	应用 AppID
TemplateId	Number	是	模板 ID
LeftBottomX	Number	否	地图左下角横坐标（见下图）
LeftBottomZ	Number	否	地图左下角纵坐标（见下图）
RightUpX	Number	否	地图右上角横坐标（见下图）
RightUpZ	Number	否	地图右上角纵坐标（见下图）
MaxUserNum	Number	是	场景人数上限无限制，达到上限后，后续用户将登录失败
ViewRadius	Number	是	AOI 半径（用户视野半径）
MaxVisibleNum	Number	是	AOI 人数上限本端用户的AOI范围内，可视远端用户数的上限，人数上限最多 100

                        -------------------------------------------(RightUpX, RightUpZ)
                        |                                       |
                        |                                       |
                        |                                       |
                        |                                       |
                        |                                       |                                                            
(LeftBottomX, LeftBottomZ)------------------------------------------

模板配置更改后，正在使用该模板的场景不会立刻生效，需等待场景销毁后（场景中全部用户退出 10 分钟后，该场景会被自动销毁），重新创建才可生效。

4 请求示例

https://metaworld-api.zego.im/?Action=SetSceneTemplate&SignatureNonce=8cb67a4cd41df5dc&Timestamp=1670576924&Signature=a6da407f29dfab00c6aed21979634df8&SignatureVersion=2.0&IsTest=true&AppId=111111111&TemplateId=10080&ViewRadius=3&MaxUserNum=50000&MaxVisibleNum=50&MaxItemNum=100&MaxVisibleItemNum=10&MaxBindItemNum=3&MaxItemCapacity=5&LeftBottomX=0.00&LeftBottomZ=0.00&RightUpX=500.00&RightUpZ=500.00

5 响应参数

参数	类型	描述
Code	Number	错误码
Message	String	错误信息描述
RequestId	String	请求 ID
Data	Object	返回数据内容

6 响应示例

{
    "Code": 0,
    "Message": "succeed",
    "RequestId": "9f674801-69e9-463f-a966-1ba2c6b5dbbe",
    "Data": null
}

7 返回码

以下仅列出了常见的接口业务逻辑相关的返回码，完整返回码请参考全局返回码。

返回码	说明	处理建议
340004003	模版已存在。	设置其他模版 ID。
340006003	参数错误。	根据错误提示设置正确的请求参数。