AppId (cluster access ID), ZoneId (table group ID), and AppKey (cluster access password). Currently, TcaplusDB RESTful API only supports tables defined through protobuf.http://{Tcaplus_REST_URL}/{Version}/apps/{AppId}/zones/{ZoneId}/tables/{TableName}/records
http://10.123.9.70/ver1.0/apps/2/zones/1/tables/tb_rest_test/records
x-tcaplus-pwd-md5
Fill in this field with the calculated MD5 of your app key, which is used to authenticate the client's access to the data.
Calculate the MD5 of the string by running the bash command:# echo -n "c3eda5f013f92c81dda7afcdc273cf82" | md5sum879423b88d153cace7b31773a7f46039 -
x-tcaplus-target specifies TcaplusDB RESTful API request operations, including:x-tcaplus-idl-type specifies the TcaplusDB table type. Currently, only the protobuf (pb) type is supported.x-tcaplus-data-version-check Specifies TcaplusDB data version check policy use with x-tcaplus-data-version. It can be set as:
x-tcaplus-data-version-check specifies the TcaplusDB data version check policy to implement the optimistic locking feature, which is to be used with x-tcaplus-data-version tagging. Valid values include:1: write operations can be performed only if the data version number at the client is identical to that at the storage layer. The version number will be increased by 1 each time this operation is performed.2: the relationship between the client version number and the server version number is ignored. The client version number will be forcibly set at the storage layer.3: the relationship between the client version number and the server version number is ignored. The version number at the storage layer will be increased by 1 each time the write operation is performed.Tcaplus.AddRecord and Tcaplus.SetRecord.x-tcaplus-data-version is used with x-tcaplus-data-version-check to set the data version number of the client. Valid values include:x-tcaplus-result-flag sets whether the response contains the complete data policy. Valid values include:0: the response only contains whether the request succeeded or failed.1: the response contains the same values as the request does.2: the response contains the latest values of all fields of the data that has been modified.3: the response contains the value before the record is modified.Request Data:{"ReturnValues": "...", // The data you configure to be retained, which will arrive at TcaplusDB with the request and be sent back as-is"Record": {... // For the format of data records, please see "API Samples".}}
GetRecord/SetRecord/AddRecord/DeleteRecord/FieldGetRecord/FieldSetRecord/FieldIncRecord operation returns a single data entry. The JSON response data is as below:Response Data{"ErrorCode": 0, // Return code"ErrorMsg": "Succeed", // Return message"RecordVersion": 1, // Data version number"ReturnValues": "...", // The data you configure to be retained, which will arrive at TcaplusDB with the request and be sent back as-is"Record": { // For the format of data records, please see "API Samples"....}}
PartkeyGetRecord operation may return multiple data entries. The JSON response data is as below:Response Data{"ErrorCode": 0, // Return code"ErrorMsg": "Succeed", // Return message"MultiRecords": [ // Array of multiple data entries{"RecordVersion": 1, // Version number of each data entry"Record": {...} // For the format of data records, please see "API Samples".},...],"RemainNum": 0, // Number of data entries not accessed yet"TotalNum": 5 // Total number of eligible data entries}
HTTP Status Code | Return Code | Return Message |
200 | 0 | Successful |
400 | -2579 | Data deserialization error |
401 | -279 | Authentication error |
400 | -11539 | Invalid request For the detailed reason, please see the return message field. |
400 | -2067 | Operation type mismatch |
400 | -1811 | Invalid parameter |
400 | -5395 | No primary key is set |
400 | -2323 | Data serialization error |
400 | -7949 | Invalid data version number This error generally occurs when the data version check policy is used in a write operation |
400 | -1293 | The record already exists |
404 | 261 | The record does not exist |
404 | -34565 | The index does not exist |
500 | - | Internal system error Please see the return message field |
GET /ver1.0/apps/{APP_ID}/zones/{ZONE_ID}/tables/{TABLE_NAME}/records?keys={JSONKeysObj}&select={JSONSelectObj}
key information in a TcaplusDB PB table. You will get the entire record by performing this operation. However, you can set the select variable to specify the fields to be returned in the response; otherwise, the information of all fields will be displayed. If no data records exist, an error will be returned.keys variable must be specified in the URI, which indicates the values of all primary keys. The optional select variable indicates the name of the field whose value you want to display. You can specify the fields in the nested structure by separating the path with a dot, such as pay.total_money.%20 instead of +.Name | Type | Value |
x-tcaplus-target | String | Tcaplus.GetRecord |
x-tcaplus-version | String | Tcaplus3.32.0 |
x-tcaplus-pwd-md5 | String | MD5 of AppKey(Password) |
x-tcaplus-idl-type | String | protobuf |
http://10.123.9.70:31002/ver1.0/apps/2/zones/1/tables/tb_example/records?keys={'region': 101, 'name': 'calvinshao', 'uin': 100}
http://10.123.9.70:31002/ver1.0/apps/2/zones/1/tables/tb_example/records?keys=%7B%22region%22%3A%20101%2C%20%22name%22%3A%20%22calvinshao%22%2C%20%22uin%22%3A%20100%7D
["x-tcaplus-target:Tcaplus.GetRecord","x-tcaplus-version:Tcaplus3.32.0","x-tcaplus-pwd-md5:c3eda5f013f92c81dda7afcdc273cf82","x-tcaplus-idl-type:protobuf"]
{"ErrorCode": 0,"ErrorMsg": "Succeed","RecordVersion": 1,"Record": {"name": "calvinshao","lockid": [50,60,70],"pay": {"pay_times": 2,"total_money": 10000,"pay_id": 5,"auth": {"pay_keys": "adqwacsasafasda","update_time": 1528018372}},"region": 101,"uin": 100,"is_available": true,"gamesvrid": 4099,"logintime": 404}}
PUT /ver1.0/apps/{APP_ID}/zones/{ZONE_ID}/tables/{TABLE_NAME}/records
key information. If the record already exists, an overwrite operation will be performed; otherwise, an insert operation will be performed.SetRecord operation supports setting the following values for resultflag:0: the response only contains whether the request succeeded or failed1: the response contains the same values as the request does2: the response contains the latest values of all fields of the data that has been modified3: the response contains the value before the record is modifiedName | Type | Value |
x-tcaplus-target | String | Tcaplus.SetRecord |
x-tcaplus-version | String | Tcaplus3.32.0 |
x-tcaplus-pwd-md5 | String | MD5 of AppKey(Password) |
x-tcaplus-result-flag | Int | 2 |
x-tcaplus-data-version-check | Int | 2 |
x-tcaplus-data-version | Int | -1 |
x-tcaplus-idl-type | String | protobuf |
http://10.123.9.70/ver1.0/apps/2/zones/1/tables/tb_example/records
["x-tcaplus-target:Tcaplus.SetRecord","x-tcaplus-version:Tcaplus3.32.0","x-tcaplus-pwd-md5:c3eda5f013f92c81dda7afcdc273cf82","x-tcaplus-result-flag:2","x-tcaplus-data-version-check:2","x-tcaplus-data-version:-1","x-tcaplus-idl-type:Protobuf"]
{"ReturnValues": "Send to tcaplus by calvinshao","Record": {"name": "calvinshao","lockid": [50,60,70,80,90,100],"pay": {"pay_times": 3,"total_money": 12000,"pay_id": 5,"auth": {"pay_keys": "adqwacsasafasda","update_time": 1528018372}},"region": 101,"uin": 100,"is_available": false,"gamesvrid": 4099,"logintime": 404}}
{"ErrorCode": 0,"ErrorMsg": "Succeed","RecordVersion": 1,"ReturnValues": "Send to tcaplus by calvinshao","Record": {"name": "calvinshao","lockid": [50,60,70,80,90,100],"pay": {"pay_times": 3,"total_money": 12000,"pay_id": 5,"auth": {"pay_keys": "adqwacsasafasda","update_time": 1528018372}},"region": 101,"uin": 100,"is_available": false,"gamesvrid": 4099,"logintime": 404}}
POST /ver1.0/apps/{APP_ID}/zones/{ZONE_ID}/tables/{TABLE_NAME}/records
key information. If the record already exists, an error will be returned.AddRecord operation supports setting the following values for resultflag:0: the response only contains whether the request succeeded or failed1: the response contains the same values as the request does2: the response contains the latest values of all fields of the data that has been modified3: the response contains the value before the record is modifiedName | Type | Value |
x-tcaplus-target | String | Tcaplus.SetRecord |
x-tcaplus-version | String | Tcaplus3.32.0 |
x-tcaplus-pwd-md5 | String | MD5 of AppKey(Password) |
x-tcaplus-result-flag | Int | 1 |
x-tcaplus-idl-type | String | protobuf |
http://10.123.9.70/ver1.0/apps/2/zones/1/tables/tb_example/records
["x-tcaplus-target:Tcaplus.AddRecord","x-tcaplus-version:Tcaplus3.32.0","x-tcaplus-pwd-md5:c3eda5f013f92c81dda7afcdc273cf82","x-tcaplus-result-flag:1","x-tcaplus-idl-type:protobuf"]
{"ReturnValues": "Send to tcaplus by calvinshao","Record": {"name": "calvinshao","lockid": [50,60,70],"pay": {"pay_times": 2,"total_money": 10000,"pay_id": 5,"auth": {"pay_keys": "adqwacsasafasda","update_time": 1528018372}},"region": 101,"uin": 100,"is_available": true,"gamesvrid": 4099,"logintime": 404}}
{"ErrorCode": 0,"ErrorMsg": "Succeed","RecordVersion": 1,"ReturnValues": "Send to tcaplus by calvinshao","Record": {"name": "calvinshao","lockid": [50,60,70],"pay": {"pay_times": 2,"total_money": 10000,"pay_id": 5,"auth": {"pay_keys": "adqwacsasafasda","update_time": 1528018372}},"region": 101,"uin": 100,"is_available": true,"gamesvrid": 4099,"logintime": 404}}
DELETE /ver1.0/apps/{APP_ID}/zones/{ZONE_ID}/tables/{TABLE_NAME}/records
key information. If the data does not exist, an error will be returned.DeleteRecord operation supports setting the following values for resultflag:0: the response only contains whether the request succeeded or failed1: the response contains the same values as the request does2: the response contains the latest values of all fields of the data that has been modified3: the response contains the value before the record is modifiedName | Type | Value |
x-tcaplus-target | String | Tcaplus.SetRecord |
x-tcaplus-version | String | Tcaplus3.32.0 |
x-tcaplus-pwd-md5 | String | MD5 of AppKey(Password) |
x-tcaplus-result-flag | Int | 1 |
x-tcaplus-idl-type | String | protobuf |
http://10.123.9.70/ver1.0/apps/2/zones/1/tables/tb_example/records
["x-tcaplus-target:Tcaplus.DeleteRecord","x-tcaplus-version:Tcaplus3.32.0","x-tcaplus-pwd-md5:c3eda5f013f92c81dda7afcdc273cf82","x-tcaplus-result-flag:1","x-tcaplus-idl-type:protobuf"]
{"ReturnValues": "Send to tcaplus by calvinshao","Record": {"region": 101,"name": "calvinshao","uin": 100}}
{"ErrorCode": 0,"Record": {},"RecordVersion": -1,"ReturnValues": "Send to tcaplus by calvinshao"}
GET /ver1.0/apps/{APP_ID}/zones/{ZONE_ID}/tables/{TABLE_NAME}/records?keys={JSONKeysObj}&select={JSONSelectObj}
key information in a TcaplusDB pb table. This operation only queries and transfers the values of the field you specify through the select variable, which will reduce the network transfer traffic usage and is the biggest difference from the GetRecord operation. If the data record does not exist, an error will be returned.
The keys and select variables must be specified in the URI. keys specifies the values of all primary keys. select specifies the name of the field whose value you want to display. You can specify the fields in the nested structure by separating the path with a dot, such as pay.total_money.%20 instead of +.Name | Type | Value |
x-tcaplus-target | String | Tcaplus.FieldGetRecord |
x-tcaplus-version | String | Tcaplus3.32.0 |
x-tcaplus-pwd-md5 | String | MD5 of AppKey(Password) |
x-tcaplus-idl-type | String | protobuf |
http://10.123.9.70/ver1.0/apps/2/zones/1/tables/tb_example/records?keys={'region': 101, 'name': 'calvinshao', 'uin': 100}&select=['gamesvrid', 'lockid', 'pay.auth.pay_keys', 'pay.total_money']
http://10.123.9.70/ver1.0/apps/2/zones/1/tables/tb_example/records?keys=%7B%22region%22%3A%20101%2C%20%22name%22%3A%20%22calvinshao%22%2C%20%22uin%22%3A%20100%7D&select=%5B%22gamesvrid%22%2C%20%22lockid%22%2C%20%22pay.auth.pay_keys%22%2C%20%22pay.total_money%22%5D
["x-tcaplus-target:Tcaplus.FieldGetRecord","x-tcaplus-version:Tcaplus3.32.0","x-tcaplus-pwd-md5:c3eda5f013f92c81dda7afcdc273cf82","x-tcaplus-idl-type:protobuf"]
{"ErrorCode": 0,"ErrorMsg": "Succeed","RecordVersion": 1,"Record": {"name": "calvinshao","lockid": [50,60,70],"pay": {"total_money": 10000,"auth": {"pay_keys": "adqwacsasafasda"}},"region": 101,"uin": 100,"gamesvrid": 4099}}
PUT /ver1.0/apps/{APP_ID}/zones/{ZONE_ID}/tables/{TABLE_NAME}/records
key information. Different from the SetRecord operation, it transfers and sets the values of only the specified fields instead of all fields, which reduces the network traffic usage. If the data record already exists, an update operation will be performed; otherwise, an error will be returned.FieldSetRecord operation supports setting the following values for resultflag:0: the response only contains whether the request succeeded or failed1: the response contains the same values as the request doesName | Type | Value |
x-tcaplus-target | String | Tcaplus.SetRecord |
x-tcaplus-version | String | Tcaplus3.32.0 |
x-tcaplus-pwd-md5 | String | MD5 of AppKey(Password) |
x-tcaplus-result-flag | Int | 2 |
x-tcaplus-data-version-check | Int | 2 |
x-tcaplus-data-version | Int | -1 |
x-tcaplus-idl-type | String | protobuf |
http://10.123.9.70/ver1.0/apps/2/zones/1/tables/tb_example/records
["x-tcaplus-target:Tcaplus.FieldSetRecord","x-tcaplus-version:Tcaplus3.32.0","x-tcaplus-pwd-md5:c3eda5f013f92c81dda7afcdc273cf82","x-tcaplus-result-flag:1","x-tcaplus-data-version-check:1","x-tcaplus-data-version:-1","x-tcaplus-idl-type:Protobuf"]
{"ReturnValues": "aaaaaaaaaa","FieldPath": [ // Explicitly specify the path of the field to be updated"gamesvrid","logintime","pay.total_money","pay.auth.pay_keys"],"Record": { // Set the new value of the field to be updated"name": "calvinshao","pay": {"total_money": 17190,"auth": {"pay_keys": "bingo"}},"region": 101,"uin": 100,"gamesvrid": 1719,"logintime": 1719}}
{"ErrorCode": 0,"ErrorMsg": "Succeed","RecordVersion": 3,"ReturnValues": "aaaaaaaaaa","Record": {"name": "calvinshao","pay": {"total_money": 17190,"auth": {"pay_keys": "bingo"}},"region": 101,"uin": 100,"gamesvrid": 1719,"logintime": 1719}}
PUT /ver1.0/apps/{APP_ID}/zones/{ZONE_ID}/tables/{TABLE_NAME}/records
key information of a record. It supports fields in int32, int64, uint32, and uint64 fields and has similar characteristics as FieldSetRecord.SetRecord operation supports setting the following values for resultflag:0: the response only contains whether the request succeeded or failed1: the response contains the modified value of the specified fieldName | Type | Value |
x-tcaplus-target | String | Tcaplus.SetRecord |
x-tcaplus-version | String | Tcaplus3.32.0 |
x-tcaplus-pwd-md5 | String | MD5 of AppKey(Password) |
x-tcaplus-result-flag | Int | 2 |
x-tcaplus-data-version-check | Int | 2 |
x-tcaplus-data-version | Int | -1 |
x-tcaplus-idl-type | String | protobuf |
http://10.123.9.70/ver1.0/apps/2/zones/1/tables/tb_example/records
["x-tcaplus-target:Tcaplus.FieldIncRecord","x-tcaplus-version:Tcaplus3.32.0","x-tcaplus-pwd-md5:c3eda5f013f92c81dda7afcdc273cf82","x-tcaplus-result-flag:1","x-tcaplus-data-version-check:1","x-tcaplus-data-version:-1","x-tcaplus-idl-type:Protobuf"]
{"ReturnValues": "aaaaaaaaaa","Record": {"name": "calvinshao","pay": {"total_money": -1,"auth": {"update_time": -1}},"region": 101,"uin": 100,"gamesvrid": 2,"logintime": -2}}
{"ErrorCode": 0,"ErrorMsg": "Succeed","RecordVersion": 9,"ReturnValues": "aaaaaaaaaa","Record": {"name": "calvinshao","pay": {"total_money": 11999,"auth": {"update_time": 921}},"region": 101,"uin": 100,"gamesvrid": 4101,"logintime": 98}}
GET /ver1.0/apps/{APP_ID}/zones/{ZONE_ID}/tables/{TABLE_NAME}/records?keys={JSONKeysObj}&select={JSONSelectObj}
select variable. The premise of this operation is that the specified primary key set must have an index created when the table is created; otherwise, an error will be returned.keys variable must be specified in the URI, which specifies the values of all primary keys. The optional select variable specifies the name of the field whose value you want to display. You can specify the fields in the nested structure by separating the path with a dot, such as pay.total_money.limit and offset are the parameters used to control partial record return.%20 instead of +. Please specify the index name to be accessed through x-tcaplus-index-name in the HEADER. The index name can be found in the table definition file.Name | Type | Value |
x-tcaplus-target | String | Tcaplus.GetRecord |
x-tcaplus-version | String | Tcaplus3.32.0 |
x-tcaplus-pwd-md5 | String | MD5 of AppKey(Password) |
x-tcaplus-idl-type | String | protobuf |
x-tcaplus-index-name | String | {index_name} |
http://10.123.9.70/ver1.0/apps/2/zones/1/tables/tb_example/records?keys={'name': 'calvinshao', 'uin': 100}&select=['gamesvrid', 'lockid', 'pay.total_money', 'pay.auth.pay_keys']
http://10.123.9.70/ver1.0/apps/2/zones/1/tables/tb_example/records?keys=%7B%22name%22%3A%20%22calvinshao%22%2C%20%22uin%22%3A%20100%7D&select=%5B%22gamesvrid%22%2C%20%22lockid%22%2C%20%22pay.total_money%22%2C%20%22pay.auth.pay_keys%22%5D
["x-tcaplus-target:Tcaplus.PartkeyGetRecord","x-tcaplus-version:Tcaplus3.32.0","x-tcaplus-pwd-md5:c3eda5f013f92c81dda7afcdc273cf82","x-tcaplus-idl-type:protobuf""x-tcaplus-index-name:index_name"]
{"ErrorCode": 0,"ErrorMsg": "Succeed","MultiRecords": [{"RecordVersion": 9,"Record": {"name": "calvinshao","lockid": [50,60,70,80,90,100],"pay": {"total_money": 11999,"auth": {"pay_keys": "adqwacsasafasda"}},"region": 101,"uin": 100,"gamesvrid": 4101}},{"RecordVersion": 1,"Record": {"name": "calvinshao","lockid": [50,60,70,80],"pay": {"total_money": 10000,"auth": {"pay_keys": "adqwacsasafasda"}},"region": 102,"uin": 100,"gamesvrid": 4100}},{"RecordVersion": 1,"Record": {"name": "calvinshao","lockid": [60,70,80,90],"pay": {"total_money": 10000,"auth": {"pay_keys": "adqwacsasafasda"}},"region": 103,"uin": 100,"gamesvrid": 4101}}],"RemainNum": 0,"TotalNum": 3}
Feedback