« 创建 Elasticsearch 插件 稳定插件的插件描述符文件 »
Elastic 文档 ›Elasticsearch 插件和集成 [8.16] ›创建 Elasticsearch 插件

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

编辑

使用稳定插件 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 升级到新的 bug 修复版本或次要版本时重复使用它。

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

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

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

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

稳定插件文件结构

编辑

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

  • 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/ 下。
« 创建 Elasticsearch 插件 稳定插件的插件描述符文件 »