预置接口

文章目录

修订记录

文档版本 更新日期 更新内容
1.1.5 2024.06.21 发送角色邮件接口，新增服务器id字段
1.1.4 2024.06.17 发送角色邮件接口，字段source新增类型 3微信礼包，字段exchange_id 由int类型改为string类型
1.1.3 2024.03.26 增加“获取游戏服准入白名单”接口
1.1.2 2024.01.31 1 “发送富文本公告”接口支持分批发送功能，增加is_del参数
2 “发送跑马灯公告”接口支持分批发送功能，增加is_del参数
3 “发送全服邮件”接口支持分批发送功能，增加渠道channel_id_list、end_time和batch_id参数，同步返回字段和异步“发送全服邮件回调”把sid修改为item_id，表示游戏服ID或者渠道ID
4 “发送角色邮件”接口支持分批发送功能，增加end_time和batch_id参数
5 对请求参数说明进行补充
1.1.1 2023.12.11 增加“网页直充创建订单”接口
1.1.0 2023.11.21 1 增加“获取游戏服变更信息”、“获取道具名称列表”、“道具删除”、“发送富文本公告”、“发送跑马灯公告”、“删除公告”、“发送全服邮件”、“发送角色邮件”和“撤回邮件”预置接口
2 获取角色信息接口增加返回server_id、channel_id和vip_level参数
1.0.2 2021.10.29 GM接口参数说明
1.0.0 2020.01.01 初始化

全局说明

  1. 系统使用手册 ，了解功能的使用和配置，了解某个功能依赖哪些GM接口

  2. GM接口是接入方需要按照此文档开发出对应的接口，并在“对接中心->GM接口管理”将接口配置好，便可在“GM系统”使用标准化的GM工具

  3. 接口IP白名单限制：前往“对接中心-GM接口管理”查看来源IP列表，在使用GM接口时，会从这些服务器发起请求到接入方服务器，请把以下IP加入到接入方IP白名单，以确保收到合法请求
    file

  4. 所有的GM接口（星云调用接入方）使用App Key签名规则

    • 所有GM接口请求时会带上ts和sig这2个签名参数，get请求放在url中，post放在body中，需要对sig参数进行校验，ts也可自行进行校验，比如设置有效期为5分钟内等策略。后面请求参数就不再赘述这2个参数。这2个参数也不需要在“对接中心-GM接口管理”的请求参数中进行配置
    • 参数名 类型 长度 说明 是否必传
      ts int 11 时间戳 是
      sig string 32 签名 是
    • 示例
      file

  5. 游戏服、渠道、道具等通用接口若完成配置并上线，在对其余"未配置"状态的接口配置编辑时，会默认把游戏服、渠道、道具接口的url进行填充。注：仅针对"未配置"状态的接口生效

请求参数说明

  1. 接口参数控件类型为下拉框的说明
    file

    • 需要填写下拉框数据源获取地址，HTTP 请求方式为GET，返回的参数为固定的id和name，表示id和名称。
    • 请求参数名 类型 长度 说明 是否必传
      ts int 11 时间戳 是
      sig string 32 签名 是
    • 返回参数名 类型 长度 说明 是否必传
      id string 32 id 是
      name string 50 名称 是

  1. "per_page"和"page"用于支持查询结果的分页

  2. "ts"和"sig"字段会在请求gm接口时带上，用于签名校验

  3. 如需要增加请求参数，通用命名尽量统一，使用以下参数例：

    • 请求参数 命名
      当前分页 page
      每页展示数 per_page
      用户账号唯一标识OpenID open_id
      服务器id sid
      玩家id pid
      渠道id channel_id

  4. 若新增参数需设置游戏服字段，枚举获取地址可填入__NEBULA_SERVER__，即可使用“GM系统-操作工具-游戏服管理”维护的游戏服信息

  5. 若新增参数需设置渠道字段，枚举获取地址可填入__NEBULA_CHANNEL__，即可使用“对接中心-渠道打包-渠道配置”的配置完成和启用的渠道

  6. 富文本字段说明：统一json格式，insert插入内容，attributes对插入内容配置加粗、链接、颜色等。发送富文本公告、发送全服邮件和发送角色邮件会使用到富文本。注：换行符都是单独一行，不会在文本中

    {
"version": "v1",
"ops": [
{ "insert": "普通文本"},
{ "insert": "文本加粗", "attributes": { "bold": true } },
{ "insert": "文本颜色", "attributes": { "color": "#e60000" } },
{ "insert": "超链接", "attributes": { "link": "url地址" } },
{ 
    "insert": "超链接文本加粗和颜色设置组合使用",
    "attributes": { "bold": true, "color": "#e60000","copy":true, "link": "https://nebula.737.com/home3" } 
},
{ "insert": "\n" },
{ "insert": {"image": "https://nebula.737.com/home3/favicon.ico" } }]
}
    • 富文本效果示例
      file

  7. 由于目前暂不支持在“对接中心-GM接口”的请求参数中配置固定参数，如果需要增加固定的请求参数，可以在接口地址URL?后进行配置。（注：不要添加和请求参数一样的参数，或者ts、sig、page、per_page这些系统参数）

    • GET请求时，合并url固定的请求参数+配置请求参数作为整合请求参数，对整合请求参数进行签名处理，整合请求参数作为最后请求参数
      file
      发起的请求是：curl 'https://baidu.com/v1/gm/channelList?type=1&sid=s1&ts=1535198961&sig=0bebc8ef5313b9f9b73194e138a6ee50'
    • POST请求时，合并url固定的请求参数+配置Body请求参数作为整合Body请求参数，然后对整合Body请求参数进行签名处理，整合Body请求参数作为最后Body请求参数，去除请求地址URL?后的固定参数作为最后请求地址
      file
      发起的请求是：curl -X POST -d 'type=1&sid=s1&pid=p1&day=1&ts=1535198961&sig=0bebc8ef5313b9f9b73194e138a6ee50' https://baidu.com/v1/gm/forbiddenWords

返回结果说明

  1. 所有接口都以json格式返回，包含以下字段
参数名 说明 是否必传
status 状态，成功填1 ， 失败填其他数字 是
msg 信息，成功填ok，失败填写具体原因 是
errno 错误码（失败时为必填项（填写0以外的数字），成功可传可不传（传填0）） 否
data 数据 否
  1. 响应示例：
{
    "status":1,
    "msg":"success",
    "data":[
        {
            "id":"1",
            "name":"区服1"
        },
        {
            "id":"2",
            "name":"区服2"
        }
    ]
}

GM接口列表

1. 获取游戏服变更信息

1.1 说明
  • 运用于 GM系统-操作工具-游戏服管理，游戏研发可通过此接口获取于星云管理的游戏服信息
  • 若此接口已配置上线，则GM系统中的所有功能，若需使用游戏服信息，将自动使用 “游戏服管理”中的游戏服信息
  • 此接口与“获取游戏当前可用的游戏服列表”接口二选一即可，若已配置上线后者，则无需配置此接口
1.2 请求方式
  • POST
1.3 请求参数
  {
    "list":[
        {
            "is_del":0,
            "sid":"aaaaaa",
            "name":"221121",
            "server_char":"集群标识",
            "display_time":"2023-10-01 10:00:00",
            "open_time":"2023-10-01 10:00:00",
            "channel_id_list":[
                "1",
                "2"
            ],
            "tag":1,
            "use_status":1,
            "maintain_status":1,
            "deploy_status":1,
            "create_time":"2023-10-01 10:00:00",
            "update_time":"2023-10-01 10:00:00"
              },
        {
            "is_del":0,
            "sid":"bbbb",
            "name":"221121",
            "server_char":"集群标识",
            "display_time":"2023-10-01 10:00:00",
            "open_time":"2023-10-01 10:00:00",
            "channel_id_list":[
                "1",
                "2"
            ],
            "tag":"新服",
            "use_status":1,
            "maintain_status":1,
            "deploy_status":1,
            "create_time":"2023-10-01 10:00:00",
            "update_time":"2023-10-01 10:00:00"  
          }
    ],
}
参数名 类型 长度 说明 是否必传
list string，json格式 - 服务器列表 是
list.is_del int 1 默认0，1表示删除 是
list.sid string 32 游戏服id 是
list.name string 50 游戏服名称 是
list.server_char string 32 集群标识 是
list.display_time string - 对外展示时间，格式YYYY-MM-DD hh:mm:ss 是
list.open_time string - 开服时间，格式YYYY-MM-DD hh:mm:ss 是
list.channel_id_list array - 渠道id列表 是
list.tag int 1 标签，1正常 2新服 3爆满 4推荐 是
list.use_status int 1 使用状态，1启用 2停新 3停用 是
list.maintain_status int 1 维护状态，1正常 2维护 是
list.deploy_status int 1 部署状态，1未部署 2变更中 3已部署 是
list.create_time string - 创建时间，格式YYYY-MM-DD hh:mm:ss 是
list.update_time string - 更新时间，格式YYYY-MM-DD hh:mm:ss 是
1.4 返回参数
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":{

    }
}

2. 获取游戏当前可用的游戏服列表

2.1 说明
  • 此接口与“获取游戏服变更信息”接口二选一即可，若已对接 GM系统-操作工具-游戏服管理，则无需配置此接口
  • 若此接口已配置上线，则玩家于SDK登录后进入游戏前访问C端客服中心时，可通过此接口选择游戏服
  • GM系统-操作工具 中的所有功能，若需使用游戏服信息，将自动同步此接口信息
2.2 请求方式
  • GET
2.3 请求参数
2.4 返回参数
参数名 类型 长度 说明 是否必传
id string 32 游戏服id 是
name string 50 游戏服名称 是
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":[
        {
            "id":"1",
            "name":"name1"
        },
        {
            "id":"2",
            "name":"name2"
        }
    ]
}

3. 获取游戏当前可用的渠道列表

3.1 说明
  • 若已对接 聚合渠道SDK、已进行 对接中心-渠道打包-渠道配置，则无需配置此接口
  • 若此接口已配置上线，则GM系统-操作工具 中的所有功能，若需使用渠道信息，将自动同步此接口信息
3.2 请求方式
  • GET
3.3 请求参数
3.4 返回参数
参数名 类型 长度 说明 是否必传
id string 32 渠道id 是
name string 50 渠道名称 是
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":[
        {
            "id":"1",
            "name":"name1"
        },
        {
            "id":"2",
            "name":"name2"
        }
    ]
}

4. 获取角色信息（按创角时间降序）

4.1 说明
  • 运用于 GM系统-信息查询-角色信息查询
4.2 请求方式
  • GET
4.3 请求参数
参数名 类型 长度 说明 是否必传
per_page int 11 每页显示条数 是
page int 11 页码 是
pname string 50 角色名称，支持模糊搜索 否
pid string 50 角色ID 否
open_id string 50 用户OpenID 否
did string 32 创角设备id 否
ip string 32 创角ip 否
4.4 返回参数
参数名 类型 长度 说明 是否必传
data.total int 11 总记录数 是
data.list array 1000 玩家信息列表 是
data.list.server_id string 32 游戏服ID 是
data.list.server_name string 50 游戏服名称 是
data.list.channel_id string 32 渠道ID 是
data.list.channel_name string 50 渠道名称 是
data.list.open_id string 32 用户OpenID 是
data.list.pid string 32 角色id 是
data.list.pname string 50 角色名称 是
data.list.level int 11 角色等级 是
data.list.vip_level int 11 角色vip等级 是
data.list.register_time string 50 创角时间，格式YYYY-MM-DD hh:mm:ss 是
data.list.did string 32 创角设备id 是
data.list.ip string 32 创角ip 是
data.list.amount float 32 累计充值金额（单位为元或美元） 是
data.list.recharge_num int 11 累计充值笔数 是
data.list.last_login_time string 32 最后登录时间，格式YYYY-MM-DD hh:mm:ss 是
  • 响应示例：
{"status":1,"msg":"success","data":{"total":"2","list":[{"server_name":"游戏服名称1","channel_name":"渠道名称1","server_id":"1","channel_id":"1","open_id":"413bea7eafa0dafe8f76a4544546ae3b","pid":"3245dgh","pname":"角色名1","level":"13","vip_level":"13","register_time":"2019-02-07 14:28:15","did":"3ab0854691d6870bfcfe6c501c3bd78e","ip":"123.207.66.53","amount":"100","recharge_num":"13","last_login_time":"2019-02-07 14:38:15"},{"server_name":"游戏服名称2","channel_name":"渠道名称2","server_id":"2","channel_id":"2","open_id":"413bea7eafa0dafe8f76a4544546ae3b","pid":"3345dgh","pname":"角色名2","level":"11","vip_level":"12","register_time":"2019-02-07 14:28:15","did":"3ab0854691d6870bfcfe6c501c3bd78e","ip":"123.207.66.53","amount":"333","recharge_num":"13","last_login_time":"2019-02-07 14:38:15"}]}}

5. 获取游戏服准入白名单

5.1 说明
  • 游戏研发可通过此接口获取于 GM系统-操作工具-游戏服管理-准入白名单 配置的准入白名单
  • 注意：星云会异步把准入白名单数据全量推送到该GM接口，研发需自行处理准入白名单用户进入游戏逻辑
5.2 请求方式
  • POST
5.3 请求参数
参数名 类型 长度 说明 是否必传
whitelist string 20000 聚合OpenID列表，用英文逗号进行分割，最大20000个 是
5.4 返回参数
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":{

    }
}

6. 获取客服工单处理通知

6.1 说明
  • 玩家于C端SDK登录后客服中心（含“SDK登录后进入游戏前”+“SDK进入游戏后”）“联系客服”提交的问题，在B端客服工单系统被客服人员回复后，游戏研发可通过此接口获取进度提醒，用于在游戏内向玩家推送已处理通知
  • 注意
    • 游戏向玩家的具体推送形式，需由游戏研发自行处理（如红点、邮件等）
    • 此接口暂不支持 WEB客服 及 SDK登录前客服 的工单处理进度通知，其余通知方式说明，详见 客服中心介绍
6.2 请求方式
  • POST
6.3 请求参数
参数名 类型 长度 说明 是否必传
open_id string 32 用户OpenID 是
sid string 32 服务器id 否
channel_id string 32 渠道id 否
pid string 32 角色id 否
6.4 返回参数
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":{

    }
}

7. 获取道具名称列表

7.1 说明
  • 若此接口已配置上线，则GM系统中的所有功能，若需使用道具信息，将自动同步此接口信息
7.2 请求方式
  • GET
7.3 请求参数
7.4 返回参数
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":[
        {
            "id":"1",
            "name":"name1"
        },
        {
            "id":"2",
            "name":"name2"
        }
    ]
}

8. 获取道具变更明细

  • 运用于 GM系统-信息查询-道具变更明细
8.1 获取道具变更明细（按变更时间降序）

HTTP 请求方式：
GET

参数说明：

参数名 类型 长度 说明 是否必传
per_page int 11 每页显示条数 是
page int 11 页码 是
pid string 50 角色id 是
prop_id int 11 道具id 否，和变更原因id必传一个
change_reason_id int 11 变更原因id 否，和道具id必传一个
change_start_time string 32 变更开始时间，格式YYYY-MM-DD hh:mm:ss 是
change_end_time string 32 变更结束时间，格式YYYY-MM-DD hh:mm:ss 是

请求示例：
http://{HOST}:{PORT}/propChangeList?ts=1535195226&sig=1c9f83680d579d182b02b81efad18523&per_page=10&page=1pid=111&prop_id=11&change_start_time=2019-06-11 11:11:09&change_end_time=2019-06-11 11:16:11
响应示例：

{"status":1,"msg":"success","data":{"total":"2","list":[{"change_time":"2020-07-18 00:01:57","prop_name":"道具名称1","change_num":"+10","account_num":"100","change_reason":"变更原因1"},{"change_time":"2020-07-18 00:02:57","prop_name":"道具名称2","change_num":"-10","account_num":"80","change_reason":"变更原因2"}]}}

返回参数说明：

参数名 类型 长度 说明 是否必传
data.total int 11 总记录数 是
data.list array 1000 道具变更明细列表 是
data.list.change_time string 32 变更时间，格式YYYY-MM-DD hh:mm:ss 是
data.list.prop_name string 50 道具名称 是
data.list.change_num string 11 变更数量，如果是增加，数量前面需加上+，如果是减少，数量前面需加上-，例如+10或-20 是
data.list.account_num int 11 变更后数量 是
data.list.change_reason string 50 变更原因 是
8.2 获取道具变更原因列表

HTTP 请求方式：
GET
参数说明：

请求示例：
http://{HOST}:{PORT}/propChangeReasonList?ts=1535195226&sig=1c9f83680d579d182b02b81efad18523
响应示例：

{
    "status":1,
    "msg":"success",
    "data":[
        {
            "id":"1",
            "name":"变更原因1"
        },
        {
            "id":"2",
            "name":"变更原因2"
        }
    ]
}

返回参数说明：

参数名 类型 长度 说明 是否必传
id string 11 变更原因id 是
name string 50 变更原因 是

9. 道具删除

9.1 说明
  • 运用于 GM系统-操作工具-道具操作-道具删除
9.2 请求方式
  • POST
9.3 请求参数
{
    "pid": "syusfjfjs",
    "prop_list": [
        {"id":"xx","num":10},
        {"id":"yy","num":1}
    ],
    "reason":"xxxx"
}
参数名 类型 长度 说明 是否必传
pid string 50 角色id 是
prop_list string，json格式 - 道具列表 是
prop_list.id string 50 道具id 是
prop_list.num int 11 道具数量 是
reason string 50 删除原因 是
9.4 返回参数
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":{

    }
}

10. 发送富文本公告（分批）

10.1 说明
  • 运用于 GM系统-操作工具-公告管理-添加&修改富文本公告
  • 该接口是分批请求接口，当渠道或游戏服数量大于1000，会以每批1000条进行发送
  • 有渠道或游戏服追加时，会增量请求
  • 注：在添加&修改富文本公告时就会调用此接口，公告的显示需要由接入方自行处理
10.2 请求方式
  • POST
10.3 请求参数
{
    "anc_id": "100",
    "anc_type": 1,
    "title": "礼包兑换成功",
    "list_title":"公告列表标题",
    "content": {},
    "sid_list":["a111","a222"],
    "channel_id_list":["1","2"],
    "img_list":[
        {"img":"http://img1","link":"link1"},
        {"img":"http://img2","link":"link2"}
    ],
    "start_time":"2023-10-01 00:00:00",
    "end_time":"2023-10-10 00:00:00",
    "create_time":"2023-10-01 10:00:00",
    "update_time":"2023-10-01 10:00:00"
    "sort":-1,
    "is_del":0
}
参数名 类型 长度 说明 是否必传
anc_id string 11 公告ID，唯一 是
anc_type int 1 公告类型，固定为1，表示富文本 是
title string 50 公告标题 是
list_title string 50 公告列表标题，可选 否
content string，json格式 - 公告内容，富文本json，参见“请求参数说明”关于富文本的说明 是
channel_id_list string，json格式 - 多个渠道id，和游戏服id二选一 否
sid_list string，json格式 - 多个游戏服id，和渠道id二选一 否
start_time string - 开始生效时间，格式YYYY-MM-DD hh:mm:ss 是
end_time string - 生效结束时间，格式YYYY-MM-DD hh:mm:ss 是
create_time string - 创建时间，格式YYYY-MM-DD hh:mm:ss 是
update_time string - 更新时间，格式YYYY-MM-DD hh:mm:ss 是
sort int 11 优先级，0置顶、-1置底，＞0值越大越优先 是
tag string 32 标签，可选 否
img_list string，json格式 - 轮播图，可选 否
img_list.img string - 图片url 是
img_list.link string - 图片跳转链接，选填 否
is_del int 1 默认0，1表示这一批次的数据都要删除 是
10.4 返回参数
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":{

    }
}

11. 发送跑马灯公告（分批）

11.1 说明
  • 运用于 GM系统-操作工具-公告管理-添加&修改跑马灯公告
  • 该接口是分批请求接口，当渠道或游戏服数量大于1000，会以每批1000条进行发送
  • 注：在添加&修改跑马灯公告时就会调用此接口，公告的显示需要由接入方自行处理
11.2 请求方式
  • POST
11.3 请求参数
{
    "anc_id": "11.",
    "anc_type": 2,
    "content": "亲爱的玩家：\n 礼包奖励兑换成功，请及时领取，祝您游戏愉快^_^",
    "channel_id_list":["1","2"],
    "sid_list":["a111","a222"],
    "start_time":"2023-11.01 00:00:00",
    "end_time":"2023-11.11.00:00:00",
    "create_time":"2023-11.01 11.00:00",
    "update_time":"2023-11.01 11.00:00"
    "sort":-1,
    "interval":11,
    "is_del":0
}
参数名 类型 长度 说明 是否必传
anc_id string 11 公告ID，唯一 是
anc_type int 1 公告类型，固定为2，表示跑马灯 是
content string - 公告内容，纯文本 是
channel_id_list string，json格式 - 多个渠道id，和游戏服id二选一 否
sid_list string，json格式 - 多个游戏服id，和渠道id二选一 否
start_time string - 开始生效时间，格式YYYY-MM-DD hh:mm:ss 是
end_time string - 生效结束时间，格式YYYY-MM-DD hh:mm:ss 是
create_time string - 创建时间，格式YYYY-MM-DD hh:mm:ss 是
update_time string - 更新时间，格式YYYY-MM-DD hh:mm:ss 是
sort int 11 优先级，0置顶、-1置底，＞0值越大越优先 是
interval int 11 播放间隔，分钟 是
is_del int 1 默认0，1表示这一批次的数据都要删除 是
11.4 返回参数
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":{

    }
}

12. 删除公告

12.1 说明
  • 运用于 GM系统-操作工具-公告管理-删除富文本公告&跑马灯公告
  • 注：在删除富文本公告&跑马灯公告时就会调用此接口，公告的显示需要由接入方自行处理
12.2 请求方式
  • POST
12.3 请求参数
{
    "anc_id": "100",
    "anc_type": 1
}
参数名 类型 长度 说明 是否必传
anc_id string 11 公告ID，唯一 是
anc_type int 1 公告类型，1富文本 2跑马灯 是
12.4 返回参数
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":{

    }
}

13. 发送全服邮件（分批）

13.1 说明
  • 运用于 GM系统-操作工具-邮件管理-添加&修改全服邮件
  • 该接口是分批请求接口，当渠道或游戏服数量大于1000，会以每批1000条进行发送
  • 有渠道或游戏服追加时，会增量请求
  • 注：在到达设定时间时才会调用此接口
13.2 请求方式
  • POST
13.3 请求参数
{
    "email_id":"100",
    "email_type":1,
    "title": "礼包兑换成功",
    "sender": "福利官",
    "content": {},
    "pid_deny_list": ["syusfjfjs"],
    "channel_id_list":["1","2"],
    "sid_list":["a111","a222"],
    "prop_list": [
        {"id":"xx","num":10},
        {"id":"yy","num":1}
    ],
    "send_time":"2023-10-01 00:00:00",
    "end_time":"2023-10-07 00:00:00",
    "batch_id":"2d02e669731cbade6a64b58d602cf2a4",
}
参数名 类型 长度 说明 是否必传
email_id string 64 邮件ID，最长64位，唯一 是
email_type int 1 邮件类型，固定为1，表示全服邮件 是
title string 50 邮件标题 是
sender string 50 发件人 否
content string，json格式 - 邮件内容，富文本json，参见“请求参数说明”关于富文本的说明 是
pid_deny_list string，json格式 - 角色id黑名单 否
channel_id_list string，json格式 - 多个渠道id，和游戏服id二选一 否
sid_list string，json格式 - 多个游戏服id，和渠道id二选一 否
prop_list string，json格式 - 可选，发送道具 否
prop_list.id string 50 道具id 是
prop_list.num int 11 道具数量 是
batch_id string 64 批次id，唯一 是
send_time string - 发送时间，格式YYYY-MM-DD hh:mm:ss 是
end_time string - 失效时间，格式YYYY-MM-DD hh:mm:ss 否
13.4 返回参数
  • 响应示例：

a 异步通知邮件发送结果，需要调用发送全服邮件回调接口（同一个请求同步返回和异步返回格式二选一）

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

b 同步通知邮件发送结果（同一个请求同步返回和异步返回格式二选一）

{
    "status":1,
    "msg":"success",
    "data":{
         "list":[
            {"item_id":"aaaa","result":1,"note":""},
            {"item_id":"bbb","result":2,"note":"ID不存在"}
        ]
    }
}
参数名 类型 注释 是否必填
list string，json格式 发送结果列表，可选 是
list.item_id string 游戏服ID或者渠道ID 是
list.result int 发送情况，1成功 2失败 是
list.note string 备注，可为空 是

14. 发送角色邮件（分批）

14.1 说明
  • 运用于 GM系统-操作工具-邮件管理-添加&修改角色邮件
  • 该接口是分批请求接口，当角色数量大于1000，会以每批1000条进行发送
  • 注：在到达设定时间时才会调用此接口
14.2 请求方式
  • POST
14.3 请求参数
{
    "email_id":"100",
    "email_type":2,
    "source":1,
    "exchange_id":23,
    "title": "礼包兑换成功",
    "sender": "福利官",
    "content": {},
    "pid_list": ["syusfjfjs"],
    "prop_list": [
        {"id":"xx","num":10},
        {"id":"yy","num":1}
    ],
    "send_time":"2023-10-01 00:00:00",
    "end_time":"2023-10-07 00:00:00",
    "batch_id":"2d02e669731cbade6a64b58d602cf2a4",
}
参数名 类型 长度 说明 是否必传
email_id string 64 邮件ID，最长64位，唯一 是
email_type int 1 邮件类型，固定为2，表示角色邮件 是
source int 1 来源，1后台 2礼包码 3微信礼包 是
exchange_id string 255 礼包码兑换记录id，source=2平台礼包回调接口需要传回，其它类型不需要。有传入时需要根据exchange_id做幂等，避免一次兑换多次发送邮件。 否
title string 50 邮件标题 是
sender string 50 发件人 否
content string，json格式 - 邮件内容，富文本json，参见“请求参数说明”关于富文本的说明 是
sid string 32 服务器id，1、字段为可选参数，星云开放平台不进行预置，有需要自行新增自定义参数。2、微信礼包码下发道具邮件该字段有值，需要进行校验 否
pid_list string，json格式 - 角色id列表 是
prop_list string，json格式 - 可选，发送道具列表 否
prop_list.id string 50 道具id 是
prop_list.num int 11 道具数量 是
batch_id string 64 批次id，唯一 是
send_time string - 发送时间，格式YYYY-MM-DD hh:mm:ss 是
end_time string - 失效时间，格式YYYY-MM-DD hh:mm:ss 否
14.4 返回参数
  • 响应示例：

a 异步通知邮件发送结果，需要调用发送角色邮件回调接口（同一个请求同步返回和异步返回格式二选一）

{
    "status":1,
    "msg":"success",
    "data":{

    }
}

b 同步通知邮件发送结果（同一个请求同步返回和异步返回格式二选一）

{
    "status":1,
    "msg":"success",
    "data":{
         "list":[
            {"pid":"aaaa","result":1,"note":""},
            {"pid":"bbb","result":2,"note":"ID不存在"}
        ]
    }
}
参数名 类型 注释 是否必填
list string，json格式 发送结果列表，可选 是
list.pid string 角色id 是
list.result int 发送情况，1成功 2失败 是
list.note string 备注，可为空 是

15. 撤回邮件

15.1 说明

  • 运用于 GM系统-操作工具-邮件管理-撤回全服邮件&角色邮件

  • 注：在-撤回全服邮件&角色邮件调用此接口，道具是否撤回由接入方自行处理

    15.2 请求方式

  • POST

15.3 请求参数
{
    "email_id": "100",
    "email_type": 1
}
参数名 类型 长度 说明 是否必传
email_id string 64 邮件ID，最长64位，唯一 是
email_type int 1 邮件类型，1全服邮件 2角色邮件 是
15.4 返回参数
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":{

    }
}

16. 获取玩家聊天内容

16.1 说明
  • GM系统-操作工具-聊天监控 中，可通过此接口查询玩家聊天内容
16.2 请求方式
  • POST
16.3 请求参数
参数名 类型 长度 说明 是否必传
sid string 11 游戏服id，多个通过 “;” 符号拼接 是
channel_id string 11 频道id，多个通过 “;” 符号拼接 是
start_time string 32 聊天内容开始时间，格式YYYY-MM-DD hh:mm:ss 是
end_time string 32 聊天内容结束时间，格式YYYY-MM-DD hh:mm:ss 是
min_level int 11 角色最小等级 否
max_level int 11 角色最大等级 否
16.4 返回参数
参数名 类型 长度 说明 是否必传
sid string 11 游戏服id 是
server_name string 50 游戏服名称 是
content string 512 聊天内容 是
create_time string 50 聊天时间，格式YYYY-MM-DD hh:mm:ss 是
pname string 50 角色名称 是
pid string 32 角色id 是
channel_name string 50 频道 是
  • 响应示例：
{"status":1,"msg":"success","data":[{"sid":"1","server_name":"服务器1","content":"聊天内容1","create_time":"2020-06-23 15:57:25","pname":"角色名称1","pid":"dfhe23233","channel_name":"频道名称1"},{"sid":"2","server_name":"服务器1","content":"聊天内容2","create_time":"2020-06-2315:57:26","pname":"角色名称2","pid":"fg345fg4","channel_name":"频道名称2"}]}

17. 获取游戏聊天频道列表

17.1 说明
  • GM系统-操作工具-聊天监控 中，可通过此接口选择聊天频道
17.2 请求方式
  • GET
17.3 请求参数
参数名 类型 长度 说明 是否必传
sid string 11 游戏服id 否，多个通过 “;” 符号拼接
17.4 返回参数
参数名 类型 长度 说明 是否必传
id int 11 频道id 是
name string 50 频道名称 是
  • 响应示例：
{"status":1,"msg":"success","data":[{"id":"1","name":"频道1"},{"id":"2","name":"频道2"}]}

18. 角色禁言

18.1 说明
  • GM系统-操作工具-违规封禁-封禁 中，可通过此接口角色禁言
  • GM系统-操作工具-聊天监控 中，可通过此接口角色禁言
18.2 请求方式
  • POST
18.3 请求参数
参数名 类型 长度 说明 是否必传
sid string 11 游戏服id 是
pid string 32 角色id 是
day int 11 封禁天数 是
18.4 返回参数
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":{

    }
}

19. 解除角色禁言

19.1 说明
  • GM系统-操作工具-违规封禁-解除封禁 中，可通过此接口解除角色禁言
  • GM系统-操作工具-聊天监控 中，可通过此接口解除角色禁言
19.2 请求方式
  • POST
19.3 请求参数
参数名 类型 长度 说明 是否必传
sid string 11 游戏服id 是
pid string 32 角色id 是
19.4 返回参数
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":{

    }
}

20. 角色封停

20.1 说明
  • GM系统-操作工具-违规封禁-封禁 中，可通过此接口角色封停
  • GM系统-操作工具-聊天监控 中，可通过此接口角色封停
20.2 请求方式
  • POST
20.3 请求参数
参数名 类型 长度 说明 是否必传
sid string 11 游戏服id 是
pid string 32 角色id 是
day int 11 封禁天数 是
20.4 返回参数
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":{

    }
}

21. 角色解封

21.1 说明
  • GM系统-操作工具-违规封禁-解除封禁 中，可通过此接口角色解封
  • GM系统-操作工具-聊天监控 中，可通过此接口角色解封
21.3 请求方式
  • POST
21.3 请求参数
参数名 类型 长度 说明 是否必传
sid string 11 游戏服id 是
pid string 32 角色id 是
21.4 返回参数
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":{

    }
}

22. ip封停

22.1 说明
  • GM系统-操作工具-违规封禁-封禁 中，可通过此接口IP封停
22.2 请求方式
  • POST
22.3 请求参数
参数名 类型 长度 说明 是否必传
sid string 11 游戏服id 是
ip string 32 ip 是
day int 11 封禁天数 是
22.4 返回参数
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":{

    }
}

23. ip解封

23.1 说明
  • GM系统-操作工具-违规封禁-解除封禁 中，可通过此接口IP解封
23.2 请求方式
  • POST
23.3 请求参数
参数名 类型 长度 说明 是否必传
sid string 11 游戏服id 是
ip string 32 ip 是
23.4 返回参数
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":{

    }
}

24. 设备封停

24.1 说明
  • GM系统-操作工具-违规封禁-封禁 中，可通过此接口设备封停
24.2 请求方式
  • POST
24.3 请求参数
参数名 类型 长度 说明 是否必传
sid string 11 游戏服id 是
did string 32 设备id 是
day int 11 封禁天数 是
24.4 返回参数
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":{

    }
}

25. 设备解封

25.1 说明
  • GM系统-操作工具-违规封禁-解除封禁 中，可通过此接口设备解封
25.2 请求方式
  • POST
25.3 请求参数
参数名 类型 长度 说明 是否必传
sid string 11 游戏服id 是
did string 32 设备id 是
25.4 返回参数
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":{

    }
}

26. 网页直充创建订单

26.1 说明
  • 玩家网页直充时，中台通过此接口直接向游戏服务端创建订单
  • 需对传入参数需要做基本校验，例如：商品ID和金额是否一致、是否停服
  • 注意：针对网页直充支付回调扩展参数额外新增两个参数goods_ext（商品扩展参数）、callback_ext（创建游戏订单扩展参数）
    {"pay_sign_type":"md5","os":"windows","callback_ext":"","goods_ext":""}
26.2 请求方式
  • POST
26.3 请求参数
参数名 类型 长度 说明 是否必传
server_id string 32 区服ID 是
channel_id string 32 渠道ID 是
goods_id string 50 商品ID 是
pay_amount int 11 支付金额（单位：分） 是
open_id string 32 用户OpenID 是
pid string 32 角色ID 是
level int 11 角色等级 是
vip_level int 11 vip等级 是
26.4 返回参数
字段名 类型 说明
game_order_id string 游戏订单ID
callback_ext string 游戏透传参数，支付回调游戏服务端会合并到notify_ext参数里回传，例如：{"notify_ext":{"callback_ext":""}}
  • 响应示例：
{
    "status":1,
    "msg":"success",
    "data":{
        "game_order_id":"2023111011124011111",
        "callback_ext":""
    }
}

回调接口列表

说明

  • 1 下列接口是接入方调用星云的接口，非必接

  • 2 签名使用App Secret签名规则

  • 3 入参的公共参数有

参数名 类型 注释 是否必填
app_id string 星云AppID 是
timestamp int 时间戳 是
sign string 签名 是
sign_type string 签名类型(默认：md5) 是
sign_nonce string 签名随机数(随机数字+字符串共8位) 是
sign_version string 签名版本,默认1.0 是
  • 4 以json格式返回，包含以下字段
参数名 说明 是否必传
status 状态，成功未0 ， 失败为非0 是
message 信息 是
trace_id 追踪id，排查问题用 否
data 数据 否
  • 响应示例：
{
    "trace_id": "d77f7de9bb5dd754b726d2a99c9f4375",
    "status": 0,
    "message": "OK",
    "data": {}
}

1. 游戏服变更回调

1.1 描述
  • 当游戏服务端有服务器变更时，将服务器变更信息通知到星云
  • 根据server_id来识别，如果存在，会更新记录，不存在则插入记录
  • 如果记录is_del为0，便会删掉对应server_id的记录
  • 单次调用接口最多限制1000条服务器信息
1.2 接口地址
1.3 请求方式
  • POST
1.4 请求参数
{
    "list":[
        {
            "is_del":0,
            "sid":"aaaaaa",
            "name":"221121",
            "server_char":"集群标识",
            "display_time":"2023-10-01 10:00:00",
            "open_time":"2023-10-01 10:00:00",
            "channel_id_list":[
                "1",
                "2"
            ],
            "tag":1,
            "use_status":1,
            "maintain_status":1,
            "deploy_status":1,
            "create_time":"2023-10-01 10:00:00",
            "update_time":"2023-10-01 10:00:00"
                 },
        {
            "is_del":0,
            "sid":"bbbb",
            "name":"221121",
            "server_char":"集群标识",
            "display_time":"2023-10-01 10:00:00",
            "open_time":"2023-10-01 10:00:00",
            "channel_id_list":[
                "1",
                "2"
            ],
            "tag":1,
            "use_status":1,
            "maintain_status":1,
            "deploy_status":1,
            "create_time":"2023-10-01 10:00:00",
            "update_time":"2023-10-01 10:00:00"
             }
    ],
    "app_id":"30035",
    "timestamp": 1535198961,
    "sign": "0bebc8ef5313b9f9b73194e138a6ee50",
    "sign_type": "md5",
    "sign_nonce": "0bebc8qq",
    "sign_version": "1.0"
}
参数名 类型 注释 是否必填
app_id string 星云AppID 是
list string 服务器列表，单次最多限制1000条数据 是
list.is_del int 默认0，1表示删除 否
list.sid string 游戏服id 是
list.name string 服务器名称 是
list.server_char string 集群标识 是
list.display_time string 对外展示时间，格式YYYY-MM-DD hh:mm:ss 是
list.open_time string 开服时间，格式YYYY-MM-DD hh:mm:ss 是
list.auto_add_channel int 新增官方渠道时自动追加，0否 1是 是
list.channel_id_list array 渠道id列表 是
list.tag int 标签，1正常 2新服 3爆满 4推荐 是
list.use_status int 使用状态，1启用 2停新 3停用 是
list.maintain_status int 维护状态，1正常 2维护 是
list.deploy_status int 部署状态，1未部署 2变更中 3已部署 是
list.create_time string 创建时间，格式YYYY-MM-DD hh:mm:ss 是
list.update_time string 更新时间，格式YYYY-MM-DD hh:mm:ss 是
timestamp int 时间戳 是
sign string 签名 是
sign_type string 签名类型(默认：md5) 是
sign_nonce string 签名随机数(随机数字+字符串共8位) 是
sign_version string 签名版本,默认1.0 是
1.5 请求成功返回：
{
    "trace_id": "d77f7de9bb5dd754b726d2a99c9f4375",
    "status": 0,
    "message": "OK",
    "data": {}
}

2. 发送全服邮件回调

2.1 描述
  • 当发送全服邮件后，将具体发送结果变更信息回调
2.2 接口地址
2.3 请求方式
  • POST
2.4 请求参数
{
    "app_id": "30035",
    "email_id": "100",
    "email_type": 1,
    "timestamp": 1535198961,
    "list":[
        {"item_id":"aaaa","result":1,"note":""},
        {"item_id":"aaaa","result":2,"note":"服务器ID不存在"}
    ],
    "sign": "0bebc8ef5313b9f9b73194e138a6ee50",
    "sign_type": "md5",
    "sign_nonce": "0bebc8qq",
    "sign_version": "1.0"
}
参数名 类型 注释 是否必填
app_id string 星云AppID 是
email_id string 邮件id 是
email_type int 邮件类型，固定为1，表示全服邮件 是
timestamp int 时间戳 是
list string 发送结果列表 是
list.item_id string 游戏服ID或者渠道ID 是
list.result int 角色发送情况，1成功 2失败 是
list.note string 备注 是
sign string 签名 是
sign_type string 签名类型(默认：md5) 是
sign_nonce string 签名随机数(随机数字+字符串共8位) 是
sign_version string 签名版本,默认1.0 是
2.5 请求成功返回：
{
    "trace_id": "d77f7de9bb5dd754b726d2a99c9f4375",
    "status": 0,
    "message": "OK",
    "data": {}
}

3. 发送角色邮件回调

3.1 描述
  • 当发送角色邮件后，将具体发送结果变更信息回调
3.2 接口地址
3.3 请求方式
  • POST
3.4 请求参数
{
    "app_id": "30035",
    "email_id": "100",
    "email_type": 2,
    "timestamp": 1535198961,
    "list":[
        {"pid":"aaaa","result":1,"note":""},
        {"pid":"aaaa","result":2,"note":"角色ID不存在"}
    ],
    "sign": "0bebc8ef5313b9f9b73194e138a6ee50",
    "sign_type": "md5",
    "sign_nonce": "0bebc8qq",
    "sign_version": "1.0"
}
参数名 类型 注释 是否必填
app_id string 星云AppID 是
email_id string 邮件id 是
email_type int 邮件类型，固定为2，表示角色邮件 是
timestamp int 时间戳 是
list string 发送结果列表 是
list.pid string 角色id 是
list.result int 角色发送情况，1成功 2失败 是
list.note string 备注 是
sign string 签名 是
sign_type string 签名类型(默认：md5) 是
sign_nonce string 签名随机数(随机数字+字符串共8位) 是
sign_version string 签名版本,默认1.0 是
3.5 请求成功返回：
{
    "trace_id": "d77f7de9bb5dd754b726d2a99c9f4375",
    "status": 0,
    "message": "OK",
    "data": {}
}

4. 获取渠道列表

4.1 描述
  • 获取对接中心-渠道配置的渠道列表
4.2 接口地址
4.3 请求方式
  • POST
4.4 请求参数
{
    "app_id": "30035",
    "timestamp": 1535198961,
    "sign": "0bebc8ef5313b9f9b73194e138a6ee50",
    "sign_type": "md5",
    "sign_nonce": "0bebc8qq",
    "sign_version": "1.0"
}
参数名 类型 注释 是否必填
app_id string 星云AppID 是
timestamp int 时间戳 是
sign string 签名 是
sign_type string 签名类型(默认：md5) 是
sign_nonce string 签名随机数(随机数字+字符串共8位) 是
sign_version string 签名版本,默认1.0 是
4.5 请求成功返回：
{
    "trace_id": "d77f7de9bb5dd754b726d2a99c9f4375",
    "status": 0,
    "message": "OK",
    "data": [
        {"channel_id":1,"channel_name":"xxxx","is_official":1},
        {"channel_id":2,"channel_name":"xxxx","is_official":0}
    ]
}
参数名 类型 注释 是否必填
status int 状态码 是
message string 消息 是
data array 数据 是
data.channel_id int 渠道id 是
data.channel_name string 渠道名称 是
data.is_official int 是否官方，1官方 0三方 是

App Key签名规则

秘钥

见 对接中心-SDK列表-App Key

说明

所有星云方请求接入方的GM接口都使用该签名规则

MD5步骤说明

1 待签名参数 ：除去 sig ，其他参数(包含空值的参数)都要参加验签。
2 对所有待签名参数按照字段名的ASCII码从小到大排序。
3 使用键值对的格式（key1=value1&key2=value2）拼接成字符串；进行urlencode编码（PHP使用rawurlencode），获得$source字符串。
4 将步骤3的$source字符与秘钥通过&符号进行拼接:$source&$key。
5 将步骤4的字符串进行md5哈希签名得到最终sign值。

签名样例（PHP版本）： 

ksort($data);//1 按照健值从小到大排序
$query_string = array();//2 键值对按照'='拼接,排除sign参数
foreach ($data as $key => $val) {
    if ($key == 'sig') continue;
    array_push($query_string, $key . '=' . $val);
}
$query_string = join('&', $query_string);//3 将上述数组按照&拼接
$source = rawurlencode($query_string);//4 将拼接结果用rawurlencode编码
$sign= md5($source.'&'. $app_secret);//md5 hash计算签名

App Secret签名规则

秘钥

见 对接中心-SDK列表-App Secret

说明

所有接入方请求星云的接口都使用该签名规则

MD5步骤说明

1 待签名参数 ：除去 sig ，其他参数(包含空值的参数)都要参加验签。
2 对所有待签名参数按照字段名的ASCII码从小到大排序。
3 使用键值对的格式（key1=value1&key2=value2）拼接成字符串；进行urlencode编码（PHP使用rawurlencode），获得$source字符串。
4 将步骤3的$source字符与秘钥通过&符号进行拼接:$source&$key。
5 将步骤4的字符串进行md5哈希签名得到最终sign值。

签名样例（PHP版本）： 

ksort($data);//1 按照健值从小到大排序
$query_string = array();//2 键值对按照'='拼接,排除sign参数
foreach ($data as $key => $val) {
    if ($key == 'sig') continue;
    array_push($query_string, $key . '=' . $val);
}
$query_string = join('&', $query_string);//3 将上述数组按照&拼接
$source = rawurlencode($query_string);//4 将拼接结果用rawurlencode编码
$sign= md5($source.'&'. $app_secret);//md5 hash计算签名
文章目录