云游戏平台服务端SPI接口能力包括会话鉴权、游戏准入、容器生命周期通知等服务,本篇介绍SPI接入步骤、接口标准等内容。

接入说明

云游戏PaaS服务需要在会话鉴权、游戏准入等场景调用客户业务系统。客户方需要按照云游戏PaaS统一制定的接入标准进行接入。标准说明如下:

  • 需要提供相应的https服务,供云游戏PaaS平台调用;
  • 需要按照云游戏PaaS平台制定的标准模版,统一输入输出数据格式;
  • 需要采用在云游戏运营中心申请的服务端AppKey对数据进行验签和加签;
  • 需要满足云游戏PaaS平台制定的质量标准;

1、服务端AppKey申请

通过阿里云账号登录云游戏PaaS服务控制台,选择运营中心,在项目列表中选中需要接入的【项目】,点击【应用列表管理】,点击【创建应用】,设备类型选择【服务端(SPI)】。

同一个项目只能创建一个【服务端(SPI)】应用。服务端接口将采用该应用对应的AppKey,AppSecret进行加签和验签操作。

2、创建SPI接口

通过阿里云账号登录云游戏PaaS服务控制台,选择运营中心,在项目列表中选中需要接入的【项目】,点击【SPI配置管理】,点击【创建SPI接口】

  • 输入模板名称
  • 选择模版类型
  • 接入服务https协议地址URL
  • 输入版本号(版本号不可重复,同一个模版类型如果存在多个版本的已上线SPI接口,云游戏平台会调用版本号最高的SPI接口)
  • 输入扩展参数(可选,部分接口需要)
  • 输入方法名(可选,部分接口需要)

3、调试并上线

自主完成开发和调试工作,在【SPI配置管理】页面,选择需要上线的接口,点击【上线】按钮,进入调试并上线页面,在该页面输入调试参数并且调试成功,方可点击【上线】按钮,完成接口的上线操作。上线之后云游戏平台的业务流程将会在相应的场景调用该SPI服务,请务必保证接口已经具备上线条件,再进行【上线】操作。

4、稳定性保障

  • 客户方需要提供接口流量的预估,云游戏PaaS平台技术人员将会针对项目维度设置限流,熔断等稳定性指标
  • 客户方接口稳定性达不到要求,云游戏PaaS平台将会采取限流,降级等措施以保障平台服务的稳定性

接口标准

  • 接口协议:https
  • host:业务方定义
  • 接口名称:业务方自定义

1、公共传入参数

参数 类型 含义 取值说明
action String 模版类型 必须,根据不同接口传不同参数
version Integer 接口版本 必须,默认值1,会请求所有上线接口中版本最高的一个
timestamp String 调用的时间戳,必须符合ISO8601规范,并需要使用UTC时间,时区为+0。 必须,举例子:2016-02-23T12:46:24Z
accessKey String 服务端AppKey 必须,云游戏paas平台统一颁发
signatureMethod String 签名方法 必须,HMAC-SHA1
signatureVersion String 方法版本 必须,1.0
signatureNonce String 随机数据 必须,端侧生成的随机数,长度在8-32位之间。生成方式可自己决定
format String 返回值类型 必须,JSON
signature String 签名 必须,生成方式参见下文
2、公共返回参数
参数 类型 说明 举例
code Int 返回编码
  • 0:success
  • -1:failed
message String 返回说明 OK:success
data 明细数据
data.signature String 签名 必须,通过云游戏PaaS平台统一颁发的AccessSecret加签,加签data中的数据即可
data.signatureNonce String 签名用随机数据 必须,生成的随机数,长度在8-32位之间。生成方式可自己决定
data.timestamp String 调用的时间戳,必须符合ISO8601规范,并需要使用UTC时间,时区为+0。 必须,2016-02-23T12:46:24Z

返回码code

编码 说明
0 成功
-1 失败

返回说明message

编码 说明
OK 成功
其他自定义文案 失败

接口模板

1、会话鉴权

模版说明

会话鉴权接口通过统一的标准,对客户的Session进行识别,从而做到识别客户的账号体系。整个Session鉴权流程如下图所示:

入参(需要带上公共入参)
参数 类型 含义 取值说明
action String 模版类型 必须,AUTH_CHECK
accountToken String 客户端SDK入参数userToken 必须,业务方token数据,业务方自己解析
accountId String 客户端SDK入参数userId 非必须,业务方accountId数据,业务方自己解析
frontAppKey String 客户端AppKey 必须,端侧使用的AppKey

返回(需带上公共参数)

参数 类型 说明 举例
code Integer 返回编码 公共参数
message String 返回说明 公共参数
data 明细数据 公共参数
data.sessionState Integer 会话状态 0:未识别或已过期;1:识别成功 必须
data.accountId String 用户唯一标示 非必须,未返回等同于sessionState=0
data.ttl Integer 身份信息缓存的时间,单位:秒 非必须,默认60秒,该场景不允许为0,必须指定缓存时间
data.accountDomain Integer 账号类型 非必须,如果业务方有多套账号类型,需要在该字段中返回,默认值0

降级策略

  • 信任客户端SDK主动传递的userId

2、游戏准入

模版说明

游戏准入接口模版通过统一的标准,在启动游戏时,请求客户服务进行最终的授权确认,整个游戏准入流程如下图所示:
入参(需要带上公共入参)
参数 类型 含义 取值说明
action String 模版类型 必须,GAME_ACCESS
gameId String 云游戏PaaS平台游戏ID 必须
accountToken String 客户端SDK入参数userToken 必须,业务方token数据,业务方自己解析
frontAppKey String 客户端AppKey 必须,端侧使用的AppKey
ip String 客户端请求IP 非必须
userLevel Integer 用户调度等级 非必须,端侧启动游戏时指定的用户调度等级
返回(需带上公共参数)
参数 类型 含义 取值说明
code Int 返回编码 公共参数
message String 返回说明 公共参数
data 明细数据 公共参数
data.accessState Integer 准入状态 必须 0:不允许启动1:允许启动
data.ttl Integer 准入状态缓存的时间,单位:秒 非必须,默认60秒,若为0,则表示不需要缓存;若小于0或者为空,则采用默认值
data.message String 原因描述 非必须
data.trialTag Integer 试玩标记1:跳过试玩0:进入试玩null:进入试玩 非必须,在当前项目配置了试玩策略的情况下才会生效

降级策略

  • 跳过游戏准入授权确认,全部可以启动游戏(在当前项目配置了试玩策略的情况下,全部视为试玩)

3、容器生命周期通知

模版说明

容器生命周期(指一次游戏运行的完整流程)通知接口模版通过统一的标准,在游戏容器生命周期的不同场景,将状态反馈给客户服务。

入参(需要带上公共入参)
参数 类型 含义 取值说明
action String 模版类型 必须,CONTAINER_STATE_MESSAGE
messageType String 消息类型 必须,
  1. CONTAINER_START:游戏容器启动(游戏服务器进程启动)
  2. CONTAINER_START_FAILED:游戏容器启动失败(游戏服务器进程启动)
  3. CONTAINER_QUIT:游戏容器退出(游戏服务器进程启动)
  4. PLAYER_START:开始游戏(玩家进入游戏)
  5. PLAYER_JOIN:加入游戏(玩家断线重连回到游戏,或者联机玩家加入游戏)
  6. PLAYER_QUIT:退出游戏(玩家离开游戏或者断线)
projectId String 项目ID 必须,游戏运行的项目ID
accountId String 账号ID 必须,启动游戏的玩家账号ID
accountDomain String 账号域 非必须,启动游戏的玩家账号域,默认值0
gameSessionId String 游戏会话ID 必须,一次游戏调度的唯一标识
gameId String 游戏ID 必须,运行的游戏ID
time Long 当前行为的时间 必须,Unix时间戳(单位:毫秒)
startTime Long 容器启动时间 必须,Unix时间戳(单位:毫秒)
linkedAccountIdList String 当前游戏中的玩家accountId集合 非必须,多个逗号分割
playerDetailList String 所有加入游戏的玩家信息集合 非必须,JSON格式:
  1. accountId:用户Id
  2. isInitiator:是否是游戏发起人
  3. startTime:加入游戏时间Unix时间戳,(单位:毫秒)

示例:[{"isInitiator":true,"startTime":1606113124250,"accountId":"test1"},{"isInitiator":false,"startTime":1606113124250,"accountId":"test2"}, ....]

tags String 启动游戏时传入的自定义标签 非必须,如有多个标签将采用半角逗号分割
返回(需带上公共参数)
参数 类型 含义 取值说明
code Int 返回编码 公共参数
message String 返回说明 公共参数
data 明细数据 公共参数
data.consumeState Integer 消费状态 必须 0:消费失败 1:消费成功
data.message String 原因描述 非必须

降级策略

  • 丢弃消息(在客户服务响应失败/无法响应超过一定阈值,qps超过最大阈值时才会进入降级流程)

扩展参数

该接口需要通过扩展参数指定需要订阅的消息类型(请根据您的实际场景指定需要订阅的消息类型即可,所有类型均为可选)。订阅的消息需要正常消费,如果消费失败,云游戏平台方会发起重试最多16次,超过16次之后将会丢弃该消息,扩展参数示例如下:

{"subscribeContainerMessage":["CONTAINER_START","CONTAINER_START_FAILED","CONTAINER_QUIT","PLAYER_START","PLAYER_JOIN","PLAYER_QUIT"]}

4、批量停止游戏回调通知

模版说明

客户方调用云游戏平台提供的批量停止游戏接口时,将采用该方式回调客户方进行通知,将进度反馈给客户服务。(该SPI接口需要配合批量停止游戏API一起使用)

入参(需要带上公共入参)
参数 类型 含义 取值说明
action String 模版类型 必须,BATCH_STOP_GAME_SESSIONS_CALLBACK
projectId String 项目ID 必须,发起调用的项目ID
gameId String 游戏ID 必须,发起调用的游戏ID
queuersCount Long 剩余排队人数 必须,操作批量停止的游戏目前剩余排队人数
playersCount Long 剩余游戏中人数 必须,操作批量停止的游戏目前剩余的游戏中人数
trackInfo String 附加链路信息 非必须
timeStamp Long 当前时间 必须,Unit时间戳(单位:毫秒)
返回(需带上公共参数)
参数 类型 含义 取值说明
code Int 返回编码 公共参数
message String 返回说明 公共参数
data 明细数据 公共参数
data.consumeState Integer 消费状态 必须 0:消费失败1:消费成功
data.message String 原因描述 非必须

降级策略

  • 丢弃消息(在客户服务响应失败/无法响应超过一定阈值,qps超过最大阈值时才会进入降级流程)

5、游戏调度事件回调通知

模版说明

在游戏排队调度过程中,将采用该方式回调客户方进行通知,将结果反馈给客户服务。

入参(需要带上公共入参)
参数 类型 含义 取值说明
action String 模版类型 必须,GAME_DISPATCH_EVENT_CALLBACK
projectId String 项目ID 必须,游戏运行的项目ID
gameId String 游戏ID 必须,运行的游戏ID
gameSessionId String 游戏会话ID 非必须,一次游戏调度的唯一标识
accountId String 账号ID 必须,启动游戏的玩家账号ID
accountDomain String 账号域 非必须,启动游戏的玩家账号域,默认值0
eventCode String 事件编码 必须,10000:调度成功,已分配容器
eventMessage String 事件说明 非必须,调度成功,已分配容器
timeStamp Long 当前行为的时间 必须,Unix时间戳(单位:毫秒)
返回(需带上公共参数)
参数 类型 含义 取值说明
code Int 返回编码 公共参数
message String 返回说明 公共参数
data 明细数据 公共参数
data.consumeState Integer 消费状态 必须 0:消费失败1:消费成功
data.message String 原因描述 非必须

降级策略

  • 丢弃消息(在客户服务响应失败/无法响应超过一定阈值,qps超过最大阈值时才会进入降级流程)

验签/加签方式

云游戏PaaS平台发起的请求将会采用以下方式加签,客户方返回参数同样需要对data中的值按照以下方式加签:https://help.aliyun.com/document_detail/25492.html?spm=5176.product25365.6.804.NbGBng