« 创建 Elasticsearch 插件 稳定插件的插件描述符文件 »
Elastic 文档 ›Elasticsearch 插件和集成 [8.14] ›创建 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 升级到新的错误修复版本或次要版本时，您可以重复使用它。

文本分析插件可以实现分析插件 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 插件 稳定插件的插件描述符文件 »