FileConfig API

概述

FileConfig API是用于管理 Fess 文件爬虫设置的API。 可以操作本地文件系统、SMB/CIFS共享文件夹、FTP、各类对象存储等的爬虫设置。

基础URL

/api/admin/fileconfig

Note

所有端点均需要管理员权限及有效的访问令牌。 有关认证方式，请参阅 Admin API 概述 。

端点列表

方法	路径	说明
GET	/settings	获取文件爬虫设置列表
GET	/setting/{id}	获取文件爬虫设置
POST	/setting	创建文件爬虫设置
PUT	/setting	更新文件爬虫设置
DELETE	/setting/{id}	删除文件爬虫设置

获取文件爬虫设置列表

请求

GET /api/admin/fileconfig/settings

Note

列表获取端点除 GET 外，也可使用 PUT 访问。

参数

参数	类型	必需	说明
page	Integer	否	页码（从1开始，默认：1）
size	Integer	否	每页记录数（默认：25。遵循 paging.page.size 设置）
name	String	否	按设置名称筛选
paths	String	否	按爬虫路径筛选
description	String	否	按说明筛选

响应

{
  "response": {
    "status": 0,
    "settings": [
      {
        "id": "fileconfig_id_1",
        "name": "Shared Documents",
        "description": "共享文档",
        "paths": "smb://server/share/documents",
        "included_paths": ".*\\.pdf$",
        "excluded_paths": ".*/(temp|cache)/.*",
        "included_doc_paths": "",
        "excluded_doc_paths": "",
        "config_parameter": "",
        "depth": 10,
        "max_access_count": 1000,
        "num_of_thread": 1,
        "interval_time": 1000,
        "boost": 1.0,
        "available": "true",
        "permissions": "{role}admin",
        "virtual_hosts": "",
        "sort_order": 0
      }
    ],
    "total": 5
  }
}

total 表示符合条件的设置总数。

获取文件爬虫设置

请求

GET /api/admin/fileconfig/setting/{id}

响应

{
  "response": {
    "status": 0,
    "setting": {
      "id": "fileconfig_id_1",
      "name": "Shared Documents",
      "description": "共享文档",
      "paths": "smb://server/share/documents",
      "included_paths": ".*\\.pdf$",
      "excluded_paths": ".*/(temp|cache)/.*",
      "included_doc_paths": "",
      "excluded_doc_paths": "",
      "config_parameter": "",
      "depth": 10,
      "max_access_count": 1000,
      "num_of_thread": 1,
      "interval_time": 1000,
      "boost": 1.0,
      "available": "true",
      "sort_order": 0,
      "permissions": "{role}admin",
      "virtual_hosts": "",
      "created_by": "admin",
      "created_time": 1700000000000,
      "updated_by": "admin",
      "updated_time": 1700000000000,
      "version_no": 1
    }
  }
}

Note

响应中包含在注册和更新时由服务器自动设置的 created_by 、 created_time 、 updated_by 、 updated_time 、 version_no 字段。 version_no 在更新时为必填项（请参阅后述的”更新文件爬虫设置”）。

创建文件爬虫设置

请求

POST /api/admin/fileconfig/setting
Content-Type: application/json

请求体

{
  "name": "Local Files",
  "paths": "file:///data/documents",
  "included_paths": ".*\\.(pdf|doc|docx|xls|xlsx)$",
  "excluded_paths": ".*/(temp|backup)/.*",
  "num_of_thread": 2,
  "interval_time": 500,
  "boost": 1.0,
  "available": "true",
  "sort_order": 0,
  "permissions": "{role}admin\n{role}user"
}

字段说明

字段	必需	说明
name	是	设置名称（最多200个字符）
description	否	设置说明（最多1000个字符）
paths	是	爬虫起始路径（多个路径用换行符分隔）。使用 file: 、 smb: 、 smb1: 、 ftp: 、 s3: 、 gcs: 中的一种协议指定
included_paths	否	爬虫目标路径的正则表达式模式
excluded_paths	否	排除爬虫路径的正则表达式模式
included_doc_paths	否	索引目标路径的正则表达式模式
excluded_doc_paths	否	排除索引路径的正则表达式模式
config_parameter	否	附加配置参数（ key=value 格式，每行一项）
depth	否	爬虫深度（0以上）
max_access_count	否	最大访问数（0以上）
num_of_thread	是	并行线程数（1以上）
interval_time	是	访问间隔（毫秒，0以上）
boost	是	搜索结果提升值
available	是	启用/禁用（字符串 "true" / "false"）
sort_order	是	显示顺序（0以上）
permissions	否	访问权限角色（多个时用换行符分隔）
virtual_hosts	否	虚拟主机（多个时用换行符分隔）

Note

created_by 、 created_time 、 updated_by 、 updated_time 等审计字段 由服务器自动设置，无需在请求体中指定。

响应

{
  "response": {
    "status": 0,
    "id": "new_fileconfig_id",
    "created": true
  }
}

更新文件爬虫设置

请求

PUT /api/admin/fileconfig/setting
Content-Type: application/json

请求体

更新时，除创建时的字段外，还需要指定用于确定更新目标的 id 和版本号 version_no 。 version_no 需填写获取API（GET）响应中包含的当前值。

{
  "id": "existing_fileconfig_id",
  "name": "Updated Local Files",
  "paths": "file:///data/documents",
  "included_paths": ".*\\.(pdf|doc|docx|xls|xlsx|ppt|pptx)$",
  "excluded_paths": ".*/(temp|backup|archive)/.*",
  "depth": 10,
  "max_access_count": 10000,
  "num_of_thread": 3,
  "interval_time": 300,
  "boost": 1.2,
  "available": "true",
  "sort_order": 0,
  "version_no": 1
}

更新时的附加字段

字段	必需	说明
id	是	更新目标的设置ID（最多1000个字符）
version_no	是	更新目标的当前版本号。填写获取API（GET）响应中包含的 version_no 值

响应

{
  "response": {
    "status": 0,
    "id": "existing_fileconfig_id",
    "created": false
  }
}

删除文件爬虫设置

请求

DELETE /api/admin/fileconfig/setting/{id}

响应

{
  "response": {
    "status": 0
  }
}

路径格式

paths 可使用以下协议（支持的协议可通过 crawler.file.protocols 设置更改）。

协议	路径格式
本地文件	file:///path/to/directory
SMB/CIFS共享	smb://server/share/path
SMB/CIFS共享（SMB1）	smb1://server/share/path
FTP	ftp://server/path
Amazon S3／S3兼容对象存储（MinIO等）	s3://bucket/path
Google Cloud Storage	gcs://bucket/path

Note

SMB/CIFS及FTP的认证信息（用户名和密码）请勿嵌入路径中， 应通过”文件认证”设置进行配置。详情请参阅 文件认证 。

使用示例

本地文件爬虫设置

curl -X POST "http://localhost:8080/api/admin/fileconfig/setting" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Local Files",
       "paths": "file:///data/documents",
       "included_paths": ".*\\.(pdf|doc|docx)$",
       "excluded_paths": ".*/(temp|backup)/.*",
       "num_of_thread": 2,
       "interval_time": 500,
       "boost": 1.0,
       "available": "true",
       "sort_order": 0,
       "permissions": "{role}guest"
     }'

SMB共享爬虫设置

curl -X POST "http://localhost:8080/api/admin/fileconfig/setting" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "SMB Share",
       "paths": "smb://server/documents",
       "included_paths": ".*\\.(pdf|doc|docx)$",
       "excluded_paths": ".*/(temp|private)/.*",
       "max_access_count": 50000,
       "num_of_thread": 3,
       "interval_time": 200,
       "boost": 1.0,
       "available": "true",
       "sort_order": 0,
       "permissions": "{role}guest"
     }'

Note

如果访问SMB共享需要认证，请事先在”文件认证”设置中注册目标主机的认证信息。

参考信息

• Admin API 概述 - Admin API概述

• WebConfig API - Web爬虫设置API

• DataConfig API - 数据存储设置API

• 文件抓取（文件服务器搜索） - 文件爬虫设置指南

• 文件认证 - 文件认证设置指南