=ElasticSearch REST API 全面指南：从基础到生产实践
一、ElasticSearch API 架构概述
ElasticSearch 提供了一套完整的 RESTful API 体系，基于 HTTP/HTTPS 协议，通过 9200 端口提供服务。API 设计遵循 REST 规范，支持 JSON 格式的请求和响应。
1. API 核心分类
| API 类型 | 功能描述 | 生产环境应用场景 |
|---|---|---|
| Cat API | 提供简洁的文本格式集群信息 | 快速监控和故障排查 |
| Cluster API | 管理集群范围的操作和设置 | 集群健康检查、配置管理 |
| Document API | 文档级别的 CRUD 操作 | 业务数据增删改查 |
| Search API | 执行搜索和聚合操作 | 业务查询、数据分析 |
| Index API | 索引生命周期管理 | 索引创建、配置和删除 |
| Nodes API | 节点级别信息和统计 | 性能监控、资源调配 |
二、Cat API 深度解析
1. 核心监控端点
# 集群健康状态（生产环境推荐格式）
GET /_cat/health?v&format=json&pretty
# 节点资源使用情况（包含关键指标）
GET /_cat/nodes?v&h=name,ip,heap.percent,ram.percent,cpu,load_1m,node.role
# 索引分片分布详情
GET /_cat/shards?v&h=index,shard,prirep,state,docs,store,node&s=state
2. 生产环境实用参数
| 参数 | 作用 | 示例 |
|---|---|---|
v |
显示列标题 | /_cat/nodes?v |
h |
指定返回字段 | &h=name,ip,heap.percent |
format |
设置响应格式(json/yaml等) | &format=json |
s |
按字段排序 | &s=heap:desc |
bytes |
数据大小显示格式 | &bytes=gb |
3. 关键监控指标说明
// 典型响应示例
[
{
"name": "node-1",
"ip": "192.168.1.101",
"heap.percent": "45",
"ram.percent": "78",
"cpu": "12",
"load_1m": "2.15",
"node.role": "dimr" // d:data, i:ingest, m:master, r:remote_cluster_client
}
]
三、Cluster API 生产实践
1. 集群健康诊断
# 深度健康检查（生产推荐）
GET /_cluster/health?level=indices&pretty
# 响应关键字段解析
{
"cluster_name": "prod-cluster",
"status": "green", # 红/黄/绿状态
"timed_out": false,
"number_of_nodes": 8,
"number_of_data_nodes": 6,
"active_primary_shards": 420,
"active_shards": 840,
"relocating_shards": 0, # 正在迁移的分片
"initializing_shards": 0, # 初始化中的分片
"unassigned_shards": 0, # 未分配分片
"delayed_unassigned_shards": 0,
"number_of_pending_tasks": 0,
"task_max_waiting_in_queue_millis": 0
}
2. 集群状态分析
# 获取详细集群状态（谨慎使用，数据量大）
GET /_cluster/state?filter_path=metadata.indices.*.settings,master_node,nodes
# 常用过滤路径
?filter_path=metadata.indices.*.stat*
?filter_path=routing_table.indices.*.shards.*.state
3. 生产环境关键操作
分片分配控制：
# 临时禁用分片分配（维护时使用）
PUT /_cluster/settings
{
"persistent": {
"cluster.routing.allocation.enable": "none"
}
}
# 排除故障节点
PUT /_cluster/settings
{
"transient": {
"cluster.routing.allocation.exclude._ip": "192.168.1.100"
}
}
四、Document API 最佳实践
1. 文档 CRUD 操作
# 创建/更新文档（自动生成ID）
POST /products/_doc
{
"name": "Server Rack",
"price": 899.99,
"stock": 42
}
# 指定ID创建
PUT /products/_doc/1001
{
"name": "Network Switch",
"price": 2499.99
}
# 条件更新文档
POST /products/_update/1001
{
"script": {
"source": "ctx._source.stock -= params.quantity",
"lang": "painless",
"params": {
"quantity": 2
}
}
}
2. 批量操作（Bulk API）
POST /_bulk
{ "index" : { "_index" : "products", "_id" : "1002" } }
{ "name": "SSD Drive", "price": 199.99 }
{ "create" : { "_index" : "products", "_id" : "1003" } }
{ "name": "Memory Module", "price": 129.99 }
{ "delete" : { "_index" : "products", "_id" : "1001" } }
性能提示：生产环境批量大小建议 5-15MB，根据网络延迟调整
五、Search API 高级应用
1. 复合查询示例
GET /products/_search
{
"query": {
"bool": {
"must": [
{ "match": { "name": "server" } }
],
"filter": [
{ "range": { "price": { "gte": 500, "lte": 1000 } } },
{ "term": { "in_stock": true } }
],
"should": [
{ "match": { "description": "rackmount" } }
],
"minimum_should_match": 1
}
},
"aggs": {
"price_stats": {
"stats": { "field": "price" }
},
"inventory_by_type": {
"terms": { "field": "category.keyword" }
}
},
"sort": [
{ "price": { "order": "desc" } }
],
"from": 0,
"size": 10
}
2. 搜索性能优化参数
| 参数 | 作用 |
|---|---|
preference |
控制分片执行查询的位置（如_local） |
request_cache |
启用查询缓存（适用于重复查询） |
batched_reduce_size |
控制分片结果分批处理大小 |
terminate_after |
指定每个分片收集的最大文档数 |
六、生产环境API安全实践
1. 基础安全措施
# 启用HTTPS
xpack.security.http.ssl.enabled: true
xpack.security.http.ssl.keystore.path: certs/elastic-http.p12
# 请求认证
curl -u username:password -XGET 'https://es-cluster:9200/_cluster/health'
2. 限流保护
# 设置搜索限流（集群级别）
PUT /_cluster/settings
{
"persistent": {
"search.max_buckets": 10000,
"indices.breaker.request.limit": "60%"
}
}
# 索引级别限流
PUT /products/_settings
{
"index.search.throttled": true
}
七、API性能监控
1. 慢日志配置
PUT /_settings
{
"index.search.slowlog.threshold.query.warn": "10s",
"index.search.slowlog.threshold.fetch.debug": "500ms"
}
2. 性能分析接口
# 查询性能分析
GET /products/_search?profile=true
{
"query": { ... }
}
# 聚合性能分析
GET /products/_search
{
"profile": true,
"aggs": { ... }
}
本指南基于 Elasticsearch 7.x 版本编写，适用于生产环境部署。实际使用时请根据集群版本和具体业务需求调整 API 参数。建议结合 Kibana 的 Dev Tools 进行 API 测试和验证。
