tencent cloud

游戏数据库 TcaplusDB

产品动态
产品简介
产品概述
产品优势
应用场景
产品架构
地域介绍
购买指南
产品定价
欠费说明
快速入门
了解基本概念
创建集群
创建表格组
创建表格
获取连接信息
访问 TcaplusDB
操作指南
管理集群与表格组
管理表格
监控与告警
访问管理
标签
任务列表
使用 TcaplusDB client
使用 client 工具访问数据
client 工具命令参考
使用 TcaplusDB SDK
变更历史
SDK 下载
SDK for C++ 接口说明
TcaplusDB 错误码
SDK 安装
PB 表 C++SDK 操作方法
TDR 表 C++SDK 操作方法
使用 TcaplusDB RESTful API
RESTful API 接口说明
Go RESTful API 接口说明
Java RESTful API 接口说明
PHP RESTful API 接口说明
Python RESTful API 接口说明
RESTful API 各语言示例下载
实践教程
表结构设计
数据库交互
常见问题
信息咨询类
数据库使用类
数据库原理类
API 文档
History
Introduction
API Category
Making API Requests
Table Group APIs
Other APIs
Table APIs
Cluster APIs
Data Types
Error Codes
相关协议
服务等级协议
服务条款
词汇表
联系我们

Protobuf 表定义

PDF
聚焦模式
字号
最后更新时间: 2024-12-04 09:56:32
TcaplusDB 支持2种表定义格式,protobuf(Protocol Buffers)表 TDR(Tencent Data Representation)表。 Protobuf 是 Google 开发的一种描述性语言,针对结构化数据进行序列化,同时强调数据结构的简单化和性能。 TDR 是由腾讯开发的跨平台数据表示语言,结合了 XML,二进制和 ORM(对象关系映射)的优势,在腾讯游戏数据的序列化场景中广泛使用。 两者在使用上没有根本性的变化,请根据具体业务使用习惯选择表定义语言。 本文主要描述 Protobuf 表定义语言的定义形式。

ProtoBuf 表

TcaplusDB 创建表,首先需要使用表描述语言定义表的格式。将表格定义内容写入文件中,此文件被称之为表的 IDL 描述文件。 ProtoBuf 表的 IDL 描述文件根据 Protocol Buffers 的规则来进行表格定义。 主要分为以下3类定义:
文件定义信息
表定义信息
嵌套类型信息

文件定义信息

文件定义信息区域主要定义当前表描述文件的公共信息。主要涉及3种类型的内容。
选项名称
功能说明
值示例
必填
syntax
指明当前文件书写的语法规范版本
支持 proto2,proto3
package
指明当前文件自定义包名,包名可以避免对 message 类型之间的名字冲突。
包名信息
import
引入 Tcaplus 表的一些公共信息,必须在您的表定义中被引用
tcaplusservice.optionv1.proto

表定义信息

表定义信息主要通过 message 定义表的格式,在 message 种可对表的扩展信息进行定义,也可以对表的字段信息进行定义。

扩展信息定义

同时也可以在 protobuf 语法基础上通过 option 进行扩展,可以实现更丰富的语义功能,可定义的内容如下表所示。 详细的定义格式为:option(tcaplusservice.选项) = "值";
选项名称
功能说明
设置示例
必填
tcaplus_primary_key
设置 TcaplusDB 表主键字段
option(tcaplusservice.tcaplus_primary_key) = "uin,name,region";
tcaplus_index
设置 TcaplusDB 表索引键字段
option(tcaplusservice.tcaplus_index) = "index_1(uin,region)";
tcaplus_sharding_key
用户可以自定义表分片键
option(tcaplusservice.tcaplus_sharding_key) = "uin";
tcaplus_field_cipher_suite
如果需要使用字段加密功能,需要设置,如果用户需要指定自己的加密算法,请参考 API 中的例子
option(tcaplusservice.tcaplus_field_cipher_suite) = "DefaultAesCipherSuite";
tcaplus_cipher_md5
如果需要使用字段加密功能,需要设置用户侧保存加密密码字符串的 MD5
option(tcaplusservice.tcaplus_cipher_md5)= "62fee3b53619b7f303c939964c6f2c4b";

字段信息定义

TcaplusDB 定义字段的格式为:字段修饰符 字段类型 字段名称 = 标识号[特殊定义];
字段修饰符
proto2 支持3种类型的限定修饰符,proto3可不再支持 required 修饰,默认为 optional 类型。
required:表示字段为必填字段。proto2中主键字段必须被 required 修饰。
optional:表示此字段为可选字段,支持设定字段的默认值
repeated :表示该字段可以包含0~N 个元素。其特性和 optional 一样,但是每一次可以包含多个值。可以看作是在传递一个数组的值,必须指定[packed = true]的特殊定义。
字段类型
TcaplusDB 支持普通字段以及嵌套型字段,详细的字段介绍可参考字段类型
字段名称
针对当前属性而进行对字段进行命名,支持大小写字母,数字与下划线。建议字段的命名采用驼峰式命名方式,不能以数字开头。
标识号
标识号使用范围:[1,2^29 - 1] 不可使用 [19000-19999] 标识号, 因为 Protobuf 协议实现中对这些标识号进行了预留。假若使用,则会报错 每个字段在进行编码时都会占用内存,而 占用内存大小 取决于 标识号:
范围 [1,15] 标识号的字段 在编码时占用1个字节;
范围 [16,2047] 标识号的字段 在编码时占用2个字节
特殊定义
当 repeated 修饰的字段需要指定 packed=true 选项。用法如下:
repeated int64 lockid = 6 [packed = true];
使用 optional 修饰的字段可以通过 default = 1指定其默认值。用法如下:
optional int32 logintime = 5 [default = 1];
字段类型为 string 和 bytes 类型的字段可以指定为加密字段。用法如下:
required string name = 2[(tcaplusservice.tcaplus_crypto) = true];

嵌套类型信息

TcaplusDB 支持嵌套类型,嵌套类型可以包含另一个嵌套类型作为其字段。也可以在嵌套类型内定义一个新的嵌套类型。 嵌套类型的定义与表的定义相似,均是通过 message 进行声明,但是结构体中不能包含扩展信息定义,如“主键”,“索引”等定义。 TcaplusDB 支持最多128层连续嵌套,但是不建议大量使用嵌套,嵌套层数过多会导致数据访问性能降低。

proto2 表描述文件示例

以下是一个符合 proto2 语法规范的表描述文件。
syntax = "proto2"; // 指明符合proto2语法规范
package myTcaplusTable; // 自定义包名

import "tcaplusservice.optionv1.proto"; // 这个文件定义了Tcaplus表的一些公共信息,需要在您的表定义中被引用(import)

message player { //使用message定义表,message名即表名

// 必须是指定了主键选项(tcaplusservice.tcaplus_primary_key)的message才能被识别为一张TcaplusDB业务数据表,否则此message只是一个结构体
// 主键选项指定了主键字段名列表,字段名用逗号分割,最多四个字段能够被指定为主键
option(tcaplusservice.tcaplus_primary_key) = "uin,name,region";

// tcaplusservice.tcaplus_index选项指定Tcaplus索引
// 每个索引所包含的索引键必须是主键,并且所有索引字段集合的交集不能为空
option(tcaplusservice.tcaplus_index) = "index_1(uin,region)";
option(tcaplusservice.tcaplus_index) = "index_2(uin,name)";

//option(tcaplusservice.tcaplus_sharding_key) = "uin"; 用户可以自己显式设置索引分片字段。如果用户不显式设置,那系统将默认采用主键字段作为分片字段。

option(tcaplusservice.tcaplus_field_cipher_suite) = "DefaultAesCipherSuite"; // 使用默认的DefaultAesCipherSuite加密函数,非必须设置选项。
option(tcaplusservice.tcaplus_cipher_md5)= "62fee3b53619b7f303c939964c6f2c4b"; //设置加密密码字符串的md5值,非必须设置选项。

// 接下来是表的字段定义
// TcaplusDB 表支持以下的数据类型:
// 非嵌套类型:int32, int64, uint32, uint64, sint32, sint64, bool, fixed64, sfixed64, double, fixed32, sfixed32, float, string, bytes
// 嵌套类型:message
// Tcaplus支持REQUIRED, OPTIONAL和REPEATED作为字段修饰符

// 主键字段 (最多4个)
required int64 uin = 1; // 主键字段必须被required类型修饰,并且不能是嵌套类型
required string name = 2[(tcaplusservice.tcaplus_crypto) = true]; //message中string和bytes类型的字段可以指定为加密字段,非必须设置选项
required int32 region = 3;
// 一张表最多只能包含4个主键字段

// 普通值字段
required int32 gamesvrid = 4; // 普通字段可以被required,optional或repeated类型修饰
optional int32 logintime = 5 [default = 1];
repeated int64 lockid = 6 [packed = true]; // repeated修饰的字段需要指定packed=true选项
optional bool is_available = 7 [default = false]; //optional类型字段可以指定默认值
optional pay_info pay = 8; // 值字段的类型可以是自定义的结构体类型
}

message pay_info { //使用message定义结构体

required int64 pay_id = 1;
optional uint64 total_money = 2;
optional uint64 pay_times = 3;
optional pay_auth_info auth = 4;

message pay_auth_info { // 结构体类型支持嵌套定义
required string pay_keys = 1;
optional int64 update_time = 2;
}
}

proto3 表描述文件示例

以下是一个符合 proto3 语法规范的表描述文件。
syntax = "proto3"; // 指明符合proto3语法规范
package myTcaplusTable; // 自定义包名

import "tcaplusservice.optionv1.proto"; // 这个文件定义了Tcaplus表的一些公共信息,需要在您的表定义中被引用(import)

message player { //使用message定义表,message名即表名

// 必须是指定了主键选项(tcaplusservice.tcaplus_primary_key)的message才能被识别为一张TcaplusDB业务数据表,否则此message只是一个结构体
// 主键选项指定了主键字段名列表,字段名用逗号分割,最多四个字段能够被指定为主键
option(tcaplusservice.tcaplus_primary_key) = "uin,name,region";

// tcaplusservice.tcaplus_index选项指定Tcaplus索引
// 每个索引所包含的索引键必须是主键,并且所有索引字段集合的交集不能为空
option(tcaplusservice.tcaplus_index) = "index_1(uin,region)";
option(tcaplusservice.tcaplus_index) = "index_2(uin,name)";

//option(tcaplusservice.tcaplus_sharding_key) = "uin"; 用户可以自己显式设置分片字段,如果用户不显式设置,那系统将默认采用主键字段为分片字段。

option(tcaplusservice.tcaplus_field_cipher_suite) = "DefaultAesCipherSuite"; // 使用默认的DefaultAesCipherSuite加密函数,非必须设置选项
option(tcaplusservice.tcaplus_cipher_md5)= "62fee3b53619b7f303c939964c6f2c4b"; //设置加密密码字符串的md5值,非必须设置选项

// 接下来是表的字段定义
// Tcaplus 表支持以下的数据类型:
// 非嵌套类型:int32, int64, uint32, uint64, sint32, sint64, bool, fixed64, sfixed64, double, fixed32, sfixed32, float, string, bytes
// 嵌套类型:message

// 主键字段 (最多4个)
int64 uin = 1; // 主键字段必须是非嵌套类型
string name = 2[(tcaplusservice.tcaplus_crypto) = true]; //message中string和bytes类型的字段可以指定为加密字段,非必须设置选项
int32 region = 3;
// 一张表最多只能包含4个主键字段

// 普通值字段
int32 gamesvrid = 4;
int32 logintime = 5;
int64 lockid = 6;
bool is_available = 7;
pay_info pay = 8; // 值字段的类型可以是自定义的结构体类型
}

message pay_info { //使用message定义结构体

int64 pay_id = 1;
uint64 total_money = 2;
uint64 pay_times = 3;
pay_auth_info auth = 4;

message pay_auth_info { // 结构体类型支持嵌套定义
string pay_keys = 1;
int64 update_time = 2;
}
}


帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈