[PB] ListTraverse2.0

Supported version: 3.50.0

Brief Introduction

The interface is used to traverse the full table data. It supports the Limit parameter to control the number of records returned for each traversal. At the same time, the returned response package contains the TraveseSession field and Complete field. The traversal conditions are as follows:

  • Limit: control the number of records returned per traversal
  • TraveseSession: string, initial value: 0.0, a cursor parameter, is used to determine the traversal position each time. The Session value returned this time is transfered into the Data parameter of the next traversal
  • Complete: bool. Value range: False or True, used to determine whether the record traversal is completed
  • Select: specify the fields returned for each traversal
POST http://{Tcaplus_REST_URL}

Request Syntax

Http Request

#Tencent Cloud Console RESTful Endpoint, ip: 80, port: 80 by default
http://172.17.0.22
#TcaplusDB Local docker RESTful Endpoint, ip: 31001, port: 31001 by default
http://9.135.8.93:31001

Http Head

Name Required or not Limitations Description
x-tcaplus-target Yes None Tcaplus.ListTraverse
x-tcaplus-version Yes None Tcaplus3.50.0
x-tcaplus-app-id Yes None Correspond to the app id number(aka, cluster access id)
x-tcaplus-zone-id Yes None Correspond to the zone number (aka, table group id)
x-tcaplus-protocol-version Yes None Correspond to the protocol version number, default 2.0
x-tcaplus-table-name Yes None Correspond to the table name
x-tcaplus-pwd-md5 Yes None App password (aka, cluster access password), that is, the md5 value after the calculation
x-tcaplus-idl-type Yes None protobuf
x-tcaplus-result-flag No None 0: No data will be returned after successful operation; 1: After the operation is successful, the data that is consistent with the request will be returned; 2: After the operation is successful, the data after this update operation will be returned; 3: After the operation is successful, the data before the tcapsvr operation will be returned
x-tcaplus-data-version-check No 1: Detect the record version number. Only when the version number is the same as the server version number, the version number will automatically increase; 2: Do not detect the record version number, but force the client record version number to be written to the server; 3: Do not detect the record version number, and automatically increase the server version number
x-tcaplus-data-version No Version number

Example:

x-tcaplus-target:Tcaplus.ListTraverse
x-tcaplus-app-id:3
x-tcaplus-zone-id:1
x-tcaplus-protocol-version:2.0
x-tcaplus-table-name:tb_online_list
x-tcaplus-pwd-md5:4e81984efccfb4982333aeb1ff7968d5
x-tcaplus-result-flag:2
x-tcaplus-version:Tcaplus3.50.0
x-tcaplus-data-version-check: 3
x-tcaplus-idl-type:protobuf

Data

Use json format to represent the record related information. Parameter description:

  • Limit: Required. It limits the number of data returned per traversal
  • TraveseSession: Required. It is used to judge the state of the traversal cycle Session, similar to the offset function. It is in the TraveseSession of the response package
  • Select: Optional. It specifies the record field returned

Example:

{
    "Limit": 1000,
    "TraverseSession": "0.0",
    "Select": ["gamesvrid"]
}

Complete Request Example

One-time Traversal Example

Limit is set to a large value to return all records at one time. It is suitable for scenarios with small table records

curl -i -XPOST -H 'x-tcaplus-target: Tcaplus.ListTraverse' -H 'x-tcaplus-app-id: 70' -H 'x-tcaplus-zone-id: 1' -H 'x-tcaplus-protocol-version: 2.0' -H 'x-tcaplus-table-name: tb_online_list' -H 'x-tcaplus-pwd-md5: 0972ad76decf4d11a69e2e0d9af335da' -H 'x-tcaplus-result-flag: 1' -H 'x-tcaplus-version: Tcaplus3.50.0' -H 'x-tcaplus-data-version-check: 1' -H 'x-tcaplus-idl-type: protobuf' http://172.17.32.17 -d '{
    "Limit": 1,
    "TraveseSession": "0.0",
    "Select": ["gamesvrid"]
}'

Loop Traversal Example

Limit is sett to a moderate value, and it combines TraveseSession and Complete for loop traversal judgment. Take the Bash script as an example:

#!/bin/bash
PROTO_VERSION="2.0"
TCAPLUS_VERSION="Tcaplus3.50.0"
IDL_TYPE="protobuf"
CHECK_POLICY=3
result_flag=2
rest_url="http://172.17.32.17"
app_id=70
zone_id=1
table_name="tb_online_list"
passwd="Test@2020"

#caculate the md5 value of password
md5_passwd=$(echo -n $passwd | md5sum | cut -d ' ' -f1)

function build_headers(){
    headers=(
        -H "x-tcaplus-target: ${1}"
        -H "x-tcaplus-app-id: ${app_id}"
        -H "x-tcaplus-zone-id: ${zone_id}"
        -H "x-tcaplus-protocol-version: ${PROTO_VERSION}"
        -H "x-tcaplus-table-name: ${table_name}"
        -H "x-tcaplus-pwd-md5: ${md5_passwd}"
        -H "x-tcaplus-result-flag: ${result_flag}"
        -H "x-tcaplus-version: ${TCAPLUS_VERSION}"
        -H "x-tcaplus-data-version-check: ${CHECK_POLICY}"
        -H "x-tcaplus-idl-type: ${IDL_TYPE}"
    )
}
function build_traverse_loop_data(){
    cat <<EOF
{
    "Limit": 1,
    "TraveseSession": "$1",
    "Select": ["gamesvrid"]
}
EOF
}
function traverse_loop() {
  target="Tcaplus.Traverse"
  build_headers "$target"
  complete="False"
  limit=1
  traverse_session="0.0"
  total_num=0
  while [ "$complete" == "False" ];do

      ret=$(curl -i -XPOST "${headers[@]}" "$rest_url" -d "$(build_traverse_loop_data $traverse_session)" | grep -v HTTP | grep -v "json-1.0" | grep -v "content-length" | grep -v "^$" )

      echo "$ret"

      #Get the complete value, False or true, False: means that the data traversal has not yet ended, and true: means that the traversal has ended. Use the Json of Python 3
      complete=$( echo "$ret" | python3 -c "import sys, json; print(json.load(sys.stdin)['Complete'])" )
　　　
　　　# Get the value of TraveseSession, which is used for the location of the next traversal, similar to Offset.
      traverse_session=$( echo "$ret" | python3 -c "import sys, json; print(json.load(sys.stdin)['TraveseSession'])" )

      if [ "$complete" == "False" ];then

          total_num=$(($total_num+1))
      fi

  done
  echo "TotalRecords:$total_num"
}

declare -a headers

#traverse
traverse_loop

Return Syntax

Return Parameter Description

Parameter name Description
ErrorCode Return code
ErrorMsg Return message
ReturnValues The reserved data set by the user arrives at tcaplus with the request and is returned in the original form by the response
SucceedRecords Data returned of successful records in json format. For details, refer to Data section
SucceedNum Number of successful records
FailedRecords Data returned of failed records in json format. For details, refer to Data section
FailedNum Number of failed records

Return Example

Judge whether the Complete parameter is true. If it is false, continue the request through loop traversal.

One-time Return Data Example

Limit is set to a large value

{
    "ErrorCode": 0,
    "ErrorMsg": "Succeed",
    "MultiRecords": [{
        "RecordVersion": 3,
        "Index": 0,
        "Record": {
            "gamesvrid": "4",
            "openid": 4,
            "tconndid": 4,
            "timekey": "4"
        }
    }, {
        "RecordVersion": 3,
        "Index": 1,
        "Record": {
            "gamesvrid": "2",
            "openid": 2,
            "tconndid": 2,
            "timekey": "2"
        }
    }, {
        "RecordVersion": 3,
        "Index": 2,
        "Record": {
            "gamesvrid": "3",
            "openid": 3,
            "tconndid": 3,
            "timekey": "3"
        }
    }, {
        "RecordVersion": 7,
        "Index": 0,
        "Record": {
            "gamesvrid": "2",
            "openid": 1,
            "tconndid": 1,
            "timekey": "1"
        }
    }, {
        "RecordVersion": 7,
        "Index": 1,
        "Record": {
            "gamesvrid": "11",
            "openid": 1,
            "tconndid": 1,
            "timekey": "1"
        }
    }, {
        "RecordVersion": 7,
        "Index": 2,
        "Record": {
            "gamesvrid": "22",
            "openid": 1,
            "tconndid": 1,
            "timekey": "1"
        }
    }, {
        "RecordVersion": 7,
        "Index": 3,
        "Record": {
            "gamesvrid": "4",
            "openid": 1,
            "tconndid": 1,
            "timekey": "1"
        }
    }],
    "TotalNum": 7,
    "Complete": true,
    "TraveseSession": "80630.48568512"
}

Loop Return Data Example

Limit is set to a small value (Limit = 1). The results returned through loop traversal are as shown in the figure below. All records are returned after 2 times of traversal. The total number of records is the same as the number of records returned at one time above, and the TotalNum is 7.

#Loop - return the result for the first time, TotalNum: 3
{
    "ErrorCode": 0,
    "ErrorMsg": "Succeed",
    "MultiRecords": [{
        "RecordVersion": 3,
        "Index": 0,
        "Record": {
            "gamesvrid": "4",
            "openid": 4,
            "tconndid": 4,
            "timekey": "4"
        }
    }, {
        "RecordVersion": 3,
        "Index": 1,
        "Record": {
            "gamesvrid": "2",
            "openid": 2,
            "tconndid": 2,
            "timekey": "2"
        }
    }, {
        "RecordVersion": 3,
        "Index": 2,
        "Record": {
            "gamesvrid": "3",
            "openid": 3,
            "tconndid": 3,
            "timekey": "3"
        }
    }],
    "TotalNum": 3,
    "Complete": false,
    "TraveseSession": "80630.48566720"
}

#Loop - return the result for the second time, TotalNum: 4

{
    "ErrorCode": 0,
    "ErrorMsg": "Succeed",
    "MultiRecords": [{
        "RecordVersion": 7,
        "Index": 0,
        "Record": {
            "gamesvrid": "2",
            "openid": 1,
            "tconndid": 1,
            "timekey": "1"
        }
    }, {
        "RecordVersion": 7,
        "Index": 1,
        "Record": {
            "gamesvrid": "11",
            "openid": 1,
            "tconndid": 1,
            "timekey": "1"
        }
    }, {
        "RecordVersion": 7,
        "Index": 2,
        "Record": {
            "gamesvrid": "22",
            "openid": 1,
            "tconndid": 1,
            "timekey": "1"
        }
    }, {
        "RecordVersion": 7,
        "Index": 3,
        "Record": {
            "gamesvrid": "4",
            "openid": 1,
            "tconndid": 1,
            "timekey": "1"
        }
    }],
    "TotalNum": 4,
    "Complete": false,
    "TraveseSession": "80630.48568384"
}

Error code

Refer to Common Error Codes

Other Reference Documents

[[PB List Table][C++ SDK] Interface Description for Traversing Table Data](../../01C++_SDK/02Interface_Documents/28[List_Table]Traverse_Table_Data.md

[[PB List Table][Go SDK] Interface Description for Traversing Full Table Data](../../02Go_SDK/02Interface_Documents/29[List_Table]Traverse_Table_Data.md

results matching ""

    No results matching ""