概述
- GM接口，是用于实现游戏管理相关功能的工具接口。通过开发及配置GM接口，可以快速实现业务需求对接，完成数据交互：研运人员可以自助完成游戏信息查询，游戏服、礼包、公告、邮件等维护操作，聊天监控、禁言、封号等游戏行为规范，提升游戏运营效率和用户体验。
- 目前提供预置接口，将常用的GM工具标准化，便于研发对接及发行使用；提供自定义接口，支持游戏自助配置个性化GM功能，以响应不同游戏的设计及管理需求。
- 本文旨在指导用户完成GM接口配置，涵盖从基础信息填写到接口上线调试的全过程。通过规范化的参数配置和调试验证，确保接口功能与业务需求高度匹配。
使用前提
- 请先通过 GM系统使用手册 或 悬浮查看“GM接口管理”页中各接口的应用场景说明，了解所需功能的关联GM接口，而后按照 GM接口对接文档 开发对应GM接口。
- “GM接口管理”页顶部列出了来源IP，在使用GM接口时，会从这些服务器发起请求至接入方服务器，请将所列IP加入到接入方IP白名单，以确保收到合法请求。
配置入口
- GM接口管理访问路径：登录星云开放平台 → 游戏中心 → 选择游戏 → 对接中心 → GM接口管理
- 星云预置了30多个GM接口，涉及游戏服管理、角色信息查询、客服工单处理进度推送、道具信息查询、公告发送、邮件发送、禁言、封号等常用功能，请于预置接口列表选择所需接口点击“修改”开始对应预置接口配置。
- 其中，游戏服、渠道、道具等通用接口若完成配置并上线，其余接口引用到对应参数将自动填充对应信息——
- “同步星云游戏服变更信息”及“获取游戏当前可用的游戏服列表”：均用于游戏服获取及展示，前者为在星云的 GM系统→操作工具→游戏服管理 中维护游戏服信息而后同步给游戏，后者为直接获取游戏自行构建的游戏服信息，二者二选一即可；任一已配置上线，则GM系统中的其余功能，若需使用游戏服信息，将默认填充此接口作为游戏服数据源。
- “获取游戏当前可用的渠道列表”：若已对接 星云聚合渠道SDK、已进行 对接中心-渠道打包-渠道配置，则无需配置此接口（即二者二选一即可）；若此接口已配置上线，则GM系统中的所有功能，若需使用渠道信息，将默认填充此接口作为渠道数据源。
- “获取道具名称列表”：若此接口已配置上线，则GM系统中的所有功能，若需使用道具信息，将默认填充此接口作为道具数据源。
- 其中，游戏服、渠道、道具等通用接口若完成配置并上线，其余接口引用到对应参数将自动填充对应信息——
- 若预置接口无法满足所需实现的业务需求，可切换至自定义接口列表，点击“添加自定义接口”或“修改”开始对应自定义接口配置。
配置流程
基础信息
- 接口描述：接口标题或用途说明，预置接口此处不可编辑。
- 接口类型：支持查询、操作接口类型，预置接口此处不可编辑。
- 请求方式：支持GET、POST请求方式，预置接口此处不可编辑。
- 支持分页：仅查询接口有此配置，用于支撑数据请求时是否分页；开启分页则默认预置“per_page”、“page”参数；预置接口此处不可编辑。
- 而GM系统功能界面，无论“支持分页”是开启或关闭，基于用户体验考虑，将针对大于10条的返回结果默认提供翻页功能。
- 接口地址：
不允许添加url参数，若需使用请于“请求参数”中添加类型为“固定值”的参数以实现。
- 分组：仅自定义接口有此配置，用于 “GM系统 → 自定义功能” 的子菜单显示；若部分自定义接口期望归集于同一菜单显示，则选择同一分组即可；例，排行榜查询、排行榜黑名单 计划统一归类为 排行榜管理，则创建“排行榜管理”分组并将这几个接口均选中此分组即可。
- 分组管理，支持 添加、修改、删除、旗下接口转组；其中，预置的“默认”分组不支持删除（但支持改名）。
- 在“分组管理”列表中未删除且旗下有接口的分组，将在“星云开放平台 → 企业管理 → 成员与权限 → 用户组管理” 中作为GM系统的“自定义功能权限”供用户组授权及对应用户组菜单显示。
- 分组管理，支持 添加、修改、删除、旗下接口转组；其中，预置的“默认”分组不支持删除（但支持改名）。
请求参数
- 请求参数包含 参数名、参数显示名、参数注释、是否必填、参数类型、控件类型、控件详情 的配置。
- 参数名：接口请求所需的参数名称，例“title”。
- 参数显示名：参数显示于功能界面（如GM系统对应操作表单）中的字段名称，例“公告标题”。
- 参数注释：参数显示于功能界面（如GM系统对应操作表单）中的虚拟提示，可用于提示输入规则等，例“最多可输入40个字”。
- 是否必填：判断请求接口时参数是否必传、对应功能界面生成表单时字段是否必填。
特殊，因预置接口可能关联其他业务（如礼包码等），请务必在游戏服务端放开请求参数的必填限制。
- 参数类型：支持固定值、字符串、数字、数组、时间控件参数类型。
- 控件类型&控件详情
- 固定值
- 不显示于功能界面中；因接口地址不允许添加url参数，若需使用可通过添加“固定值”的参数以实现。
- 时间控件
- 查询接口，可选精确到天或分钟的多天时间控件。
- 操作接口，可选精确到天或分钟的单天时间控件；若操作表单需设置一个时段，需添加两个使用时间控件的参数。
- 字符串&数字
- 可根据交互需求选择文本输入类或下拉选择类控件。
- 若使用选择框，需选择枚举值获取数据源；数据源将从星云预置数据源及所有查询接口中选择，若无匹配数据源，请先于“自定义接口”中添加所需的查询接口并“上线”；
接口必须返回对象列表，且对象包含id、name参数。 - 若使用富文本编辑器，可设置编辑器支持的样式，如 文字加粗、文字颜色、图片上传、链接插入等，全部未选则界面效果同多行文本框。
- 若使用批量处理框，无需维护枚举值获取数据源，将于GM功能界面中出现批处理文本框，支持用户手动输入或上传附件填充内容。
- 数组
- 当参数的请求内容可能包含多个值时，需使用“数组”类型。
- 查询接口仅支持多选下拉框控件，操作接口除了多选下拉框，还支持批量处理框控件。
- 若使用选择框，需选择枚举值获取数据源；数据源将从星云预置数据源及所有查询接口中选择，若无匹配数据源，请先于“自定义接口”中添加所需的查询接口并“上线”；
接口必须返回对象列表，且对象包含id、name参数。 - 若使用批量处理框，无需维护枚举值获取数据源，将于GM功能界面中出现批处理文本框，支持用户手动输入或上传附件填充内容。
- 固定值
- 为了保障业务功能正常使用，预置接口预置了部分请求参数，此类参数仅“参数注释”、“是否必填”、控件详情“其他”支持编辑。
- 除了预置参数外，支持通过“添加参数”添加各游戏接口所需的自定义请求参数。
- 若需调整参数顺序，可通过“参数排序”完成。
- 若存在多个请求参数需至少必填一项才可提交的情况，可通过“提交设置”设置。
返回参数
- 仅查询接口支持配置返回参数，若未配置，则功能界面将全量展示接口返回的参数；返回参数包含 参数名、参数显示名、是否显示 的配置。
- 参数名：接口返回携带的参数名称，例“pid”。
- 参数显示名：参数显示于功能界面查询结果中的字段名称，例“角色ID”。
- 是否显示：判断对应功能界面查询结果中此字段是否显示。
- 为了保障业务功能正常使用，预置接口预置了部分返回参数，此类参数仅“是否显示”支持编辑。
- 除了预置参数外，支持通过“添加参数”或“导入参数”添加各游戏接口所需的自定义返回参数。
- 推荐先进行“在线调试”，调试成功的“响应结果”可自动导入返回参数。
- 若需手动“导入参数”，可依据示例输入返回参数的JSON信息 或 选择近15天调试成功的记录 完成返回参数的信息填充。
- 若需调整参数顺序，可通过“参数排序”完成。
在线调试
- 如果您已完成接口的基本信息及请求参数配置，接下来请进行“在线调试”。
- 调试器将根据所配置的接口地址及请求参数生成入参表单，故请确保接口地址及请求参数配置完整。
- 针对预置接口，星云将默认填充示例数据以提升调试效率。其中，选择类参数，不会直接展示已配置的数据源，请通过增删所需使用的枚举值完成输入。
- 针对查询接口，调试成功的“响应结果”可一键导入“返回参数”，故返回参数配置前推荐先进行“在线调试”。
- 发起调试，将通过接口发送请求等同于真实操作。调试结果将于右侧面板即时反馈，包含：调试结果、http状态码、请求耗时、失败原因、响应结果、响应报文、请求报文等。
- 调试历史，仅罗列最近15天的调试记录。点击调试记录，可查看当时的调试详情；点击“填入调试参数”，可将所选记录当时的入参内容快速填充至“输入参数”以便发起调试。
上线&存草稿
- 接口信息配置完成后，支持直接上线或存草稿。
- 接口需正确配置并“上线”后才可于GM系统等对应业务功能中使用。
- 存草稿不会影响当前接口的状态及线上业务功能的使用。
- 上线，将进行接口最新配置信息是否调试成功的校验；若调试成功或继续上线，将列出配置信息供确认；若接口曾经上线，将列出最近上线的正式配置及最后修改的配置，供信息对比。
- 若接口曾经上线且最后进行了“存草稿”：则于列表查看时，将列出最近上线的正式配置及最后修改的草稿配置，供信息对比；修改时，可选基于哪份配置信息进行修改。
其他
- 支持于接口列表查看配置信息、上线接口、下线接口、修改接口；其中，自定义接口还支持删除接口、分组管理。
- 已上线的预置接口，将应用于GM系统、客服系统、充值服务中，具体应用场景详见预置接口列表中各接口的悬浮说明。
- 已上线的自定义接口，将应用于 “星云开放平台 → 游戏中心 → 选择游戏 → GM系统 → 自定义功能”。