PROTOBUF 说明

PB (PROTO) 表是基于 PROTOBUF 协议设计的 TcaplusDB 表，PROTOBUF 协议是 Google 开源的通用 RPC 通信协议，用于 TcaplusDB 存储数据的序列化、反序列化等操作，具体关于 PROTO 表的定义说明可参考章节：表定义语言(PB, TDR)。PROTO 表定义以 protobuf 格式来定义表结构，支持丰富的数据类型, 可参考 protobuf 支持的类型。

入门

快速入手 PROTOBUF 协议表的开发涉及几个步骤，下面介绍如何基于 TcalusDB 的腾讯云环境或本地 Docker 版环境，快速上手基于 C++ 进行 PROTO 表的增删查改操作。所有操作均在申请的开发测试机或云主机进行。

环境要求

SDK 部署环境要求

机器配置: 建议 2c4g, Centos7 64bit, 腾讯云 CVM
GCC 版本: 4.8.5 以上
protobuf 版本: 3.5.0 以上
TcaplusDB SDK 版本 : 3.46.0 以上

其它要求 (非必须)

TcaplusDB 除了腾讯云环境,也支持本地版环境.本地环境主要用于开发调试. 对于本地版环境,需要额外部署 docker 环境.
具体请参考资料：[Linux] TcaplusDB Local版部署。

如果是基于 Docker 本地版进行 SDK 调试, 可以参考上述链接文档进行相关操作. TcaplusDB 还提供了 tcapluscli 工具进行相关资源操作, 如资源创建,删除,查看. 具体可查阅:TcaplusDB CLI工具.

SDK 依赖安装

系统依赖库安装

SDK 依赖一些系统库,主要如下:

autoconf
automake
libtool
curl
make
g++
unzip
gcc-c++
openssl
openssl-devel
zlib-devel

可通过 yum 一建安装:

yum install -y autoconf automake libtool curl make g++ unzip gcc-c++ openssl openssl-devel zlib-devel

依赖安装完后,有一些 lib 需要手动创建一下软链:

cd /usr/lib64
#查看当前libcrypto.so前缀库名
ls libcrypto.so.*
#以libcrypto.so.1.0.2k举例,将此so建软链
ln -s /usr/lib64/libcrypto.so.1.0.2k /usr/lib64/libcrypto.so

protobuf 安装

需要下载源码编译安装,或安装已经编译好的 protobuf. 版本要求:3.5.0以上. 下载地址: protobuf-cpp-3.5.0.tar.gz. 具体源码编译安装步骤:

./configure --prefix=/usr/local/protobuf
make
make check
make install

注:如果编译过程有问题,一般是少系统库问题,可参阅网上资料解决.

安装完后, 可测试是否 ok. 进/usr/local/protocbuf/bin 目录,执行:

./protoc --version
# 显示版本号
libprotoc 3.5.0

SDK 安装

下载 TcaplusDB C++ PB SDK. 下载方式: TcaplusPbApi3.46.0.

TcaplusDB 资源准备

TcaplusDB 表准备

准备 PROTO 表示例文件

这里以示例中的 game_players.proto 举例，表名: tb_online, 表类型: GENERIC。文件具体内容如下：

syntax = "proto3";
package myTcaplusTable;
//import tcaplusdb extensions
import "tcaplusservice.optionv1.proto";
message tb_online {
    //define primary key
    option(tcaplusservice.tcaplus_primary_key) = "openid,tconndid,timekey";
    //primary key fields
    int32 openid = 1; //QQ Uin
    int32 tconndid = 2;
    string timekey = 3;
    //non-primary key fields
    string gamesvrid = 4;
    int32 logintime = 5 ;
    repeated int64 lockid = 6;
    pay_info pay = 7;
    message pay_info {
        uint64 total_money = 1;
        uint64 pay_times = 2;
    }
    map<string, pay_info> projects = 8;
}

将上述文件内容保存为table_test.proto。

TcaplusDB 表创建-OMS

TcaplusDB 表创建-Docker 环境

对于需要本地开发调试的用户,TcaplusDB 也提供 docker 环境进行示例操作.

步骤 1-获取集群信息

查看 PROTO 集群(业务)信息. 对于 Docker 本地版，集群已经默认创建好一个供大家使用，所以不用再创建集群。对于 PROTO 集群，已经默认创建一个pb_app的业务，集群接入 ID (AccessID) 默认为3。

步骤 2-获取表格组信息

查看表格组(游戏区)信息. 对于 Docker 本地版, 已经默认在pb_app集群(业务)下创建了一个表格组(游戏区), 默认 ID 为1. 如果用户想自行创建, 可参考TcaplusDB CLI工具, 手册中有描述如何创建表格组.

步骤 3-创建表

创建表. 针对上述示例 proto 表定义文件 table_test.proto. 用 tcapluscli 工具进行创建.

#查看表创建命令提示帮助
./tcapluscli table -h
#创建一个表, 指定endpoint-url, 表格组id: group-id, 表类型: PROTO, 表定义文件:table_test.proto, 放当前路径, 如果用户自行创建了表格组,则group-id替换为自己创建的id即可
./tcapluscli table create  create --endpoint-url=http://localhost --access-id=3 --group-id=1 --schema-type=PROTO --schema-file=table_test.proto

备注:如果表创建提示失败, 一般有几类原因:

Error1: 集群 access-id 出错, 默认为 3, 填其它如果未创建有问题
Error2: 表格组 group-id 出错, 默认为 1, 如果用户自己创建了表格组,这里需要替换为自己创建的表格组 id
Error3: schema-type 出错, 业务默认为 PROTO, 如果填其它则报错
Error4: schema-file 出错, 可能找不到 shcema file, 建议把 proto 文件放在和 tcapluscli 同目录下

示例代码

以 C++ 示例代码为例，介绍如何使用 PROTOBUF 接口进行 TcaplusDB 表数据操作，这里主要介绍 Generic 类型表操作。

步骤 1-SDK 下载

参考上述 SDK 下载部分. 解压 SDK 到机器对应目录.

cd /root
tar zxvf TcaplusPbApi3.46.0.199033.x86_64_release_20201210.tar.gz

步骤 2-集群连接信息获取

示例代码中涉及连接 TcalusDB 部分, 连接信息配置在 SDK 目录:

/root/TcaplusPbApi3.46.0.199033.x86_64_release_20201210/release/x86_64/examples/tcaplus/C++_common_for_pb2/common.h

修改配置信息如下:

/*********************测试例子前需要用户手动修改的地方BEGIN**************************************/// 目标业务的tcapdir地址, 即集群地址, 获取方式, 腾讯云参考: https://cloud.tencent.com/document/product/596/31652, docker环境: ip (docerk机器ip):9999static const char DIR_URL_ARRAY[][TCAPLUS_MAX_STRING_LENGTH] ={    "tcp://172.17.32.17:9999",};// 目标业务的tcapdir 地址个数, 默认1个static const int32_t DIR_URL_COUNT = 1;// 目标业务的表名static const char * TABLE_NAME = "tb_online";// 目标业务的App ID, 即集群接入ID, 腾讯云参考: https://cloud.tencent.com/document/product/596/31652, docker环境: 3 (默认proto业务)static const int32_t APP_ID = 70;// 目标业务的Zone ID, 表格组id, 腾讯云参考: https://cloud.tencent.com/document/product/596/31652, docker环境: 1 (默认1, 也可自行创建)static const int32_t ZONE_ID = 1;// 目标业务的业务密码, 腾讯云参考: https://cloud.tencent.com/document/product/596/31652, docker环境: 进web控制台,业务管理->业务维护->选中pb_app业务,查看密码static const char * SIGNATURE = "Tcaplus@2020";/*********************测试例子前需要用户手动修改的地方END**************************************/

步骤 3-配置环境变量

以 SDK 中如下目录示例举例:

#pb3协议, add操作/root/TcaplusPbApi3.46.0.199033.x86_64_release_20201210/release/x86_64/examples/tcaplus/C++_pb3_coroutine_simpletable/SingleOperation/add

envcfg.env: 配置 PROTOBUF_HOME 和 TCAPLUS_HOME 环境变量

export PROTOBUF_HOME=/usr/local/protobuf;export TCAPLUS_HOME=/root/TcaplusPbApi3.46.0.199033.x86_64_release_20201210/release/x86_64/;

步骤 4-生成表接口定义代码

示例目录

cd /root/TcaplusPbApi3.46.0.199033.x86_64_release_20201210/release/x86_64/examples/tcaplus/C++_pb3_coroutine_simpletable/SingleOperation/add

生成接口定义
```
sh conv.sh
```

步骤 5-修改 Makefile

示例:

# ================================================================#Makefile for tcaplus example## Date:   2016-09-14## Copyright (C) 2016 Architechure IRED TENCENT## ================================================================CPPFILE=$(wildcard *.cpp)CCFILE=$(wildcard *.cc)#GENERATE_FILE=$(shell ./conv.sh )# ${PROTOBUF_HOME} change to ${PROTOBUF_HOME}/libLIBS += -L $(PROTOBUF_HOME)/lib -L$(TCAPLUS_HOME)/lib -Wl,-Bstatic -ltcaplusprotobufapi -lprotobuf -lscew -lexpat -Wl,-Bdynamic -lpthread -lz -ldl -lcrypto -lanl# ${PROTOBUF_HOME} change to ${PROTOBUF_HOME}/includeINC =-I$(PROTOBUF_HOME)/include -I$(TCAPLUS_HOME)/include/tcaplus_pb_api/ -I../../../C++_common_for_pb2.PHONY: all cleanall:    g++ -o mytest $(CCFILE) $(CPPFILE) $(INC) ${LIBS}clean:    rm -f mytest     mytest.log*

步骤 6-执行示例

./mytest

步骤 7-查看插入数据

TcaplusDB 提供有 tcaplus_client 工具进行数据查看, 在 SDK 目录下有对应的tcaplus_client. 具体使用参考:TcaplusDB Client.

cd /root/TcaplusPbApi3.46.0.199033.x86_64_release_20201210/release/x86_64/bin#demo connect, -a: access-id/appid, -z: tablegroup-id/zone-id, -s: password, -d: connect address./tcaplus_client -a 3 -z 1 -s ABCDEFEFEF -d 172.17.12.1:9999#demo select, specify primary key of tableselect * from tb_online where openid=1 and tconndid=2 and timekey='12345';

备注: **tcaplus_client 和 tcapluscli 的区别是: tcaplus_client 主要是数据层的操作工具( 如数据的增删查改), tcapluscli 主要是资源层的操作(如表/表格组/集群的创建,删除,查询)**TcaplusDB是腾讯出品的分布式NoSQL数据库，存储和调度的代码完全自研。具备缓存+落地融合架构、PB级存储、毫秒级时延、无损水平扩展和复杂数据结构等特性。同时具备丰富的生态、便捷的迁移、极低的运维成本和五个九高可用等特点。客户覆盖游戏、互联网、政务、金融、制造和物联网等领域。

【TcaplusDB知识库】C++快速上手PB表的增删查改操作