v1 API 获取单个对外查询

API 使用者，可以通过本接口，获取一个对外查询页面的完整配置

功能	免费版	专业版/专业增强版	企业基础版	企业协作版	企业高级版
对外查询	❌	✔️	✔️	✔️	✔️

认证方式

V1 Bearer 认证方式

headers 设置

需要在请求中设置如下 headers

• Content-Type: application/json
• Accept: application/json
• Authorization: Bearer YOUR_ACCESS_TOKEN

接口说明

• 只能获取自己创建的对外查询；别人创建的查询返回 404。
• search_field_rules 和 display_field_rules 在编辑对外查询时是 REPLACE 语义，所以改之前先用本接口把完整列表读出来再合并。
• messages 是已存下来的文案，未设置的 key 在公开页上会回落到产品默认值；default_messages 是回落之后的实际生效文案。编辑时要基于 messages 合并，不要基于 default_messages，否则会把默认值固化进记录里。

接口描述

Request

GET https://jinshuju.net/api/v1/opensearch/queries/QUERY_TOKEN

参数名称	是否必须	类型	说明
QUERY_TOKEN	是	String	对外查询 Token（URL 路径参数）

Response

{
    "token": "o5qeEX",
    "url": "https://demo.jinshuju.net/os/o5qeEX",
    "name": "成绩查询",
    "enabled": true,
    "form_token": "wX7pQ2",
    "created_at": "2026-09-07T16:11:37.532+08:00",
    "description": null,
    "status": "active",
    "search_field_rules": [
        {
            "operand": "and",
            "search_field_settings": [
                {
                    "field_api_code": "field_2",
                    "field_label": "手机号",
                    "fuzzy": false,
                    "sms_verification": false
                }
            ]
        }
    ],
    "display_field_rules": [
        {
            "field_api_code": "field_1",
            "field_label": null,
            "editable": false,
            "protected": true,
            "highlight": null
        }
    ],
    "messages": { "has_result": "查到了", "no_result": "没查到" },
    "default_messages": { "has_result": "查到了", "no_result": "没查到" },
    "search_button": {},
    "allow_to_export_results": false,
    "updated_at": "2026-09-07T16:11:56.412+08:00",
    "searches_count": 128,
    "views_count": 356
}

参数名称	是否必须	类型	说明
token	是	String	对外查询 Token
url	是	String	公开查询页地址
name	是	String	查询页标题
enabled	是	Boolean	是否启用
form_token	是	String / null	数据来源表单 Token；来源表单已删除时为 null
created_at	是	DateTime	创建时间
searches_count	是	Integer	累计查询次数
views_count	是	Integer	累计访问次数
description	是	String / null	查询页描述文案
status	是	String	查询页可用状态：active = 正常；entries_count_limited = 表单数据量超出套餐的对外查询上限，访问者会看到不可用提示；form_not_found = 来源表单已删除。与 enabled 无关，停用的查询 status 仍可能是 active
search_field_rules	是	Array(Object)	查询条件组，通常只有一组
search_field_rules[].operand	是	String	组内多个查询字段的关系：and = 全部匹配；or = 任一匹配
search_field_rules[].search_field_settings	是	Array(OpensearchSearchFieldSetting)	访问者需要填写的查询字段
display_field_rules	是	Array(Object)	命中数据展示的字段，按展示顺序
display_field_rules[].field_api_code	是	String	展示字段的 api_code
display_field_rules[].field_label	是	String / null	自定义标签；未设置为 null
display_field_rules[].editable	是	Boolean	是否允许访问者在结果页编辑该字段值
display_field_rules[].protected	是	Boolean	是否对值做隐私脱敏（如 张*三）
display_field_rules[].highlight	是	Object / null	高亮设置；未设置为 null
display_field_rules[].highlight.color	否	String / null	高亮颜色（CSS 颜色值）
display_field_rules[].highlight.position	否	Integer	多个高亮字段间的排序，越小越靠前
messages	是	Object / null	已存下来的结果文案；未设置的 key 不出现
messages.has_result	否	String	查到结果时的提示文案
messages.no_result	否	String	未查到结果时的提示文案
default_messages	是	Object	回落默认值之后的实际生效文案
default_messages.has_result	是	String	查到结果时的提示文案
default_messages.no_result	是	String	未查到结果时的提示文案
search_button	是	Object	查询按钮外观，包含 text / color；未设置时为 {}
search_button.text	否	String	按钮文字
search_button.color	否	String	按钮颜色
allow_to_export_results	是	Boolean	是否允许访问者导出查询结果
header	是	Object	页头设置
header.background_image	是	Object / null	页头背景图；未设置为 null
header.background_image.attachment_id	是	String	背景图附件 ID
header.background_image.position_x	是	Number / null	背景图横向位置
header.background_image.position_y	是	Number / null	背景图纵向位置
header.background_image.image_url	是	String / null	背景图地址
updated_at	是	DateTime	最后更新时间

状态码

状态码	说明
200	获取成功
401	未认证
402	当前套餐不支持 V1 API
403	无权限（如 OAuth scope 不足）
404	对外查询不存在，或不是当前调用方创建的

数据类型

OpensearchSearchFieldSetting

参数名称	是否必须	类型	说明
field_api_code	是	String	查询字段的 api_code，须在可用字段的 search_fields 中
field_label	否	String / null	展示给访问者的自定义标签；未设置（null）时用字段标题
fuzzy	否	Boolean	true = 包含匹配；false = 精确匹配（默认）
sms_verification	否	Boolean	查询前是否要求短信验证（仅手机号字段生效），默认 false

示例代码

HTTP

GET https://jinshuju.net/api/v1/opensearch/queries/$QUERY_TOKEN

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Python

import requests

access_token = 'YOUR_ACCESS_TOKEN'
query_token = 'YOUR_QUERY_TOKEN'

response = requests.get(
    f'https://jinshuju.net/api/v1/opensearch/queries/{query_token}',
    headers={'Authorization': f'Bearer {access_token}'}
)

print(response.text)