ElasticSearch实战-RestAPI

• 基于ElasticSearch版本8.5.0
• 本文描述的集群部署方式，只用以测试和学习使用，不能作为生产环境
• 本文描述的集群方式基于docker
• ElasticSearch文档
• 本篇文章中的接口执行示例，如无特殊说明，均是在Kibana的Dev Tools的Console中执行的。

ElasticSearch暴露了Rest风格的API，用以对ElasticSearch进行配置、控制功能、查询数据等，所有的API都是基于HTTP协议对外进行暴露的。

一、使用约定

ContentType

包含request body的请求，必须使用使用Content-Type请求头，支持的类型包括JSON、YAML、CBOR、SMILE。对于批量执行或者批量查询的接口，支持NDJSON、JSON、SMILE，使用其他的类型，会报错。

traceparent的请求头

支持traceparent的请求头，用以追踪接口的执行，请求的规范为official W3C trace context spec。包含该请求头，elastic search会在服务日志、慢查询日志中打印出trace信息。便于问题的定位。

GET or POST方法

ElasticSearch有很多GET方法支持request body(尤其是搜索接口)，但是很多HTTP client不支持GET方法包含请求体，因此这些方法都支持以POST方法进行请求。

二、请求选项

对返回结果进行格式化

?pretty=true&format=yaml 用pretty=true指定对相应结果进行格式化，format指定对结果格式化的格式。例如

# 不包含格式化信息
GET _cat/indices?v=true
health status index                           uuid                   pri rep docs.count docs.deleted store.size pri.store.size
green  open   get-together-group              pmDUpYvkRiy-T_4jV4xDwA   1   1          1            0     18.1kb            9kb
green  open   .monitoring-es-7-2022.11.11     i74ojFpDQ9COGpNSkY_Tdw   1   1      30006        74984     45.9mb         22.9mb

#包含格式化参数
GET _cat/indices?v=true&pretty=true&format=yaml
---
- health: "green"
  status: "open"
  index: "get-together-group"
  uuid: "pmDUpYvkRiy-T_4jV4xDwA"
  pri: "1"
  rep: "1"
  docs.count: "1"
  docs.deleted: "0"
  store.size: "18.1kb"
  pri.store.size: "9kb"
- health: "green"
  status: "open"
  index: ".monitoring-es-7-2022.11.11"
  uuid: "i74ojFpDQ9COGpNSkY_Tdw"
  pri: "1"
  rep: "1"
  docs.count: "30006"
  docs.deleted: "74984"
  store.size: "45.9mb"
  pri.store.size: "22.9mb"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

统计结果可读性控制

对于一些统计结果，ElasticSearch会做人工可读性的转换，例如：exist_time: 1h， size：1kb等。如果相应结果用以做监控或者需要对结果进行排序，可以使用?human=false的参数，避免ElasticSearch对结果进行可读性的转换。

控制返回的字段

filter_path控制返回结果中需要返回哪些字段，通过该参数，可以去掉响应结果中无用的参数，节省传输大小。例如GET /_search?q=kimchy&filter_path=took,hits.hits._id,hits.hits._score。各个筛选的字段间用逗号分割，支持*通配符。

三、CAT API

以适合在终端上进行展示的格式输出查询结果，CAT APIs包含了很多查询集群状态的接口，本小节挑选一些比较有用的进行介绍。

通用参数

v=true展示详细信息，输出结果中带上标题。
help 展示接口的帮助信息，主要是展示接口返回的标题的说明。
h=ip,port指定输出结果包含哪些列。
bytes=b time=s size=k指定返回结果的单位，支持的单位byte units、size units、time units。
s=order:desc 按照指定列进行排序，asc 升序，desc降序。

1. health接口

接口: /_cat/health
返回集群健康状态，返回包括如下字段

epoch                 | t,time                                   | seconds since 1970-01-01 00:00:00  
timestamp             | ts,hms,hhmmss                            | time in HH:MM:SS                   
cluster               | cl                                       | cluster name                       
status                | st                                       | health status                      
node.total            | nt,nodeTotal                             | total number of nodes              
node.data             | nd,nodeData                              | number of nodes that can store data
shards                | t,sh,shards.total,shardsTotal            | total number of shards             
pri                   | p,shards.primary,shardsPrimary           | number of primary shards           
relo                  | r,shards.relocating,shardsRelocating     | number of relocating nodes         
init                  | i,shards.initializing,shardsInitializing | number of initializing nodes       
unassign              | u,shards.unassigned,shardsUnassigned     | number of unassigned shards        
pending_tasks         | pt,pendingTasks                          | number of pending tasks            
max_task_wait_time    | mtwt,maxTaskWaitTime                     | wait time of longest task pending  
active_shards_percent | asp,activeShardsPercent                  | active number of shards in percent 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

执行示例

GET /_cat/health?v=true

epoch      timestamp cluster        status node.total node.data shards pri relo init unassign pending_tasks max_task_wait_time active_shards_percent
1668343664 12:47:44  docker-cluster green           3         3     52  26    0    0        0             0                  -                100.0%
1
2
3
4