Elasticsearch REST API 约定是一套规则和约定,它们指导开发者如何正确、高效地与Elasticsearch集群进行交互。以下是一些关键的API约定和实践:
1. 基于HTTP协议
Elasticsearch的API完全基于HTTP协议,支持GET、POST、PUT、DELETE等标准HTTP方法,用于执行对应的操作,如查询(GET)、创建(POST)、更新(PUT)和删除(DELETE)文档。
2. JSON作为数据格式
所有的请求体和响应体都采用JSON格式。这意味着你需要按照JSON的规则构造请求数据,并能够解析返回的JSON响应。
3. URL结构
Elasticsearch API URL通常由以下部分组成:
-
主机与端口:指明Elasticsearch集群的访问地址,如
http://localhost:9200
。 -
索引(Indices):API操作的目标索引或索引模式。可以指定单个索引(如
my_index
),多个索引(如index1,index2
或使用通配符logs-*
),或_all
表示所有索引。 -
类型(Types,7.x+版本已弃用):在Elasticsearch早期版本中,一个索引可以包含多个类型,但自7.x版本起,单索引单类型成为默认设置,类型的概念被逐步弃用。现在通常省略类型部分,或者在旧版本中指定文档类型(如
_doc
)。 -
API端点:表示要执行的操作,如
_search
用于搜索,_doc
或_create
用于文档操作,_bulk
用于批量处理等。 -
文档ID:对于文档操作,可以在URL末尾添加文档ID,如
/my_index/_doc/1
。
4. 查询参数
许多API支持通过URL查询参数传递额外的配置信息,如排序、分页、过滤条件等。查询参数以 ?
开始,各个参数之间用 &
分隔,如 ?q=title:example&size=10
.
5. 请求体
对于需要携带数据的HTTP方法(如POST、PUT),请求体包含具体的JSON对象,描述要执行的操作详情,如插入或更新的文档内容、搜索查询DSL等。
6. 错误处理
如果请求失败,Elasticsearch会返回带有HTTP状态码(如4xx或5xx)的响应,且响应体包含详细的错误信息,包括错误类型、原因、以及可能的堆栈跟踪。应用程序应检查并妥善处理这些错误。
7. 版本控制与乐观并发控制
Elasticsearch支持文档版本控制,允许实现乐观并发控制。在更新或删除文档时,可以通过在请求中包含 _version
参数和对应的 if_seq_no
、if_primary_term
参数来确保操作仅在文档未被他人修改的情况下执行。
8. 批量操作
使用 _bulk
API可以高效地批量执行多个索引、更新、删除等操作。批量请求体由多行组成,每行是一个操作指令(如 { "index": { "_index": "my_index", "_id": "1" } }
)跟随一个可选的文档JSON(换行分隔)。这种机制显著减少了网络开销和索引写入延迟。
9. 过滤条件与查询DSL
Elasticsearch使用JSON-based查询DSL(Domain Specific Language)来构建复杂的查询条件。查询DSL支持布尔逻辑、模糊匹配、范围查询、聚合等各种查询类型,并可通过 query
和 filter
上下文区分查询得分与纯粹的过滤条件。
10. 分页与排序
搜索请求支持 from
和 size
参数进行分页,以及 sort
参数指定排序字段和方向。还可以使用 track_total_hits
参数控制是否精确计算总命中数,以优化大规模结果集的分页性能。
11. Scroll API与深度分页
对于大量数据的全量或深度分页,使用 scroll
API可以保持搜索上下文,实现高效的逐页遍历。Scroll API适用于一次性获取大量数据的批处理任务,而非实时用户界面分页。
12. 索引管理
-
索引创建:使用
PUT /<index>
创建索引,请求体中可包含索引的设置(settings)和映射(mappings)。 -
映射管理:在创建索引时或之后单独使用
PUT /<index>/_mapping
更新映射,定义字段类型、分析器等。 -
索引模板:通过
PUT _template/<template_name>
创建索引模板,当符合模板匹配条件的新索引被创建时,自动应用预定义的设置和映射。 -
别名管理:使用
POST /_aliases
创建、更新或删除索引来关联或取消关联别名,别名提供了一种对索引进行逻辑命名和透明切换的机制。
13. 集群与节点状态查询
-
集群健康:
GET /_cluster/health
查询集群健康状况、节点数、分片状态等。 -
节点统计:
GET /_nodes/stats
获取节点级别的统计信息,如CPU、内存、磁盘使用情况等。 -
索引统计:
GET /<index>/_stats
查看特定索引的统计信息,如文档数量、存储大小、分片分布等。
遵循上述Elasticsearch API约定,开发者可以确保与Elasticsearch的交互既符合规范又高效。随着Elasticsearch版本的更新,API可能会有新增特性和调整,因此在实际使用时还需参考对应版本的官方文档以获取最新信息。