跳到主要内容

v1 API 获取对外查询可用字段

API 使用者，在创建或编辑对外查询前，可以通过本接口获取该表单允许作为查询条件、允许展示的字段

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

认证方式​

V1 Bearer 认证方式

headers 设置​

需要在请求中设置如下 headers

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

接口说明​

  • 创建或编辑对外查询前请先调用本接口，search_field_rules / display_field_rules 里的 api_code 必须来自这里。
  • 不要用获取单个表单结构的 api_code 代替：对外查询额外提供表单结构里没有的字段（如 serial_number、created_at、updated_at、info_filling_duration、考试得分、展开的关联表单字段），同时也会拒绝一部分表单字段。用表单结构里的 api_code 可能被拒。
  • 调用方需要是该表单的管理员；能读表单但无管理权时返回 403，表单不存在或不可访问时返回 404。
  • recommend_display_fields 是编辑器的预选集合，几乎涵盖所有字段 —— 不要直接照搬，应由使用者明确选择哪些字段可以对外展示。

接口描述​

Request​

GET https://jinshuju.net/api/v1/opensearch/query_suggestions?form_token=FORM_TOKEN
参数名称是否必须类型说明
form_token是String表单 Token（Query 参数）。注意这里传的是表单 token，不是对外查询 token

Response​

{
    "form_token": "wX7pQ2",
    "search_fields": [
        {
            "api_code": "field_2",
            "label": "手机号",
            "type": "MobileField",
            "privacy_protectable": true,
            "for_associated": false
        }
    ],
    "display_fields": [
        {
            "api_code": "field_1",
            "label": "姓名",
            "type": "NameField",
            "privacy_protectable": true,
            "for_associated": false,
            "editable": false,
            "scorable": false
        }
    ],
    "recommend_search_fields": ["field_1", "field_2"],
    "recommend_display_fields": ["field_1", "field_2", "field_3", "created_at"]
}
参数名称是否必须类型说明
form_token是String表单 Token
search_fields是Array可用作查询条件的字段，即 search_field_rules[].search_field_settings[].field_api_code 的合法取值
display_fields是Array可用于展示的字段，即 display_field_rules[].field_api_code 的合法取值
*[].api_code是String字段 api_code
*[].label是String字段标题
*[].type是String字段类型名
*[].privacy_protectable是Bool该字段的值能否脱敏；只有为 true 时 display_field_rules[].protected 才生效
*[].for_associated是Bool是否来自关联表单的展开字段
display_fields[].editable是Bool该字段能否允许访问者在结果页编辑；只有为 true 时 display_field_rules[].editable 才生效
display_fields[].scorable是Bool是否为考试得分类字段
recommend_search_fields是Array(String)推荐作为查询条件的 api_code，可直接使用。为空数组说明该表单没有手机号字段可推荐，此时应由使用者指定查询字段
recommend_display_fields是Array(String)编辑器的展示字段预选集合，不要不加筛选地直接使用

状态码​

状态码说明
200获取成功
401未认证
402当前套餐不支持 V1 API
403能访问该表单但不是表单管理员
404表单不存在或无权访问

示例代码​

HTTP​

GET https://jinshuju.net/api/v1/opensearch/query_suggestions?form_token=$FORM_TOKEN

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

Python​

import requests

access_token = 'YOUR_ACCESS_TOKEN'

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

print(response.text)