正在加载

使用稳定插件 API 创建文本分析插件

文本分析插件为 Elasticsearch 提供自定义的 Lucene 分析器、词元过滤器、字符过滤器和词元生成器。

稳定插件 API

文本分析插件可以针对稳定插件 API 进行开发。此 API 包括以下依赖项：

  • plugin-api - 插件开发人员用于实现自定义 Elasticsearch 插件的 API。
  • plugin-analysis-api - 插件开发人员用于实现分析插件并将其集成到 Elasticsearch 中的 API。
  • lucene-analysis-common - plugin-analysis-api 的依赖项，其中包含核心 Lucene 分析接口，如 Tokenizer、Analyzer 和 TokenStream。

对于同一主要版本中新版本的 Elasticsearch，针对此 API 构建的插件无需重新编译。该 API 的未来版本将向后兼容，并且插件与未来版本的 Elasticsearch 在二进制级别上兼容。换句话说，一旦您拥有一个可用的工件，当您将 Elasticsearch 升级到新的错误修复或次要版本时，就可以重复使用它。

文本分析插件可以实现分析插件 API 提供的四个工厂类。

  • AnalyzerFactory 用于创建 Lucene 分析器
  • CharFilterFactory 用于创建字符过滤器
  • TokenFilterFactory 用于创建 Lucene 词元过滤器
  • TokenizerFactory 用于创建 Lucene 词元生成器

实现稳定插件的关键是 @NamedComponent 注解。Elasticsearch 的许多组件都有名称，这些名称用于配置中。例如，关键字分析器在配置中通过名称 "keyword" 引用。一旦您的自定义插件安装到集群中，您命名的组件也可以通过名称在这些配置中引用。

您还可以将文本分析插件创建为 经典插件。但是，经典插件绑定到特定版本的 Elasticsearch。升级 Elasticsearch 时，您需要重新编译它们。由于经典插件是针对可能更改的内部 API 构建的，因此升级到新版本可能需要更改代码。

稳定插件文件结构

稳定插件是 ZIP 文件，由 JAR 文件和两个元数据文件组成

  • stable-plugin-descriptor.properties - 描述插件的 Java 属性文件。请参阅 稳定插件的插件描述符文件。
  • named_components.json - 一个 JSON 文件，将接口映射到组件名称和实现类的键值对。

请注意，只有插件根目录下的 JAR 文件才会添加到插件的类路径中。如果您需要其他资源，请将它们打包到资源 JAR 中。

开发流程

Elastic 提供了一个 Gradle 插件 elasticsearch.stable-esplugin，它可以更轻松地开发和打包稳定插件。本节中的步骤假设您使用此插件。但是，您不需要 Gradle 来创建插件。

Elasticsearch Github 仓库包含 一个示例分析插件。示例 build.gradle 构建脚本为开发您自己的插件提供了一个良好的起点。

前提条件

插件用 Java 编写，因此您需要安装 Java 开发工具包 (JDK)。如果您想使用 Gradle，请安装 Gradle。

分步指南

  1. 为您的项目创建一个目录。

  2. 将示例 build.gradle 构建脚本复制到您的项目目录。请注意，此构建脚本使用 elasticsearch.stable-esplugin gradle 插件来构建您的插件。

  3. 编辑 build.gradle 构建脚本

    • 在文件顶部添加 pluginApiVersion 和匹配的 luceneVersion 变量的定义。您可以在 Elasticsearch Github 仓库 中的 build-tools-internal/version.properties 文件中找到这些版本。

    • 编辑构建脚本的 esplugin 部分中的 name 和 description。这将创建插件描述符文件。如果您未使用 elasticsearch.stable-esplugin gradle 插件，请参阅 稳定插件的插件描述符文件 手动创建该文件。

    • 添加模块信息。

    • 确保您已声明以下编译时依赖项。这些依赖项仅在编译时有效，因为 Elasticsearch 将在运行时提供这些库。

      • org.elasticsearch.plugin:elasticsearch-plugin-api
      • org.elasticsearch.plugin:elasticsearch-plugin-analysis-api
      • org.apache.lucene:lucene-analysis-common

    • 对于单元测试，请确保这些依赖项也已作为 testImplementation 依赖项添加到 build.gradle 脚本中。

  4. 实现分析插件 API 中的一个接口，并使用 NamedComponent 进行注解。有关示例，请参阅 示例文本分析插件。

  5. 您现在应该能够通过运行以下命令来组装插件 ZIP 文件：

    gradle bundlePlugin

    生成的插件 ZIP 文件将写入到 build/distributions 目录。

YAML REST 测试

Gradle elasticsearch.yaml-rest-test 插件可以使用 Elasticsearch yamlRestTest 框架测试您的插件。这些测试使用 YAML 格式的领域语言，针对已安装插件的内部 Elasticsearch 集群发出 REST 请求，并检查这些请求的结果。YAML REST 测试目录的结构如下：

  • 一个测试套件类，在 src/yamlRestTest/java 下定义。此类应继承 ESClientYamlSuiteTestCase。
  • YAML 测试本身应在 src/yamlRestTest/resources/test/ 下定义。
© . All rights reserved.