行操作接口

更新时间：2024-10-11

单条写入PutRow

描述

写入一行数据，只能通过request body将写入数据的各项参数传递给云数据库 TableStorage。

请求

Verb	URI
PUT	/v{version}/instance/{instanceName}/table/{tableName}/row

请求参数

参数名称	是否必须	参数类型	说明
rowkey	是	string	行主键，需rawurlencode
cells	是	list	每个column，value对的列表
+column	是	string	列名，命名规则满足正则[a-zA-Z_][a-za-z0-9\_]{0,254}
+value	是	string	rawurlencode后的string

响应参数

无

错误码

http_code	code	说明
20x	-	返回20x表示请求成功，例如200，204等
401	AuthenticationFailed	认证失败
400	InvalidURI	URI非法
405	MethodNotAllowed	传递了不支持的HTTP方法
400	InvalidContentType	请求头域Content-Type是不支持的类型
400	InvalidAutherization	请求头域Autherization没有传递
400	EmptyDate	请求头域Date或x-bce-date都没有传递
400	InvalidContentLength	请求头域Content-Length没有传递
400	ContentLengthMismatchBodySize	请求头域的Content-Length和实际Request body大小不等
400	MalformedJSON	请求体传递的json无法解析
500	InternalError	服务内部错误，需联系技术人员解决
503	ServerBusy	请求过于频繁，需要降低请求频率
404	InstanceNotExist	Instance不存在
404	TableNotExist	Table不存在
403	AccessDenied	请求了不属于自己创建的Instance
400	EmptyRowkey	请求的rowkey传递为空值或未传递
400	EmptyColumn	请求的column传递为空值或未传递
400	InvalidColumnName	请求的column名称不合法
400	EmptyCell	请求的cell传递为空或未传递
413	PayloadTooLarge	请求列数／整行大小／单列大小超过限制
403	InstanceCreating	实例创建中，请稍候
403	AccountOverdue	账号欠费，请充值后访问

请求示例

PUT /v1/instance/ins1/table/table1/row HTTP/1.1
HOST: bts.bd.baidubce.com
Authorization: bce-auth-v1/table-access-key/2018-05-24T13:41:13Z/1800/x-bce-date/{signature}
Content-Type: application/json
Content-Length: {payloadSizeBytes}
x-bce-date: 2018-05-24T13:41:13Z

{
    "rowkey": "k1%E5%B8",
    "cells": [
        {
            "column": "c1",
            "value": "v1"
        },
        {
            "column": "c2",
            "value": "v2"
        }
    ]
}

注意:rowkey和value均需要rawurlencode。

响应示例

HTTP/1.1 200 OK
Date: Sat, 18 Aug 2018 18:18:18 GMT
Content-Type: application/json; charset=utf-8
Content-Length: {payloadSizeBytes}
x-bce-request-id: 7869616F-7A68-6977-656E-406261696475

{}

批量写入BatchPutRow

描述

批量写入多行数据，只能通过request body将写入数据的各项参数传递给云数据库 TableStorage。

请求

Verb	URI
PUT	/v{version}/instance/{instanceName}/table/{tableName}/rows

请求参数

参数名称	是否必须	参数类型	说明
rows	是	list
+rowkey	是	string	行主键，需rawurlencode
+cells	是	list	每个column，value对的列表
++column	是	string	列名，命名规则满足正则[a-zA-Z_][a-za-z0-9\_]{0,254}
++value	是	string	rawurlencode后的string

响应参数

无

错误码

http_code	code	说明
20x	-	返回20x表示请求成功，例如200，204等
401	AuthenticationFailed	认证失败
400	InvalidURI	URI非法
405	MethodNotAllowed	传递了不支持的HTTP方法
400	InvalidContentType	请求头域Content-Type是不支持的类型
400	InvalidAutherization	请求头域Autherization没有传递
400	EmptyDate	请求头域Date或x-bce-date都没有传递
400	InvalidContentLength	请求头域Content-Length没有传递
400	ContentLengthMismatchBodySize	请求头域的Content-Length和实际Request body大小不等
400	MalformedJSON	请求体传递的json无法解析
500	InternalError	服务内部错误，需联系技术人员解决
503	ServerBusy	请求过于频繁，需要降低请求频率
404	InstanceNotExist	Instance不存在
404	TableNotExist	Table不存在
403	AccessDenied	请求了不属于自己创建的Instance
400	EmptyRows	请求的rows为空或未传递
400	EmptyRowkey	请求的rowkey传递为空值或未传递
400	EmptyColumn	请求的column传递为空值或未传递
400	InvalidColumnName	请求的column名称不合法
400	EmptyCell	请求的cell传递为空或未传递
413	PayloadTooLarge	请求行数/列数／整行大小／单列大小超过限制
403	InstanceCreating	实例创建中，请稍候
403	AccountOverdue	账号欠费，请充值后访问

请求示例

PUT /v1/instance/ins1/table/table1/rows HTTP/1.1
HOST: bts.bd.baidubce.com
Authorization: bce-auth-v1/table-access-key/2018-05-24T13:41:13Z/1800/x-bce-date/{signature}
Content-Type: application/json
Content-Length: {payloadSizeBytes}
x-bce-date: 2018-05-24T13:41:13Z

{
    "rows": [
        {
            "rowkey": "k1%E5%B8",
            "cells": [
                {
                    "column": "c1",
                    "value": "v1"
                },
                {
                    "column": "c2",
                    "value": "v2"
                }
            ]
        }
    ]
}

注意:rowkey和value均需要rawurlencode。

响应示例

HTTP/1.1 200 OK
Date: Sat, 18 Aug 2018 18:18:18 GMT
Content-Type: application/json; charset=utf-8
Content-Length: {payloadSizeBytes}
x-bce-request-id: 7869616F-7A68-6977-656E-406261696475

{}

单条删除DeleteRow

描述

删除一整行数据或该行数据的部分列。

删除指定的列：将待删除的列指定在columns字段。
删除整行：cells参数传空list。

暂时无法支持return_old_value和condition_delete功能。

请求

Verb	URI
DELETE	/v{version}/instance/{instanceName}/table/{tableName}/row

请求参数

参数名称	是否必须	参数类型	说明
rowkey	是	string	行主键，需rawurlencode
cells	否	list	待删除column列表
+column	否	string	待删除的列名称

响应参数

无

错误码

http_code	code	说明
20x	-	返回20x类表示请求成功
401	AuthenticationFailed	认证失败
400	InvalidURI	URI非法
405	MethodNotAllowed	传递了不支持的HTTP方法
400	InvalidContentType	请求头域Content-Type是不支持的类型
400	InvalidAutherization	请求头域Autherization没有传递
400	EmptyDate	请求头域Date或x-bce-date都没有传递
400	InvalidContentLength	请求头域Content-Length没有传递
400	ContentLengthMismatchBodySize	请求头域的Content-Length和实际Request body大小不等
400	MalformedJSON	请求体传递的json无法解析
500	InternalError	服务内部错误，需联系技术人员解决
503	ServerBusy	请求过于频繁，需要降低请求频率
404	InstanceNotExist	Instance不存在
404	TableNotExist	Table不存在
403	AccessDenied	请求了不属于自己创建的Instance
400	EmptyRowkey	请求的rowkey传递为空值或未传递
400	EmptyColumn	请求的column传递为空值或未传递
400	InvalidColumnName	请求的column名称不合法
413	PayloadTooLarge	请求列数超过限制
403	InstanceCreating	实例创建中，请稍候
403	AccountOverdue	账号欠费，请充值后访问

请求示例

DELETE /v1/instance/ins1/table/table1/row HTTP/1.1
HOST: bts.bd.baidubce.com
Authorization: bce-auth-v1/table-access-key/2018-05-24T13:41:13Z/1800/x-bce-date/{signature}
Content-Type: application/json
Content-Length: {payloadSizeBytes}
x-bce-date: 2018-05-24T13:41:13Z

{
    "rowkey": "k1%E5%B8",
    "cells": [
        {
            "column": "c1"
        },
        {
            "column": "c2"
        }
    ]
}

注意:rowkey需要rawurlencode。

响应示例

HTTP/1.1 200 OK
Date: Sat, 18 Aug 2018 18:18:18 GMT
Content-Type: application/json; charset=utf-8
Content-Length: {payloadSizeBytes}
x-bce-request-id: 7869616F-7A68-6977-656E-406261696475

{}

注意:传递的字段只要有非法格式，即报错。

批量删除BatchDeleteRow

描述

批量删除若干行数据，只能通过request body将写入数据的各项参数传递给云数据库 TableStorage。

请求

Verb	URI
DELETE	/v{version}/instance/{instanceName}/table/{tableName}/rows

请求参数

参数名称	是否必须	参数类型	说明
rows	是	list
+rowkey	是	string	行主键，需rawurlencode
+cells	是	list	待删除column列表
++column	是	string	待删除的列名称

响应参数

无

错误码

http_code	code	说明
20x	-	返回20x类表示请求成功
401	AuthenticationFailed	认证失败
400	InvalidURI	URI非法
405	MethodNotAllowed	传递了不支持的HTTP方法
400	InvalidContentType	请求头域Content-Type是不支持的类型
400	InvalidAutherization	请求头域Autherization没有传递
400	EmptyDate	请求头域Date或x-bce-date都没有传递
400	InvalidContentLength	请求头域Content-Length没有传递
400	ContentLengthMismatchBodySize	请求头域的Content-Length和实际Request body大小不等
400	MalformedJSON	请求体传递的json无法解析
500	InternalError	服务内部错误，需联系技术人员解决
503	ServerBusy	请求过于频繁，需要降低请求频率
404	InstanceNotExist	Instance不存在
404	TableNotExist	Table不存在
403	AccessDenied	请求了不属于自己创建的Instance
400	EmptyRows	请求的rows传递为空或未传递
400	EmptyRowkey	请求的rowkey传递为空值或未传递
400	EmptyColumn	请求的column传递为空值或未传递
400	InvalidColumnName	请求的column名称不合法
413	PayloadTooLarge	请求行数/列数超过限制
403	InstanceCreating	实例创建中，请稍候
403	AccountOverdue	账号欠费，请充值后访问

请求示例

DELETE /v1/instance/ins1/table/table1/rows HTTP/1.1
HOST: bts.bd.baidubce.com
Authorization: bce-auth-v1/table-access-key/2018-05-24T13:41:13Z/1800/x-bce-date/{signature}
Content-Type: application/json
Content-Length: {payloadSizeBytes}
x-bce-date: 2018-05-24T13:41:13Z

{
    "rows": [
        {
            "rowkey": "k1%E5%B8",
            "cells": [
                {
                    "column": "c1"
                },
                {
                    "column": "c2"
                }
            ]
        }
    ]
}

注意:rowkey需要rawurlencode。

响应示例

HTTP/1.1 200 OK
Date: Sat, 18 Aug 2018 18:18:18 GMT
Content-Type: application/json; charset=utf-8
Content-Length: {payloadSizeBytes}
x-bce-request-id: 7869616F-7A68-6977-656E-406261696475

{}

单条随机读GetRow

描述

查询一行，或一行中的某些列。

请求

Verb	URI
GET	/v{version}/instance/{instanceName}/table/{tableName}/row

请求头:x-bce-if-none-match 响应头:ETag

请求参数

参数名称	是否必须	参数类型	说明
rowkey	是	string	行主键，需rawurlencode
cells	否	list	待查询的column列表
+column	否	string	待查询的列名称
maxVersions	否	int	最多保留版本数，取值范围[1, 50000]

响应参数

参数名称	参数类型	说明
result	list	查询到的行结果，GetRow最多只会有一个result
+rowkey	string	rawurlencode(rowkey)，用户需rawurldecode
+cells	list	查询到的column列表
++column	string	属性列名称
++value	string	rawurlencode(属性列值)，用户需rawurldecode
++timestamp	int	指定列的版本号，毫秒级的时间戳

错误码

http_code	code	说明
200	-	请求成功
401	AuthenticationFailed	认证失败
400	InvalidURI	URI非法
405	MethodNotAllowed	传递了不支持的HTTP方法
400	InvalidContentType	请求头域Content-Type是不支持的类型
400	InvalidAutherization	请求头域Autherization没有传递
400	EmptyDate	请求头域Date或x-bce-date都没有传递
400	InvalidContentLength	请求头域Content-Length没有传递
400	ContentLengthMismatchBodySize	请求头域的Content-Length和实际Request body大小不等
400	MalformedJSON	请求体传递的json无法解析
500	InternalError	服务内部错误，需联系技术人员解决
503	ServerBusy	请求过于频繁，需要降低请求频率
404	InstanceNotExist	Instance不存在
404	TableNotExist	Table不存在
403	AccessDenied	请求了不属于自己创建的Instance
400	EmptyRowkey	请求的rowkey传递为空值或未传递
400	EmptyColumn	请求的column传递为空值或未传递
400	InvalidColumnName	请求的column名称不合法
413	PayloadTooLarge	请求列数超过限制
403	InstanceCreating	实例创建中，请稍候
403	AccountOverdue	账号欠费，请充值后访问

请求示例

GET /v1/instance/ins1/table/table1/row HTTP/1.1
HOST: bts.bd.baidubce.com
Authorization: bce-auth-v1/table-access-key/2018-05-24T13:41:13Z/1800/x-bce-date/{signature}
Content-Type: application/json
Content-Length: {payloadSizeBytes}
x-bce-date: 2018-05-24T13:41:13Z

{
    "rowkey": "k1%E5%B8",
    "cells": [
        {
            "column": "c1"
        },
        {
            "column": "c2"
        }
    ]
}

注意:rowkey需要rawurlencode。

响应示例

HTTP/1.1 200 OK
Date: Sat, 18 Aug 2018 18:18:18 GMT
Content-Type: application/json; charset=utf-8
Content-Length: {payloadSizeBytes}
ETag: 3f80f-1b6-3e1cb03b
x-bce-request-id: 7869616F-7A68-6977-656E-406261696475

{
    "result": [
    {
        "rowkey": "k1%E5%B8",
            "cells": [
            {
                "column": "c1",
                "value": "v1",
                "timestamp": 1571049818321
            },
            {
                "column": "c2",
                "value": "v2",
                "timestamp": 1571049818321
            }
        ]
    }
    ]
}

注意:rowkey和value均需要rawurldecode。

批量读BatchGetRow

描述

查询多行，或多行中的某些列，只能通过request body将写入数据的各项参数传递给云数据库 TableStorage。

请求

Verb	URI
GET	/v{version}/instance/{instanceName}/table/{tableName}/rows

请求头: x-bce-if-none-match 响应头: ETag

请求参数

参数名称	是否必须	参数类型	说明
rows	是	list
+rowkey	是	string	行主键，需rawurlencode
+cells	否	list	待查询的column列表
++column	否	string	待查询的列名称
maxVersions	否	int	最多保留版本数，取值范围[1, 50000]

响应参数

参数名称	参数类型	说明
result	list	查询到的行结果
+rowkey	string	rawurlencode(rowkey)，用户需rawurldecode
+cells	list	查询到的column列表
++column	string	属性列名称
++value	string	rawurlencode(属性列值)，用户需rawurldecode
++timestamp	int	指定列的版本号，毫秒级的时间戳

错误码

http_code	code	说明
200	-	请求成功
401	AuthenticationFailed	认证失败
400	InvalidURI	URI非法
405	MethodNotAllowed	传递了不支持的HTTP方法
400	InvalidContentType	请求头域Content-Type是不支持的类型
400	InvalidAutherization	请求头域Autherization没有传递
400	EmptyDate	请求头域Date或x-bce-date都没有传递
400	InvalidContentLength	请求头域Content-Length没有传递
400	ContentLengthMismatchBodySize	请求头域的Content-Length和实际Request body大小不等
400	MalformedJSON	请求体传递的json无法解析
500	InternalError	服务内部错误，需联系技术人员解决
503	ServerBusy	请求过于频繁，需要降低请求频率
404	InstanceNotExist	Instance不存在
404	TableNotExist	Table不存在
403	AccessDenied	请求了不属于自己创建的Instance
400	EmptyRows	请求的rows传递为空或未传递
400	EmptyRowkey	请求的rowkey传递为空值或未传递
400	EmptyColumn	请求的column传递为空值或未传递
400	InvalidColumnName	请求的column名称不合法
413	PayloadTooLarge	请求行数/列数超过限制
403	InstanceCreating	实例创建中，请稍候
403	AccountOverdue	账号欠费，请充值后访问

请求示例

GET /v1/instance/ins1/table/table1/row/k1%E5%B8 HTTP/1.1
HOST: bts.bd.baidubce.com
Authorization: bce-auth-v1/table-access-key/2018-05-24T13:41:13Z/1800/x-bce-date/{signature}
Content-Type: application/json
Content-Length: {payloadSizeBytes}
x-bce-date: 2018-05-24T13:41:13Z

{
    "rows": [
        {
            "rowkey": "k1%E5%B8",
            "cells": [
                {
                    "column": "c1"
                },
                {
                    "column": "c2"
                }
            ]
        },
        {
            "rowkey": "k2%E5%B8",
            "cells": [
                {
                    "column": "c3"
                },
                {
                    "column": "c4"
                }
            ]
        }
    ]
}

注意:rowkey需要rawurlencode。

响应示例

HTTP/1.1 200 OK
Date: Sat, 18 Aug 2018 18:18:18 GMT
Content-Type: application/json; charset=utf-8
Content-Length: {payloadSizeBytes}
ETag: 3f80f-1b6-3e1cb03b
x-bce-request-id: 7869616F-7A68-6977-656E-406261696475

{
    "result": [
        {
            "rowkey": "k1%E5%B8",
            "cells": [
                {
                    "column": "c1",
                    "value": "v1",
                    "timestamp": 1571049818321
                },
                {
                    "column": "c2",
                    "value": "v2",
                    "timestamp": 1571049818321
                }
            ]
        },
        {
            "rowkey": "k2%E5%B8",
            "cells": [
                {
                    "column": "c3",
                    "value": "v3",
                    "timestamp": 1571049818321
                },
                {
                    "column": "c4",
                    "value": "v4",
                    "timestamp": 1571049818321
                }
            ]
        }
    ]
}

注意:rowkey和value均需要rawurldecode。

区间读Scan

描述

顺序扫描若干行数据。

请求

Verb	URI
GET	/v{version}/instance/{instanceName}/table/{tableName}/rows

请求头: x-bce-if-none-match 响应头： ETag

请求参数

参数名称	是否必须	参数类型	说明
startRowkey	否	string	scan的起始rowkey，需rawurlencode，不填时默认为表的第一个rowkey
includeStart	否	bool	是否包含起始rowkey，默认包含
stopRowkey	否	string	scan的终止rowkey，需rawurlencode，不填时默认为表的最后一个rowkey
includeStop	否	bool	是否包含终止rowkey，默认不包含
selector	否	list	待查询的column列表，不写默认返回全部列
+column	否	string	待查询的列名称
limit	否	int	限定查询行数，其值必须为整型，设为其他类型无效
maxVersions	否	int	最多保留版本数，取值范围[1, 50000]

注意:startRowkey和stopRowkey指定的区间只需要包含用户所读数据即可，不需要一定是真实存在于表中的rowkey。

响应参数

参数名称	参数类型	说明
result	list	记录列表
+rowkey	string	rawurlencode(rowkey)，用户需rawurldecode
+cells	list	cell列表
++column	string	列名
++value	string	rawurlencode(列值)，用户需rawurldecode
++timestamp	int	指定列的版本号，毫秒级的时间戳
nextStartKey	string	若本次扫描未结束（返回206），后端会返回nextStartKey作为下一次扫描的起始key，用户应使用此值填充至startRowkey发起下一次scan操作

错误码

http_code	code	说明
200	-	请求成功
206	-	请求成功，但是后端未返回全部数据，需要用户发起下一次请求来读取剩余数据
401	AuthenticationFailed	认证失败
400	InvalidURI	URI非法
405	MethodNotAllowed	传递了不支持的HTTP方法
400	InvalidContentType	请求头域Content-Type是不支持的类型
400	InvalidAutherization	请求头域Autherization没有传递
400	EmptyDate	请求头域Date或x-bce-date都没有传递
400	InvalidContentLength	请求头域Content-Length没有传递
400	ContentLengthMismatchBodySize	请求头域的Content-Length和实际Request body大小不等
400	MalformedJSON	请求体传递的json无法解析
500	InternalError	服务内部错误，需联系技术人员解决
503	ServerBusy	请求过于频繁，需要降低请求频率
404	InstanceNotExist	Instance不存在
404	TableNotExist	Table不存在
403	AccessDenied	请求了不属于自己创建的Instance
413	PayloadTooLarge	请求列数超过限制
403	InstanceCreating	实例创建中，请稍候
403	AccountOverdue	账号欠费，请充值后访问

请求示例

GET /v1/instance/instance/table/table1/rows HTTP/1.1
HOST: bts.bd.baidubce.com
Authorization: bce-auth-v1/table-access-key/2018-05-24T13:41:13Z/1800/x-bce-date/{signature}
Content-Type: application/json
Content-Length: {payloadSizeBytes}
x-bce-date: 2018-05-24T13:41:13Z

{
    "startRowkey": "k1%E5%B8",
    "includeStart": true,
    "stopRowkey": "k5%E5%B8",
    "includeStop": false,
    "selector": [
        "column": "c1",
        "column": "c2",
        "column": "c3"
    ],
    "limit": 1000
}

注意:rowkey需要rawurlencode。

响应示例

HTTP/1.1 206 Partial Content
Date: Sat, 18 Aug 2018 18:18:18 GMT
Content-Type: application/json; charset=utf-8
Content-Length: {payloadSizeBytes}
ETag: 3f80f-1b6-3e1cb03b
x-bce-request-id: 7869616F-7A68-6977-656E-406261696475

{
    "result": [
        {
            "rowkey": "k1%E5%B8",
            "cells": [
                {
                    "column": "c1",
                    "value": "v1",
                    "timestamp": 1571049818321
                },
                {
                    "column": "c2",
                    "value": "v2",
                    "timestamp": 1571049818321
                }
            ]
        },
        {
            "rowkey": "k2%E5%B8",
            "cells": [
                {
                    "column": "c3",
                    "value": "v3",
                    "timestamp": 1571049818321
                }
            ]
        }
    ],
    "nextStartKey": "k3%E5B8"
}

注意:rowkey和value均需要rawurldecode。

表操作接口

时序模式