查询记录列表

获取对象中符合指定条件的记录列表

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/apaas/v1/applications/:namespace/objects/:object_api_name/records/batch_query
HTTP Method	POST
接口频率限制	1000 次/分钟、50 次/秒
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用	app_engine:object.record:read 查看对象记录数据

请求头

名称	类型	必填	描述
Authorization	string	是	tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Type	string	是	固定值："application/json; charset=utf-8"

路径参数

名称	类型	描述
namespace	string	命名空间 示例值："package_test__c" 数据校验规则： - 长度范围：0 ～ 256 字符
object_api_name	string	目标对象的唯一标识符 示例值："_user" 数据校验规则： - 长度范围：0 ～ 256 字符

请求体

名称	类型	必填	描述
select	string\[\]	是	需要获取的字段，使用字段唯一标识符进行查询，关联字段可使用「.」进行下钻 示例值：["_name"] 数据校验规则： - 长度范围：0 ～ 256
filter	criterion	否	筛选条件，通过 JSON 格式指定条件
└ conditions	condition\[\]	否	查询条件 数据校验规则： - 长度范围：0 ～ 10
└ index	string	否	序号 示例值："1"
└ left	condition_value	否	左值
└ type	string	否	左值类型，只支持 "metadataVariable"，表示字段 示例值："metadataVariable"
└ settings	string	否	字段具体值，以 JSONString 表示，格式：{"fieldPath":[{"fieldApiName": "字段名","objectApiName": "对象名"}]} 示例值："{\"fieldPath\":[{\"fieldApiName\": \"_id\",\"objectApiName\": \"_user\"}]}"
└ right	condition_value	否	右值
└ type	string	否	右值类型，只支持 "constant"，表示常量 示例值："constant"
└ settings	string	否	常量具体值，以 JSONString 表示，格式：{"data":"常量具体值"} 示例值："{\"data\":\"123456\"}"
└ operator	string	否	操作符 示例值："equals"
└ logic_expression	string	否	逻辑关系 示例值："1 and 2"
order_by	sort\[\]	否	排序参数，通过 JSON 格式指定条件。其中， field 为参与排序字段，direction 为排序方向，多个条件按其在数组中的顺序生效。 数据校验规则： - 长度范围：0 ～ 256
└ field	string	是	字段唯一标识 示例值："_id" 数据校验规则： - 长度范围：0 ～ 256 字符
└ direction	string	是	排序方向，值为 "ASC" 或者 "DESC"，代表升序和降序 示例值："ASC" 可选值有： - ASC: 升序 - DESC: 降序 数据校验规则： - 长度范围：0 ～ 256 字符
group_by	record_group_by_item\[\]	否	聚合参数，通过 JSON 格式指定条件。其中， field 为参与聚合的字段。 数据校验规则： - 长度范围：0 ～ 256
└ field	string	是	字段唯一标识 示例值："_id" 数据校验规则： - 长度范围：0 ～ 256 字符
page_token	string	否	分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果 示例值："eVQrYzJBNDNONlk4VFZBZVlSdzlKdFJ4bVVHVExENDNKVHoxaVdiVnViQT0="
use_page_token	boolean	否	是否使用 page_token 功能。为 True 时将使用 page_token 的值作为起始位置查询记录，并且会在 Response 中返回 next_page_token 。默认为 False 。 示例值：false
page_size	int	否	期望服务端返回的记录条数，上限 500 条。不填则取默认值，默认值为 500。 示例值：100
offset	int	否	返回记录的偏移量，默认为 0 ，即从查询到的第一条记录开始返回。offset 较大时查询性能较差，可能引起接口响应超时，拉取全部记录时建议使用 ID 游标分页，具体见 ID 游标分页说明 示例值：0 数据校验规则： - 取值范围：0 ～ 10000000000
need_total_count	boolean	否	是否返回符合条件的记录总数（Total）。默认为 False，不返回记录总数。 示例值：true

请求体示例

{
    "select": [
        "_name"
    ],
    "filter": {
        "conditions": [
            {
                "index": "1",
                "left": {
                    "type": "metadataVariable",
                    "settings": "{\"fieldPath\":[{\"fieldApiName\": \"_id\",\"objectApiName\": \"_user\"}]}"
                },
                "right": {
                    "type": "constant",
                    "settings": "{\"data\":\"123456\"}"
                },
                "operator": "equals"
            }
        ],
        "logic_expression": "1 and 2"
    },
    "order_by": [
        {
            "field": "_id",
            "direction": "ASC"
        }
    ],
    "group_by": [
        {
            "field": "_id"
        }
    ],
    "page_token": "eVQrYzJBNDNONlk4VFZBZVlSdzlKdFJ4bVVHVExENDNKVHoxaVdiVnViQT0=",
    "use_page_token": false,
    "page_size": 100,
    "offset": 0,
    "need_total_count": true
}

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ items	string	符合条件的记录列表
└ total	int	符合条件的记录数
└ next_page_token	string	下一页的起始位置 Token ，访问至末尾时不返回
└ has_more	boolean	是否还有更多项

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "items": "[{}]",
        "total": 0,
        "next_page_token": "null",
        "has_more": true
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	2320001	param is invalid	请检查输入参数