当前位置: 首页 > 工具软件 > open-rest > 使用案例 >

ElasticSearch实战-RestAPI

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

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

一、使用约定

ContentType

包含request body的请求,必须使用使用Content-Type请求头,支持的类型包括JSONYAMLCBORSMILE。对于批量执行或者批量查询的接口,支持NDJSONJSONSMILE,使用其他的类型,会报错。

traceparent的请求头

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

GET or POST方法

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

二、请求选项

对返回结果进行格式化

?pretty=true&format=yamlpretty=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"

统计结果可读性控制

对于一些统计结果,ElasticSearch会做人工可读性的转换,例如:exist_time: 1hsize: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 unitssize unitstime 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 

执行示例

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%
 类似资料: