AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 云游戏平台（文档停止维护） API参考 SPI参考

SPI参考

更新时间：
我的收藏

云游戏平台服务端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=1时必须返回；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：开始游戏（玩家进入游戏）

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"]}

接口说明

  1. 为了链路性能考虑，请按需订阅您需要使用的消息类型；

  2. 整体容器生命周期通知的接口调用不保证实时性，时间以消息体中的time，startTime等时间为准；

  3. 当返回消费失败时，都会重复投递。若不希望重复收到消息时请返回消费成功；

  4. 容器退出消息“CONTAINER_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：调度成功 20000: 异常退出

eventMessage

String

事件说明

非必须，调度成功,已分配容器

timeStamp

Long

当前行为的时间

必须，Unix时间戳（单位：毫秒）

dispatchInfo

String

调度详细信息

非必须

dispatchInfo字段描述说明：

参数

类型

含义

取值说明

dispatched

Boolean

是否已经分配容器

必须

failCode

String

错误码

非必须， 

  1. WAITING_TIMEOUT：玩家在排队过程中超时

  2. CONNECT_TIMEOUT：游戏容器已分配，等待玩家连接超时

queued

Boolean

是否已经加入排队队列

必须

返回（需带上公共参数）

参数

类型

含义

取值说明

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

上一篇：RAM鉴权下一篇：常见问题