华为云用户手册

状态码 正常状态码 描述 200 OK 201 Created 202 Accepted 204 No Content 错误状态码 描述 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 405 Method Not Allowed 409 Conflict 413 Request Entity Too Large 415 Unsupported Media Type 429 Too Many Requests 500 Internal Server Error 501 Not Implemented 503 Service Unavailable 父主题： 附录

AK/SK认证 AK/SK签名认证方式仅支持消息体大小在12MB以内。 AK/SK认证就是使用AK/SK对请求进行签名，在请求时将签名信息添加到消息头，从而通过身份认证。 AK（Access Key ID）：访问密钥ID。与私有访问密钥关联的唯一标识符；访问密钥ID和私有访问密钥一起使用，对请求进行加密签名。 SK（Secret Access Key）：私有访问密钥。与访问密钥ID结合使用，对请求进行加密签名，可标识发送方，并防止请求被修改。 使用AK/SK认证时，您可以基于签名算法使用AK/SK对请求进行签名，也可以使用专门的签名SDK对请求进行签名。详细的签名方法和SDK使用方法请参见API签名指南。 签名SDK只提供签名功能，与服务提供的SDK不同，使用时请注意。

请求URI 请求URI由如下部分组成（方括号部分可选）： {URI-scheme}://[{store-name}.]{Endpoint}/{resource-path}[?{query-string}] 尽管请求URI包含在请求消息头中，但大多数语言或框架都要求您从请求消息中单独传递它，所以在此单独强调。 表1 URI中的参数说明 参数 描述 URI-scheme 请求使用的协议类型，如HTTP、HTTPS。HTTPS表示通过安全的HTTPS访问该资源，键值存储服务支持HTTP，HTTPS两种传输协议。 store-name 请求使用的仓名称，是可选部分，并不是每个API都有仓名称。存储仓的命名规范为{用户自定义前缀}-{KVS所在区域的区 域名 }-{用户的账号ID} ，例如：exampleprefix-cn-north-4-exampledomainid。如何获取账号ID请参见获取账号ID Endpoint 指定承载KVS服务端点的服务器域名或IP。Endpoint需要通过购买 VPC终端节点 ，创建内网域名来获取，具体操作请参见VPC终端节点对接KVS。 resource-path 资源路径，即API访问路径。从具体API的URI模块获取，例如“创建表”API接口的resource-path为“/v1/create-table”。 query-string 查询参数，是可选部分，并不是每个API都有查询参数。查询参数前面需要带一个“?”，形式为“参数名=参数取值”，例如“?store-name=exampleprefix-cn-north-4-exampledomainid”，表示仓名称为exampleprefix-cn-north-4-exampledomainid。 例如您需要在KVS的“华北-北京四”区域创建表，则需使用“华北-北京四”区域的Endpoint（kvs.cn-north-4.myhuaweicloud.com），并在具体API的URI部分找到resource-path（/v1/create-table），拼接起来如下所示。其中${store-name}为仓名。 1 https://${store-name}.kvs.cn-north-4.myhuaweicloud.com/v1/create-table 为方便查看，在每个具体API的URI部分，只给出resource-path部分，并将请求方法写在一起。这是因为URI-scheme都是HTTPS，而Endpoint在同一个区域也相同，所以简洁起见将这两部分省略。

请求消息头 附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请求头“Content-Type”，请求鉴权信息等。 详细的公共请求消息头字段请参见表3。 表3 公共请求消息头 名称 描述 是否必选 示例 Host 请求的服务器信息，从服务API的URL中获取。值为hostname[:port]。端口缺省时使用默认的端口，https的默认端口为443。 否 使用AK/SK认证时该字段必选。 code.test.com or code.test.com:443 Content-Type 消息体的类型（格式）。推荐用户使用默认值application/bson，有其他取值时会在具体接口中专门说明。 是 application/bson Content-Length 请求body长度，单位为Byte。 否 3495 X-Project-Id project id，项目编号。请参考获取项目ID章节获取项目编号。 否 如果是专属云场景采用AK/SK认证方式的接口请求，或者多project场景采用AK/SK认证的接口请求，则该字段必选。 e9993fc787d94b6c886cbaa340f9c0f4 API同时支持使用AK/SK认证，AK/SK认证使用SDK对请求进行签名，签名过程会自动往请求中添加Authorization（签名认证信息）和X-Sdk-Date（请求发送的时间）请求头。 AK/SK认证的详细说明请参见认证鉴权的“AK/SK认证”。

请求消息体（可选） 该部分可选。请求消息体通常以Bson格式发出，与请求消息头中Content-Type对应，传递除请求消息头之外的内容。若请求消息体中的参数支持中文，则中文字符必须为UTF-8编码。 每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），列举仓接口就不需要消息体，消息体具体内容需要根据具体接口而定。 对于创建表接口，您可以从接口的请求部分看到所需的请求参数及参数说明。将消息体加入后的请求如下所示，斜体字段需要根据实际值填写，其中${store-name}为仓名，$YOUR_TABLE_NAME为表名，$YOUR_SHARD_KEY_NAME为分区键名称，$YOUR_SORT_KEY_NAME为排序键名称。 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 POST https://${store-name}.kvs.cn-north-4.myhuaweicloud.com/v1/create-table Content-Type: application/bson { "table_name" : "$YOUR_TABLE_NAME", "primary_key_schema" : { "shard_key_fields" : [ { "name" : "$YOUR_SHARD_KEY_NAME", "order" : true } ], "sort_key_fields" : [ { "name" : "$YOUR_SORT_KEY_NAME", "order" : true } ] } } 到这里为止这个请求需要的内容就具备齐全了，您可以直接编写代码发送请求调用API。对于创建表接口，返回的响应体中包含了创建表的属性信息。表创建好以后，您就可以调用其他API执行向表中插入数据、查询表中数据等其他操作了。

API概览 表1 接口说明 类型 子类型 说明 仓接口 列举仓 一个账户下可以创建最多25个仓，每个仓可以创建最多100个store，响应中一次性返回所有仓名称。 创建表 在指定存储仓内创建表，表名在存储仓内唯一； 创建表时，指定主键模板及本地二级索引模板及全局二级索引模板。 列举表 指定存储仓列举创建的所有表。 表接口 查询表 指定存储仓查询表属性，如容量，规模，配额。 KV接口 上传单个kv 指定表，新建kv或覆盖已有kv，且满足表的key schema描述；允许指定条件执行。 查询单个kv 下载一个kv文档的全部内容，或者部分字段的内容。 更新单个kv 指定表，指定主键，指定更新文档的部分内容，如果是自描述文档，指定字段名；如果是二进制文档，指定偏移位置和长度；允许指定条件执行。 删除单个kv 指定表，指定主键，删除该文档；允许指定条件执行。 扫描所有kv 指定表，扫描表下所有kv；允许指定过滤条件。 扫描分区键内kv 指定表及分区键，携带条件查询kv；允许指定过滤条件。 批量写请求 批量写请求，其中可以携带一或多个表的不同kv的写操作，上传kv/删除kv。

基本概念 账号 用户注册时的账号，账号对其所拥有的资源及云服务具有完全的访问权限，可以重置用户密码、分配用户权限等。由于账号是付费主体，为了确保账号安全，建议您不要直接使用账号进行日常管理工作，而是创建用户并使用用户进行日常管理工作。 用户 由账号在 IAM 中创建的用户，是云服务的使用人员，具有身份凭证（密码和访问密钥）。 在我的凭证下，您可以查看账号ID和IAM用户ID。通常在调用API的鉴权过程中，您需要用到账号、用户和密码等信息。 区域（Region） 从地理位置和网络时延维度划分，同一个Region内共享弹性计算、块存储、对象存储、VPC网络、弹性公网IP、镜像等公共服务。Region分为通用Region和专属Region，通用Region指面向公共租户提供通用云服务的Region；专属Region指只承载同一类业务或只面向特定租户提供业务服务的专用Region。 详情请参见区域和可用区。 可用区（AZ，Availability Zone） 一个可用区是一个或多个物理数据中心的集合，有独立的风火水电，AZ内逻辑上再将计算、网络、存储等资源划分成多个集群。一个Region中的多个AZ间通过高速光纤相连，以满足用户跨AZ构建高可用性系统的需求。 项目 区域默认对应一个项目，这个项目由系统预置，用来隔离物理区域间的资源（计算资源、存储资源和网络资源），以默认项目为单位进行授权，用户可以访问您账号中该区域的所有资源。如果您希望进行更加精细的权限控制，可以在区域默认的项目中创建子项目，并在子项目中创建资源，然后以子项目为单位进行授权，使得用户仅能访问特定子项目中的资源，使得资源的权限控制更加精确。 图1 项目隔离模型 同样在我的凭证下，您可以查看项目ID。 企业项目 企业项目是项目的升级版，针对企业不同项目间的资源进行分组和管理，是逻辑隔离。企业项目中可以包含多个区域的资源，且项目中的资源可以迁入迁出。 关于企业项目ID的获取及企业项目特性的详细信息，请参见《企业管理用户指南》。 父主题： 使用前必读

概述 欢迎使用键值存储服务（Key-Value Storage Service, KVS）。键值存储服务提供完全托管的键值存储及索引服务，主要用于应用的键值类数据（如：元数据、描述数据、管理参数、状态数据）的存储，提供可预测的性能和无缝扩展，无需进行分区管理、硬件预置、集群扩展等操作。 您可以使用本文档提供API对键值存储服务进行相关操作，如创建、查询、删除、更新等。支持的全部操作请参见API概览。 在调用键值存储服务API之前，请确保已经充分了解键值存储服务相关概念，详细信息请参见《用户指南》的“产品介绍”。 父主题： 使用前必读

请求示例 更新单个kv，设置表名为test-table-1，设置更新的kv分区键值为user1，排序键为test-file-1，设置更新的鑫数据为非结构化数据。 POST https://{endpoint}/v1/update-kv { "table_name" : "test-table-1", "primary_key" : { "owner" : "user-1", "filename" : "test-file-1" }, "update_fields" : { "set" : { "updateKey" : "updateValue" } } }

请求参数 表2 请求Body参数 参数 是否必选 参数类型 描述 table_name 是 String 表名，仓内唯一。 长度：[3, 63] 取值字符限制：[a-z0-9_-]+ primary_key 是 Document 用户自定义的主键名及值。 说明： 内容字段：主键字段名和值，组合索引多个元素。 condition_expression 否 condition_expression object 条件表达式，参见conditional小节，禁止携带主键字段。 update_fields 否 update_fields object 对kv_doc有效。 表3 condition_expression 参数 是否必选 参数类型 描述 single_field_expression 否 single_field_expression object 单字段条件。 multi_field_expression 否 multi_field_expression object 多字段条件，多个相同优先级的单字段条件。 composed_expression 否 composed_expression object 组合条件, 逐层同级的子表达式嵌套。 表4 multi_field_expression 参数 是否必选 参数类型 描述 logic 否 String 多字段条件，多个相同优先级的单字段条件。 expressions 是 Array of single_field_expression objects 多个相同逻辑操作的单字段条件。 表5 single_field_expression 参数 是否必选 参数类型 描述 field 是 String 条件字段。 func 是 String 条件函数，取值如"$gt", $lt","$gte", $lte" "$eq", "$ne", "$prefix", "$exists"。 value 否 Document value和value_array二选一。 value条件值，适用于除"$in", "$nin"外的func。 字段名无意义，可以传空，也可以传字段名。 $exists值为true/false。 说明： $prefix操作只适用于string和binary类型。 value_array 否 Array of strings "value"和"value_array"二选一。 "value_array" 条件值列表, 值用于"$in", "$nin"。 表6 composed_expression 参数 是否必选 参数类型 描述 logic 否 String 逻辑关系，取值如"$and", "$or", "$nor"。 expressions 是 Array of expression objects 多个相同优先级且相同逻辑的单字段或多字段条件。 表7 expression 参数 是否必选 参数类型 描述 single_field_expression 否 single_field_expression object 单字段条件。 multi_field_expression 否 single_field_expression object 多字段条件，多个相同优先级的单字段条件。 composed_expression 否 composed_expression object 组合条件, 逐层同级的子表达式嵌套。 表8 update_fields 参数 是否必选 参数类型 描述 set 否 Document 新增字段或覆盖1个或多个字段的值。 说明： 禁止修改sortkey的字段。 add 否 Document 对1个或多个字段做加法运算，并更新为运算后的值。 rmv 否 Array of strings 删除1个或多个字段。 数组元素为待删除字段名。 insert 否 Document 插入元素到数组中 说明： 非数组返回失败。 delete 否 Document 从数组中删除某个元素 说明： 值不存在则返回失败。

URI POST /v1/update-kv 表1 Query参数 参数 是否必选 参数类型 描述 store_name 否 String 仓名，全域唯一，不同租户的仓名不能相同。 格式：${prefix}-${region-code}-${account-id}，其中prefix为自定义前缀，region-code为kvs集群所在的区域代码，account-id为用户的账户id 取值字符限制：[a-z0-9-]+ 长度：[16,52] 说明： "-"不能出现在名字头部或尾部

响应参数 状态码： 200 表8 响应Body参数 参数 参数类型 描述 returned_count Long 返回的文档数量，为0不表示结束。 如果filtered_count超过500仍无匹配，则返回0。 长度：4 filtered_count Integer 被过滤掉的文档数量。 长度：4 cursor_sort_key Document 下次请求时的start_key。 说明： 该值为空时，表示指定范围或者指定filter条件所有kv已经返回。 returned_kv_items Array of returned_kv_item objects 返回的kv列表，与scan-kv接口的returned_kv_item字段相同。 表9 returned_kv_item 参数 参数类型 描述 kv_doc Document 对kv_doc有效。

响应示例 状态码： 200 表示扫描分区键内kv请求成功 { "returned_count" : 1, "filtered_count" : 0, "kv_array" : [ { "returned_kv_items" : { "kv_doc" : { "owner" : "user-1", "filename" : "test-file-1", "otherkey" : "otherValue" } } } ] }

URI POST /v1/scan-skey-kv 表1 Query参数 参数 是否必选 参数类型 描述 store_name 否 String 仓名，全域唯一，不同租户的仓名不能相同。 格式：${prefix}-${region-code}-${account-id}，其中prefix为自定义前缀，region-code为kvs集群所在的区域代码，account-id为用户的账户id 取值字符限制：[a-z0-9-]+ 长度：[16,52] 说明： "-"不能出现在名字头部或尾部

请求参数 表2 请求Body参数 参数 是否必选 参数类型 描述 table_name 是 String 表名，仓内唯一。 长度：[3, 63] 取值字符限制：[a-z0-9_-]+ hint_index_name 否 String create_table时指定的索引名。 limit 否 Long 返回的文档个数，最大100个。 说明： 默认100个文档。 shard_key 是 Document 要遍历的指定分区键下的kv。 start_sort_key 否 Document 起始排序键值，默认空表示从头遍历，左闭。 说明： 分页返回时，该值使用上次响应返回的cursor_sort_key end_sort_key 否 Document 终止主键或索引键值，默认空表示直到最后，右开。 filter_expression 否 condition_expression object 过滤表达式。 说明： 允许主键字段作为条件。 在满足shard_key和start_sort_key和end_sortkey的范围内，执行filter逻辑。 表3 condition_expression 参数 是否必选 参数类型 描述 single_field_expression 否 single_field_expression object 单字段条件。 multi_field_expression 否 multi_field_expression object 多字段条件，多个相同优先级的单字段条件。 composed_expression 否 composed_expression object 组合条件, 逐层同级的子表达式嵌套。 表4 multi_field_expression 参数 是否必选 参数类型 描述 logic 否 String 多字段条件，多个相同优先级的单字段条件。 expressions 是 Array of single_field_expression objects 多个相同逻辑操作的单字段条件。 表5 single_field_expression 参数 是否必选 参数类型 描述 field 是 String 条件字段。 func 是 String 条件函数，取值如"$gt", $lt","$gte", $lte" "$eq", "$ne", "$prefix", "$exists"。 value 否 Document value和value_array二选一。 value条件值，适用于除"$in", "$nin"外的func。 字段名无意义，可以传空，也可以传字段名。 $exists值为true/false。 说明： $prefix操作只适用于string和binary类型。 value_array 否 Array of strings "value"和"value_array"二选一。 "value_array" 条件值列表, 值用于"$in", "$nin"。 表6 composed_expression 参数 是否必选 参数类型 描述 logic 否 String 逻辑关系，取值如"$and", "$or", "$nor"。 expressions 是 Array of expression objects 多个相同优先级且相同逻辑的单字段或多字段条件。 表7 expression 参数 是否必选 参数类型 描述 single_field_expression 否 single_field_expression object 单字段条件。 multi_field_expression 否 single_field_expression object 多字段条件，多个相同优先级的单字段条件。 composed_expression 否 composed_expression object 组合条件, 逐层同级的子表达式嵌套。

请求示例 扫描所有kv，扫描条件为分区键的值为user2 POST https://{endpoint}/v1/scan-kv { "table_name" : "test-table-1", "filter_expression" : { "single_field_expr" : { "field" : "owner", "func" : "$eq", "value" : { "value" : "user-2" } } } }

响应示例 状态码： 200 表示扫描所有kv请求成功 { "returned_count" : 1, "filtered_count" : 0, "returned_kv_items" : [ { "kv_doc" : { "owner" : "user-2", "filename" : "test-file-2", "otherKey" : "otherValue" } } ] }

响应参数 状态码： 200 表9 响应Body参数 参数 参数类型 描述 returned_count Long 返回的文档数量，为0不表示结束。 说明： 如果filtered_count超过500仍无匹配，则返回0。 filtered_count Integer 被过滤掉的文档数量。 cursor_key Document 下次请求时的start_key，该值为空时，表示指定范围或者指定filter条件所有kv已经返回。 returned_kv_items Array of returned_kv_item objects 返回的kv列表。 表10 returned_kv_item 参数 参数类型 描述 kv_doc Document 对kv_doc有效。

请求参数 表2 请求Body参数 参数 是否必选 参数类型 描述 table_name 是 String 表名，仓内唯一。 长度：[3, 63] 取值字符限制：[a-z0-9_-]+ hint_index_name 否 String create_table时指定的索引名，默认空表示主索引。 长度：[3, 63] 取值字符限制：[a-z0-9_-]+ limit 否 Integer 返回的文档个数，最大100个。 说明： 默认100个文档。 start_key 否 Document 起始主键或索引键值。 默认空，表示从头遍历，左闭。 说明： 分页返回时，该值使用上次响应返回的cursor_key。 end_key 否 Document 终止主键或索引键值。 默认空，表示直到最后，右开。 filter_expression 否 condition_expression object 过滤表达式。 说明： 允许键字段作为条件。 在满足start_key和endkey的范围内，执行filter逻辑。 sample_segments_count 否 Integer 对表进行采样，尽最大努力保证返回的段列表均分整张表。举例：sample_segments_count=4，返回的段列表[MinKey, KV1)、[KV1,KV2)、[KV2,KV3)和[KV3,MaxKey)。用户可以使用scan-kv对这四个分区执行并发扫描，提高遍历效率。 范围: [1, 10000]。默认值：不执行采样。 sample_segments_count仅能和table_name、start_key和end_key字段配合使用。Range分区模式下支持全表采样和范围采样；Hash分区模式仅支持全表扫描。 仅支持对Primary key进行采样，不支持本地/全局二级索引。 返回的段列表仅包含主键，不包含键值；且段列表是编码后的数据 ，不可修改。 return_count_only 否 Boolean 是否只返回满足条件的KV个数； true:响应rsp只返回"returned_count"、"filtered_count"和"cursor_key"（如果有"cursor_key"）。 false:scan-kv的标准响应体定义返回消息。 returned_segment_items 否 Array of returned_segment_item objects 采样段区间列表。 表3 condition_expression 参数 是否必选 参数类型 描述 single_field_expression 否 single_field_expression object 单字段条件。 multi_field_expression 否 multi_field_expression object 多字段条件，多个相同优先级的单字段条件。 composed_expression 否 composed_expression object 组合条件, 逐层同级的子表达式嵌套。 表4 multi_field_expression 参数 是否必选 参数类型 描述 logic 否 String 多字段条件，多个相同优先级的单字段条件。 expressions 是 Array of single_field_expression objects 多个相同逻辑操作的单字段条件。 表5 single_field_expression 参数 是否必选 参数类型 描述 field 是 String 条件字段。 func 是 String 条件函数，取值如"$gt", $lt","$gte", $lte" "$eq", "$ne", "$prefix", "$exists"。 value 否 Document value和value_array二选一。 value条件值，适用于除"$in", "$nin"外的func。 字段名无意义，可以传空，也可以传字段名。 $exists值为true/false。 说明： $prefix操作只适用于string和binary类型。 value_array 否 Array of strings "value"和"value_array"二选一。 "value_array" 条件值列表, 值用于"$in", "$nin"。 表6 composed_expression 参数 是否必选 参数类型 描述 logic 否 String 逻辑关系，取值如"$and", "$or", "$nor"。 expressions 是 Array of expression objects 多个相同优先级且相同逻辑的单字段或多字段条件。 表7 expression 参数 是否必选 参数类型 描述 single_field_expression 否 single_field_expression object 单字段条件。 multi_field_expression 否 single_field_expression object 多字段条件，多个相同优先级的单字段条件。 composed_expression 否 composed_expression object 组合条件, 逐层同级的子表达式嵌套。 表8 returned_segment_item 参数 是否必选 参数类型 描述 segment_min_key 否 Document 采样段区间起始值。 segment_max_key 否 Document 采样段区间终止值。

URI POST /v1/scan-kv 表1 Query参数 参数 是否必选 参数类型 描述 store_name 否 String 仓名，全域唯一，不同租户的仓名不能相同。 格式：${prefix}-${region-code}-${account-id}，其中prefix为自定义前缀，region-code为kvs集群所在的区域代码，account-id为用户的账户id 取值字符限制：[a-z0-9-]+ 长度：[16,52] 说明： "-"不能出现在名字头部或尾部

请求示例 上传单个kv，表名为test-table-1，上传的kv为非结构化数据 POST https://{endpoint}/v1/put-kv { "table_name" : "test-table-1", "kv_doc" : { "owner" : "user-1", "filename" : "test-file-1", "otherKey" : "other" } }

URI POST /v1/put-kv 表1 Query参数 参数 是否必选 参数类型 描述 store_name 否 String 仓名，全域唯一，不同租户的仓名不能相同。 格式：${prefix}-${region-code}-${account-id}，其中prefix为自定义前缀，region-code为kvs集群所在的区域代码，account-id为用户的账户id 取值字符限制：[a-z0-9-]+ 长度：[16,52] 说明： "-"不能出现在名字头部或尾部

请求参数 表2 请求Body参数 参数 是否必选 参数类型 描述 table_name 是 String 表名，仓内唯一。 长度：[3, 63] 取值字符限制：[a-z0-9_-]+ condition_expression 否 condition_expression object 条件表达式，参见conditional小节。 长度：[8,4096] kv_doc 否 Document 用户文档。 表3 condition_expression 参数 是否必选 参数类型 描述 single_field_expression 否 single_field_expression object 单字段条件。 multi_field_expression 否 multi_field_expression object 多字段条件，多个相同优先级的单字段条件。 composed_expression 否 composed_expression object 组合条件, 逐层同级的子表达式嵌套。 表4 multi_field_expression 参数 是否必选 参数类型 描述 logic 否 String 多字段条件，多个相同优先级的单字段条件。 expressions 是 Array of single_field_expression objects 多个相同逻辑操作的单字段条件。 表5 single_field_expression 参数 是否必选 参数类型 描述 field 是 String 条件字段。 func 是 String 条件函数，取值如"$gt", $lt","$gte", $lte" "$eq", "$ne", "$prefix", "$exists"。 value 否 Document value和value_array二选一。 value条件值，适用于除"$in", "$nin"外的func。 字段名无意义，可以传空，也可以传字段名。 $exists值为true/false。 说明： $prefix操作只适用于string和binary类型。 value_array 否 Array of strings "value"和"value_array"二选一。 "value_array" 条件值列表, 值用于"$in", "$nin"。 表6 composed_expression 参数 是否必选 参数类型 描述 logic 否 String 逻辑关系，取值如"$and", "$or", "$nor"。 expressions 是 Array of expression objects 多个相同优先级且相同逻辑的单字段或多字段条件。 表7 expression 参数 是否必选 参数类型 描述 single_field_expression 否 single_field_expression object 单字段条件。 multi_field_expression 否 single_field_expression object 多字段条件，多个相同优先级的单字段条件。 composed_expression 否 composed_expression object 组合条件, 逐层同级的子表达式嵌套。

响应参数 状态码： 200 表3 响应Body参数 参数 参数类型 描述 cursor_name String 本次响应后的游标位置，下次请求时携带，如果为空，表示后面无更多。 长度：[3, 63] 取值字符限制：[a-z0-9_-]+ 说明： 如果为空，表示后面无更多。 table_names Array of strings 返回的表名列表。 长度：最大100 状态码： 400 表4 响应Body参数 参数 参数类型 描述 error_code String 请求返回的错误码。 error_msg String 请求返回的错误信息。

URI POST /v1/list-table 表1 Query参数 参数 是否必选 参数类型 描述 store_name 否 String 仓名，全域唯一，不同租户的仓名不能相同。 格式：${prefix}-${region-code}-${account-id}，其中prefix为自定义前缀，region-code为kvs集群所在的区域代码，account-id为用户的账户id 取值字符限制：[a-z0-9-]+ 长度：[16,52] 说明： "-"不能出现在名字头部或尾部

响应参数 状态码： 200 表2 响应Body参数 参数 参数类型 描述 cursor_name String 本次响应后的游标位置，下次请求时携带。 长度：[16,52] 取值字符限制：[a-z0-9-]+ 说明： 如果为空，表示后面无更多仓名。 stores Array of strings 返回的仓名列表。 状态码： 400 表3 响应Body参数 参数 参数类型 描述 error_code String 请求返回的错误码。 error_msg String 请求返回的错误信息。

URI POST /v1/get-kv 表1 Query参数 参数 是否必选 参数类型 描述 store_name 否 String 仓名，全域唯一，不同租户的仓名不能相同。 格式：${prefix}-${region-code}-${account-id}，其中prefix为自定义前缀，region-code为kvs集群所在的区域代码，account-id为用户的账户id 取值字符限制：[a-z0-9-]+ 长度：[16,52] 说明： "-"不能出现在名字头部或尾部

请求示例 下载一个kv，表名为test-table-1，设置分区键值为user1，排序键值为test-file-1。 POST https://{endpoint}/v1/get-kv { "table_name" : "test-table-1", "primary_key" : { "owner" : "user-1", "filename" : "test-file-1" } }

错误码说明 当您调用API时，如果遇到“APIGW”开头的错误码，请参见API网关错误码进行处理。 表1 错误码 状态码 错误码 错误信息 描述 处理措施 500 Internal Server Error KVS.00000001 InternalError 系统遇到内部错误，请重试 请联系技术支持 501 Not Implemented KVS.00000002 ServiceNotImplemented 请求的方法服务端没有实现 当前不支持，请联系技术支持 503 Service Unavailable KVS.00000003 SlowDown 请求频率过高 请降低请求频率 400 Bad Request KVS.00001001 Invalid request parameter 请求参数非法 根据返回的错误消息体提示进行修改 403 Forbidden KVS.000010010 AccessDenied 拒绝访问，请求没有携带日期头域或者头域格式错误 请求携带正确的日期头域 400 Bad Request KVS.00001002 InvalidStore 请求访问的Store已不存在，或者状态不正确 更换Store名 400 Bad Request KVS.00001003 InvalidTable 请求访问的Table已不存在，或者状态不正确 更换Table名 400 Bad Request KVS.00001004 EntityTooLarge 请求超过大小限制 减少大小 400 Bad Request KVS.00001005 IncompleteBody 由于网络原因或其他问题导致请求体未接受完整 重试 400 Bad Request KVS.00001006 InvalidRequest 无效请求 body体不合法，或者没有携带，根据返回的错误消息体提示进行修改 400 Bad Request KVS.00001007 TooManyStores 用户拥有的Store的数量达到了系统的上限，并且请求试图创建一个新Store 删除部分Store后重试 400 Bad Request KVS.00001008 TooManyTables 用户Store拥有的Tables的数量达到了系统的上限，并且请求试图创建一个新Tables 删除部分Table后重试，或选取其他Store 400 Bad Request KVS.00001009 TooManyKeyValues 超出单分区键的kv限制 - 403 Forbidden KVS.00001011 AccessForbidden 权限不足 检查权限配置 403 Forbidden KVS.00001012 InArrearsOrInsufficientBalance 用户欠费或余额不足而没有权限进行某种操作 充值 403 Forbidden KVS.00001013 InsufficientStorageSpace 存储空间不足 超过配额限制，增加配额或删除部分对象 404 Not Found KVS.00001014 NoSuchStore 指定的Store不存在 先创Store再操作 404 Not Found KVS.00001015 NoSuchTable 指定的Table不存在 先创Table再操作 404 Not Found KVS.00001016 NoSuchKey 指定的Key不存在 先PUT 408 Request Timeout KVS.00001017 RequestTimeout 用户与Server之间的socket连接在超时时间内没有进行读写操作 检查网络后重试，或联系技术支持 409 Conflict KVS.00001018 StoreAlreadyExists 请求的Store名已经存在Store的命名空间是系统中所有用户共用的，选择一个不同的Store名再重试一次 更换Store名 409 Conflict KVS.00001019 StoreNotEmpty 用户尝试删除的Store不为空 先删除Store中对象，然后再删Store 409 Conflict KVS.00001020 TableAlreadyExists 请求的Table名已经存在，选择一个不同的Table名再重试一次 更换Table名 409 Conflict KVS.00001021 TableNotEmpty 用户尝试删除的Table不为空 先删除Table中对象，然后再删Table 409 Conflict KVS.00001022 OperationAborted 另外一个冲突的操作当前正作用在这个资源上，请重试 等待一段时间后重试 503 Service Unavailable KVS.00001023 SlowDown 请求频率过高 请降低请求频率 400 Bad Request KVS.00005000 RegionIsNotOnService Region不支持创建store 等待一段时间后重试 400 Bad Request KVS.00005001 RegionNumberExceedLimit Region数量超过限制 减少Region数量 400 Bad Request KVS.00005002 TableAlreadySwitchOnPITR 下面的某个表已经打开了PITR 无需重复开启PITR 400 Bad Request KVS.00005004 BackupNameConflict 备份名冲突 更换备份名 400 Bad Request KVS.00005006 BackupNameNotExit 备份名不存在 - 400 Bad Request KVS.00005007 BackupNameIsCreateing 备份正在创建 等待备份创建完成 400 Bad Request KVS.00005008 BackupNameNotAvailable 备份名无效 更换备份名 400 Bad Request KVS.00005009 RecoveryTimeStampInvalid 恢复时间点无效 更换恢复时间点 400 Bad Request KVS.00005010 Local2ndIndexNumberExceedLimit 本地二级索引数量超过限制 减少本地二级索引数量 400 Bad Request KVS.00005011 Global2ndIndexNumberExceedLimit 全局二级索引数量超过限制 减少全局二级索引数量 400 Bad Request KVS.00005012 PrimaryKeyIndexSchemaInvalid 主键索引模板定义无效 检查模板定义参数 400 Bad Request KVS.00005013 Local2ndIndexSchemaInvalid 本地二级索引模板定义无效 检查模板定义参数 400 Bad Request KVS.00005014 Global2ndIndexSchemaInvalid 全局二级索引模板定义无效 检查模板定义参数 400 Bad Request KVS.00005015 StoreAlreadySwitchOnPITR store已经打开了PITR 无需重复开启PITR 400 Bad Request KVS.00005016 ConditionExpressionInvalid 条件表达式超过上线，或者语法不正确，或者预定义变量找不到 检查条件表达式定义 400 Bad Request KVS.00005017 ConditionIsFalse 条件表达式非真 - 400 Bad Request KVS.00005018 keyValueSizeExceedLimited KV大小超过限制 缩减文档数据量 400 Bad Request KVS.00005019 ReturnPartialBlobIsInvalid ReturnPartialBlob指定的偏移无效 修改偏移参数值 400 Bad Request KVS.00005020 BatchExceedLimit batch大小或操作个数超限 减少操作个数

响应示例 状态码： 200 表示查询表请求成功 { "table_name" : "test-table-1", "primary_key_schema" : { "shard_key_fields" : [ { "name" : "owner", "order" : true } ], "sort_key_fields" : [ { "name" : "filename", "order" : true } ] }, "runtime_info" : { "table_info" : { "table_status" : "ACTIVE" } } }