tencent cloud

To help you use Java to manipulate TcaplusDB tables, we encapsulated the SDK for Java based on RESTful APIs. This document describes how to use RESTful APIs for Java to manipulate TcaplusDB PB tables (based on the protobuf protocol).

Preparations

1. Create a TcaplusDB table

Create a sample TcaplusDB table game_players.proto. For more information, please see Creating Table.

2. Create a CVM instance

• Create a CVM instance to run the SDK demo. We recommend the following configuration: 1 CPU core, 2 GB memory, and CentOS 7. The CVM instance needs to be in the same VPC as that of the TcaplusDB instance.
• Download the installation package of the RESTful API SDK for Java here.

3. Prepare the Java environment

The SDK is dependent on Java 1.8 or above. If the OS of the CVM instance is CentOS 7 or above, you can simply run yum install -y java.

4. API description

Currently, the SDK supports eight APIs, which are as detailed below:

Directions

Upload the entire SDK package tcaplusdb-restapi-java-sdk-1.0-assembly.zip to the CVM instance directory. For more information, please see Copying Local File to CVM. After decompression, the directory name will be tcaplusdb-restapi-java-sdk-1.0.

1. Prepare configuration

The configuration file is in tcaplusdb-restapi-java-sdk-1.0/conf/config.properties, and its content is as follows:

#replace with your table endpoint
endpoint=http://10.xx.xx.16

#replace with your table access id
access_id=60

#replace with your table access password
access_password=Tcaxxx19

#replace with your table group id
table_group_id=1

#replace with your table name
table_name=game_players

#optional, configure the returning fields for GetRecord API, multiple fields with comma delimeter
get_select_fields=

#required, configure the returing fields for FieldGetRecord API
field_get_select_fields=game_server_id,is_online

#optional, configure the returning fields for PartkeyGetRecord API
part_key_get_select_fields=game_server_id,is_online

#required, configure the updating fields for FieldSetRecord API
field_set_fields=game_server_id,pay.amount

#required, configure the index keys for PartkeyGetRecord API
part_key_index_keys=player_id,player_name

#required, configure the index name for PartkeyGetRecord API
part_key_index_name=index_1

#optional, configure the limit number of records per request to return for PartkeyGetRecord API, value range: >0
part_key_limit = 10

#optional, configure the offset position to return for PartkeyGetRecord API, value range: >=0
part_key_offset = 0

2. Prepare data

The demo provides separately prepared testing data for each RESTful API, which is stored in the tcaplusdb-restapi-java-sdk-1.0/conf directory as JSON files.

3. Execute the script

The main execution scripts are in tcaplusdb-restapi-java-sdk-1.0/bin/run.sh and can be run as follows:

# Add a record
sh bin/run.sh add
# Get a record
sh bin/run.sh get
# Update a record
sh bin/run.sh set
# Delete a record
sh bin/run.sh delete
# Update specified fields
sh bin/run.sh field_set
# Get specified fields
sh bin/run.sh field_get
# Update the values of specified fields (in numeric type)
sh bin/run.sh field_inc
# Get a record based on the index
sh bin/run.sh partkey_get

API Data Description

addRecord

This API is used to add a record. The inserted data is in JSON format as shown below:

{"player_id":1,"player_name":"test","player_email":"test@email.com", "game_server_id":2,"login_timestamp":[],"logout_timestamp":[],"is_online":true,"pay":{"pay_id":1,"amount":20,"method":3}}

getRecord

This API is used to query a record by specifying the primary key field. The data is in JSON format as shown below:

{"player_id":1,"player_name":"test","player_email":"test@email.com"}

The query API also allows you to specify the list of fields to be returned. The get_select_fields configuration item defined in the config.properties configuration file is used to specify the names of the fields to be returned. If it is left empty, all fields of the record will be returned by default; otherwise, the values of the specified fields will be returned.

setRecord

This API is used to update a record, and the record to be updated must contain a primary key field. The data is in JSON format as shown below:

{"player_id":1,"player_name":"test","player_email":"test@email.com", "game_server_id":2,"login_timestamp":[],"logout_timestamp":[],"is_online":false,"pay":{"pay_id":1,"amount":30,"method":3}}

deleteRecord

This API is used to delete a record. The entered data must contain a primary key field. The data is in JSON format as shown below:

{"player_id":1,"player_name":"test","player_email":"test@email.com"}

fieldSetRecord

This API is used to update the values of specified fields. The entered data must contain a primary key field. The data is in JSON format as shown below:

{"player_id":1,"player_name":"test","player_email":"test@email.com", "game_server_id":3,"is_online":false, "login_timestamp":[],"logout_timestamp":[],"pay":{"pay_id":1,"amount":40,"method":3}}

At the same time, you need to specify the names of the fields to be updated in the field_set_fields configuration item defined in the config.properties configuration file. Multiple fields should be separated with commas, and the value cannot be empty.

fieldGetRecord

This API is used to get the values of specified fields. The entered data must contain a primary key field. The data is in JSON format as shown below:

{"player_id":1,"player_name":"test","player_email":"test@email.com"}

At the same time, you need to specify the names of the fields to be obtained in the field_get_select_fields configuration item defined in the config.properties configuration file, and the value cannot be empty.

fieldIncRecord

This API is used to update the values of specified fields. Different from the fieldSetRecord API, it can update field values only in numeric type, such as increasing or decreasing a value. The entered data must contain a primary key field and the numeric fields to be updated. The data is in JSON format as shown below:

{"player_id":1,"player_name":"test","player_email":"test@email.com", "pay":{"amount":50}}

Suppose the initial value of pay.amount is 100, and the value of the input parameter in the request is 50, then the final value will be 150.

partkeyGetRecord

This API is used to get the corresponding record based on the specified index. Multiple records may be matched, and you can specify the fields to be returned. The entered data must contain an index field. The data is in JSON format as shown below:

{"player_id":1,"player_name":"test","player_email":"test@email.com"}

At the same time, you need to specify the corresponding index name and index field names in the part_key_index_name and part_key_index_keys configuration items defined in the config.properties configuration file, respectively. The two configuration items cannot be empty.

To return specified fields, you can configure part_key_get_select_fields in the configuration file; otherwise, leave it empty.

For this API, the maximum size of a packet returned by one request is 256 KB, and the limit value is subject to the size of one single record. We recommend you set it as follows:

• If the size of one single record is smaller than 256 KB, you can set limit to 256 KB / record size; for example, if the record size is 10 KB, we recommend you set limit to a value between 20 and 25.
• If the size of one single record is greater than or equal to 256 KB, set limit to 1, i.e., only one record will be returned by one request.

In scenarios where limit and offset are set, to get the full data based on the index key, you need to judge whether the obtained data is complete based on the TotalNum and RemainNum flags returned in the response packet.

You can set limit and offset in the following steps:

# Step 1. Prepare batch demo data and set the values of `limit` and `offset` as instructed in `conf/batch_add_data.json`.
part_key_limit = 2
part_key_offset = 0

# Step 2. Add demo data in batches. Run the `batch_add` command to add three records.
sh bin/run.sh batch_add

# Step 3. Call the `partkey_get` command, and `partkeyGetRecord` will be executed twice: in the first execution, `limit` and `offset` are not set; in the second execution, `limit` and `offset` are set. Check the differences between the two execution results.
sh bin/run.sh partkey_get

# Step 4. The response data with `limit` and `offset` not set is as follows, which contains four data entries in total:
{"MultiRecords":[{"RecordVersion":3,"Record":{"game_server_id":3,"is_online":true,"player_email":"test@email.com","player_id":1,"player_name":"test"}},{"RecordVersion":1,"Record":{"game_server_id":3,"is_online":true,"player_email":"test1@email.com","player_id":1,"player_name":"test"}},{"RecordVersion":1,"Record":{"game_server_id":4,"is_online":true,"player_email":"test2@email.com","player_id":1,"player_name":"test"}},{"RecordVersion":1,"Record":{"game_server_id":5,"is_online":true,"player_email":"test3@email.com","player_id":1,"player_name":"test"}}],"TotalNum":4,"RemainNum":0,"ErrorCode":0,"ErrorMsg":"Succeed"}

# Step 5. The response data with `limit` and `offset` set is as follows, which contains only two data entries subject to the `limit` value:
{"MultiRecords":[{"RecordVersion":3,"Record":{"game_server_id":3,"is_online":true,"player_email":"test@email.com","player_id":1,"player_name":"test"}},{"RecordVersion":1,"Record":{"game_server_id":3,"is_online":true,"player_email":"test1@email.com","player_id":1,"player_name":"test"}}],"TotalNum":4,"RemainNum":2,"ErrorCode":0,"ErrorMsg":"Succeed"}