游戏数据库 TcaplusDB

产品简介

购买指南

快速入门

操作指南

开发者指南

最佳实践

常见问题

API 文档

服务协议

词汇表

联系我们
文档中心 > 游戏数据库 TcaplusDB > 开发者指南 > RESTful API > PHP RESTful API 接口说明

PHP RESTful API 接口说明

最近更新时间：2020-07-31 15:47:30

前往 GitHub 编辑 查看 PDF

本页目录：

准备工作

1. 创建 TcaplusDB 表

创建 TcaplusDB 示例表，示例表为game_players.proto，请参见 创建表格。

2. 创建 CVM 实例

  • 创建一台 CVM 实例来运行 SDK 示例程序，配置建议为1核2GB、Centos 7，该 CVM 需创建在 TcaplusDB 实例所在 VPC 网络中。
  • 通过 SDK 下载 PHP RESTful API SDK 安装包。

3. 准备 PHP 环境

新申请实例未安装 PHP，需要执行yum install php安装默认版本的 PHP 5.4.16，PHP 版本要求大于5.3。

使用方法

1. 修改配置

所有基础配置统一放在 SDK 安装目录下的config.php中，用户需要根据申请的表信息进行相应更改。

  • 连接配置：如 url、endpoint、table_group_id、access_id、access_passwd 等，修改成对应值，连接信息获取请参考 获取连接信息。
  • 默认数据源：此部分变量都为大写，用于 demo.php 中具体接口函数的数据源，可以统一在此修改。

2. 调用方式

为方便测试单个接口的功能，TcaplusDB 还把所有 SDK 接口函数单独成了程序，分别对应 demo 中的8个接口函数，采用的也是数据源与程序代码分离管理方式。
所有接口函数的数据源有两个地方，一个是默认的数据源，统一在config.php中，另一个是每个接口函数自己的数据源，在data子目录下，用户可以修改该数据文件来执行对应的接口函数，方便批量操作时避免在程序代码中定义数据源。如果数据文件不存在则会加载默认数据源。数据源统一采用数据列表方式，支持批量加载。
sample 中的程序文件执行方法类似：

php -f <具体的接口函数文件>

3. 接口函数

所有 API 接口封装成函数统一在 demo.php 中，总共有8个接口函数，所有接口函数支持从配置中加载数据源进行批量操作，具体函数如下所示：

接口函数名 接口函数功能
GetRecord 获取表记录
AddRecord 插入表记录
SetRecord 更新表记录
DeleteRecord 删除记录
FieldGetRecord 获取指定记录属性字段
FieldSetRecord 更新指定记录属性字段值
FieldIncRecord 更新指定记录属性字段数值，如增加/减少数值类型值
PartKeyGetRecord 根据指定索引获取指定记录属性字段值

SDK 接口列表

add

插入一条表记录，如果记录存在则报错。

@param $table_group_id (必须) - 目标表 table_group_id
@param $table_name (必须) - 目标表 table_name
@param $record (必须) - 待插入的目标记录数组
@param $ReturnValues (可选) - 指定返回的自定义值
@param $resultflag (可选) - 指定返回响应包的内容，取值范围如下：
            0: 应答中仅包含请求成功或失败
            1: 应答中包含与请求一致的值
            2: 应答中包含被修改的数据的所有字段最新值
            3: 应答中包含记录被修改前的值

public function add($table_group_id, $table_name, array $record, $ReturnValues = 'TcaplusDB', $resultflag = 1)

get

根据主键查询一条记录，支持指定要返回的属性字段列表，参考$params["select"]定义。

@param $table_group_id (必须) 游戏区 ID
@param $table_name (必须) 表名
@param $params (必须)
    $params\["select"\] (可选) 查询的字段 数组
    $params \["keys"\] (必须) 查询目标记录的主键字段(Primary key)
    $params \["limit"\] (可选) 返回记录数限制量
    $params \["offset"\] (可选) 返回记录数偏移量

public function get($table_group_id, $table_name, $params)

fieldGet

根据主键查询返回指定字段的值，指定字段列表参考$param["select"]，该参数必须为非空。

@param $table_group_id (必须) 游戏区 ID
@param $table_name (必须) 表名
@param  $params (必须)
    $params\["select"\] (必须) 查询的字段 数组
    $params\["keys"\] (必须) 查询目标记录的主键字段(Primary key)
    $params\["limit"\] (可选)  返回记录数限制量
    $params\["offset"\] (可选) 返回记录数偏移量

public function fieldGet($table_group_id, $table_name, $params)

partKeyGet

根据表定义的索引查询返回一条或多条记录，支持指定字段列表返回，支持 limit 和 offset 参数控制返回包的记录数。

@param $table_group_id (必须) 游戏区 ID
@param $table_name (必须) 表名
@param  $params (必须)
    $params\["select"\] (可选) 查询的字段 数组
    $params\["index"\] (必须) 查询的索引名称
    $params\["keys"\] (必须) 查询目标记录的主键字段(Primary key)
    $params\["limit"\] (可选)  返回记录数限制量,　默认值-1
    $params\["offset"\] (可选) 返回记录数偏移量

public function partKeyGet($table_group_id, $table_name, $params)

对于 partkeyGet 接口，1个请求返回的最大包大小为256KB, limit 的设置依赖于单条记录大小。推荐设置策略：

  • 单条记录小于256KB：limit 参考设置为 256KB / [单条记录大小]，如记录大小为10KB，则 limit 推荐设置20 - 25左右。
  • 单条记录大于等于256KB：limit 设置为1，即一次请求只返回一条记录。

关于 limit 和 offset 设置的响应示例如下:

#请求设置 limit=-1, offset=0
{"MultiRecords":[{"RecordVersion":1,"Record":{"pay":{"amount":1000,"pay_id":10101},"player_email":"kosh@test.com","player_id":1,"player_name":"kosh"}},{"RecordVersion":1,"Record":{"pay":{"amount":1000,"pay_id":10101},"player_email":"kosh@163.com","player_id":1,"player_name":"kosh"}},{"RecordVersion":1,"Record":{"pay":{"amount":1000,"pay_id":10101},"player_email":"kosh@gmail.com","player_id":1,"player_name":"kosh"}},{"RecordVersion":1,"Record":{"pay":{"amount":1000,"pay_id":10101},"player_email":"kosh@126.com","player_id":1,"player_name":"kosh"}}],"TotalNum":4,"RemainNum":0,"ErrorCode":0,"ErrorMsg":"Succeed"}

#请求设置limit=2, offset=0
{"MultiRecords":[{"RecordVersion":1,"Record":{"pay":{"amount":1000,"pay_id":10101},"player_email":"kosh@test.com","player_id":1,"player_name":"kosh"}},{"RecordVersion":1,"Record":{"pay":{"amount":1000,"pay_id":10101},"player_email":"kosh@163.com","player_id":1,"player_name":"kosh"}}],"TotalNum":4,"RemainNum":2,"ErrorCode":0,"ErrorMsg":"Succeed"}

从上面响应包来看，设置了 limit 和 offset 的结果返回的条数和设定的 limit 的大小保持一致。
如果用户想获取全量的索引数据，则可根据响应包中的RemainNum和TotalNum这两个标识来判断数据是否获取完全。

set

更新记录或插入记录, 如果记录存在则进行更新，如果记录不存在则进行插入。

@param $table_group_id (必须) 游戏区 ID
@param $table_name (必须) 表名
@param $record (必须) 待设置的目标记录 该操作包含插入和修改的语义
@param $ReturnValues (可选) 校验字符串, 服务端返回同样的字符串
@param $resultflag (可选) 默认值1，设置响应包的内容模式，取值范围如下:
            0: 应答中仅包含请求成功或失败
            1: 应答中包含与请求一致的值
            2: 应答中包含被修改的数据的所有字段最新值
            3: 应答中包含记录被修改前的值

public function set($table_group_id, $table_name, array $record, $ReturnValues = 'TcaplusDB', $resultflag = 1)

fieldSet

根据主键更新指定字段的值，指定更新字段参考$field_path。

@param $table_group_id (必须) 游戏区 ID
@param $table_name (必须) 表名
@param $record (必须) 待设置的目标记录 该操作包含插入和修改的语义
@param $field_path (必须) - 待设置的字段名(路径)数组, 嵌套字段可以通过点分路径的方式指定
@param $ReturnValues (可选) 校验字符串, 服务端返回同样的字符串
@param $resultflag (可选) 默认值1，设置响应包的内容模式，取值范围如下:
            0: 应答中仅包含请求成功或失败
            1: 应答中包含与请求一致的值
            2: 应答中包含被修改的数据的所有字段最新值
            3: 应答中包含记录被修改前的值

public function fieldSet($table_group_id, $table_name, array $record, $field_path, $ReturnValues = 'TcaplusDB', $resultflag = 1)

fieldInc

根据主键更新指定字段的值（自增或自减)，仅针对数值类型字段。如 pay.method 原始值为200，请求值若为50，则最终值为250；请求值若为-50，则最终值为150。

注意：

自减仅针对有符号型字段，如int32、int64。

@param $table_group_id (必须) 游戏区 ID
@param $table_name (必须) 表名
@param $record (必须)  待自增、自减的记录，必须保证记录中包含主键，待自增、自减的记录必须是整数类型
@param $ReturnValues (可选) 校验字符串, 服务端返回同样的字符串
@param $resultflag (可选), 默认值1，设置响应包的内容模式，取值范围如下:
            0: 应答中仅包含请求成功或失败
            1: 应答中包含与请求一致的值
            2: 应答中包含被修改的数据的所有字段最新值
            3: 应答中包含记录被修改前的值
@param $dataVersion (可选) 版本号
@param $dataVersionCheck (可选) 数据版本检查策略，取值范围:
    1 : 表示版本号一致才能会写入
    2 : 不检测版本号，强制将客户端传入的版本号设置到存储层
    3 : 默认值，不校验版本号，写操作会将存储层数据版本号+1

public function fieldInc($table_group_id, $table_name, array $record, $ReturnValues = 'TcaplusDB', $resultflag = 2, $dataVersion = -1, $dataVersionCheck = 3)

delete

删除指定主键的记录。

@param $table_group_id (必须) 游戏区 ID
@param $table_name (必须) 表名
@param $record (必须)  待删除的目标记录，可以只需要设置主键字段
@param  $ReturnValues (可选) 校验字符串, 服务端返回同样的字符串
@param $resultflag(可选)  默认值1，设置响应包的内容模式，取值范围如下:
            0: 应答中仅包含请求成功或失败
            1: 应答中包含与请求一致的值
            2: 应答中包含被修改的数据的所有字段最新值
            3: 应答中包含记录被修改前的值

public function delete($table_group_id, $table_name, array $record, $ReturnValues = 'TcaplusDB', $resultflag = 1)

demo.php 使用方法

为方便用户快速体验 TcaplusDB SDK 功能， 目前所有接口已经封闭成函数统一放在 demo.php，共8个函数，可以按需执行对应的函数，只需要注释其它函数即可，执行命令如下：

php -f  "demo.php"
目录
中国站