ZincSearch 搜索引擎 API 接口详解-CSDN博客

本文链接：https://blog.csdn.net/gitblog_00844/article/details/148375268

ZincSearch 搜索引擎 API 接口详解

zincsearch ZincSearch . A lightweight alternative to elasticsearch that requires minimal resources, written in Go. 项目地址: https://gitcode.com/gh_mirrors/zi/zincsearch

概述

ZincSearch 是一个轻量级的全文搜索引擎，提供了丰富的 RESTful API 接口用于索引管理和文档操作。本文将详细介绍 ZincSearch 的主要 API 功能和使用方法，帮助开发者快速掌握其核心功能。

认证与权限

ZincSearch 采用 BasicAuth 认证方式，大部分 API 都需要认证后才能访问。系统提供了用户登录接口：

"/api/login": {
  "post": {
    "consumes": ["application/json"],
    "produces": ["application/json"],
    "tags": ["User"],
    "summary": "Login",
    "operationId": "Login",
    "parameters": [
      {
        "description": "Login credentials",
        "name": "login",
        "in": "body",
        "required": true,
        "schema": {
          "$ref": "#/definitions/auth.LoginRequest"
        }
      }
    ],
    "responses": {
      "200": {
        "description": "OK",
        "schema": {
          "$ref": "#/definitions/auth.LoginResponse"
        }
      }
    }
  }
}

登录成功后，系统会返回认证令牌，后续请求需要在 Header 中携带该令牌。

索引管理

创建索引

创建索引是使用 ZincSearch 的第一步，通过以下 API 可以创建新的索引：

"/api/index": {
  "post": {
    "security": [{"BasicAuth": []}],
    "consumes": ["application/json"],
    "produces": ["application/json"],
    "tags": ["Index"],
    "summary": "Create index",
    "operationId": "CreateIndex",
    "parameters": [
      {
        "description": "Index data",
        "name": "data",
        "in": "body",
        "required": true,
        "schema": {
          "$ref": "#/definitions/meta.IndexSimple"
        }
      }
    ],
    "responses": {
      "200": {
        "description": "OK",
        "schema": {
          "$ref": "#/definitions/meta.HTTPResponseIndex"
        }
      }
    }
  }
}

请求体需要包含索引的基本信息，如索引名称、分片数等配置参数。

查询索引列表

获取当前系统中所有索引的列表：

"/api/index": {
  "get": {
    "security": [{"BasicAuth": []}],
    "produces": ["application/json"],
    "tags": ["Index"],
    "summary": "List indexes",
    "operationId": "ListIndexes",
    "parameters": [
      {
        "type": "integer",
        "description": "page num",
        "name": "page_num",
        "in": "query"
      },
      {
        "type": "integer",
        "description": "page size",
        "name": "page_size",
        "in": "query"
      }
    ],
    "responses": {
      "200": {
        "description": "OK",
        "schema": {
          "$ref": "#/definitions/index.IndexListResponse"
        }
      }
    }
  }
}

该接口支持分页查询，可以通过 page_num 和 page_size 参数控制返回结果。

索引操作

对单个索引的操作包括：

获取索引元数据
删除索引
检查索引是否存在
刷新索引

"/api/index/{index}": {
  "get": {
    "summary": "Get index metadata"
  },
  "delete": {
    "summary": "Delete index"
  },
  "head": {
    "summary": "Checks if the index exists"
  }
},
"/api/index/{index}/refresh": {
  "post": {
    "summary": "Resfresh index"
  }
}

文档操作

批量导入文档

ZincSearch 提供了两种批量导入文档的方式：

原始文本格式批量导入

"/api/_bulk": {
  "post": {
    "consumes": ["text/plain"],
    "produces": ["application/json"],
    "tags": ["Document"],
    "summary": "Bulk documents",
    "parameters": [
      {
        "description": "Query",
        "name": "query",
        "in": "body",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    ]
  }
}

JSON 格式批量导入（推荐）

"/api/_bulkv2": {
  "post": {
    "consumes": ["application/json"],
    "produces": ["application/json"],
    "tags": ["Document"],
    "summary": "Bulkv2 documents",
    "parameters": [
      {
        "description": "Query",
        "name": "query",
        "in": "body",
        "required": true,
        "schema": {
          "$ref": "#/definitions/meta.JSONIngest"
        }
      }
    ]
  }
}

JSON 格式的批量导入更加灵活，可以包含更多元数据信息。

文本分析

ZincSearch 提供了文本分析接口，可以查看文本是如何被分词和处理的：

"/api/_analyze": {
  "post": {
    "consumes": ["application/json"],
    "produces": ["application/json"],
    "tags": ["Index"],
    "summary": "Analyze",
    "parameters": [
      {
        "description": "Query",
        "name": "query",
        "in": "body",
        "required": true,
        "schema": {
          "type": "object"
        }
      }
    ]
  }
}

这个功能对于调试搜索查询和了解分词器行为非常有用。

权限管理

ZincSearch 提供了基本的权限管理功能：

"/api/permissions": {
  "get": {
    "produces": ["application/json"],
    "tags": ["Permission"],
    "summary": "List permissions"
  }
},
"/api/role": {
  "get": {
    "produces": ["application/json"],
    "tags": ["Role"],
    "summary": "List role"
  }
}

可以查询系统中可用的权限列表和角色信息。