Elasticsearch系列：REST API

type

status

date

slug

summary

1、命令简介

1.1 Java API

Elasticsearch 为 Java 用户提供了两种内置客户端

节点客户端 ( node client )：以无数据节点 (none data node) 身份加入集群，换言之，它自己不存储任何数据，但是它知道数据在集群中的具体位置，并且能够直接转发请求到对应的节点上。

传输客户端 ( Transport client )：传输客户端更轻量，且能够发送请求到远程集群。它自己不加入集群，只是简单转发请求给集群中的节点。

两个 Java 客户端都通过 9300 端口和 Elasticsearch 传输协议 ( Elasticsearch Transport Protocol ) 与 Elasticsearch 进行交互。因为集群中的节点之间也通过 9300 端口进行通信，使用 Java API 可能会造成通讯混乱。现在已经不推荐使用 Java API 这种通讯方式，spring-boot 的高版本也已经移除 spring-data-elasticsearch 依赖。

1.2 RESTful API

Elasticsearch 的 RESTful API 使用 HTTP 作为传输协议，使用 JSON 作为数据交换格式所有的语言都可以使用 RESTful API，通过 9200 端口的与 Elasticsearch 进行通信，甚至可以使用 curl 命令来和 Elasticsearch 交互。因为是基于 HTTP 的 RESTFul API，所以向 Elasticsearch 发出的请求的组成部分与其它普通的 HTTP 请求是一样的。

VERB：HTTP 方法，可以使用下面方法：

POST：创建，可以不指定id，es自己生成不会发生碰撞的UUID
PUT：创建/更新，需要指定具体的id，如果id已经存在就会覆盖原来的内容，version会加1。
GET：查看
DELETE：删除

PROTOCOL：http 或者 https（如果你在 Elasticsearch 前面有一个 https 代理）

HOST：Elasticsearch 集群中任意节点的主机名，或者用 localhost 代表本地机器上的节点。

PORT：运行 Elasticsearch HTTP 服务的端口号，默认是 9200 。

PATH：第一部分通常是索引名称，除非它以开头。例如 /products/_search，其中 products 是索引，search 是动作。

QUERY_STRING：参数选项，常用的有：

?v：显示列名，例如 /_cat/master?v。
?help：显示当前命令的各列含义。例如 /_cat/master?help。
?bytes：数值列以指定单位显示, 转为以kb/mb/gb表示，默认为b。例如 /_cat/indices?bytes=b。
?h：显示指定列的信息，例如 _cat/indices?h=docs.count,store.size。
?s：用于排序，使用列出的字段作为排序键。例如 /_cat/nodes?v&h=cpu,master,name&s=name。
?pretty：美化输出成 json 格式，例如 /_cluster/health?pretty。

BODY：一个 JSON 格式的请求体 (如果请求需要的话)

例如，计算集群中文档的数量，我们可以用这个:

如果是在 Dev Tools 控制台，我们会使用下面的缩写形式。下面的命令也写成缩写形式。

2、常用命令

2.1 集群 API

通常使用 /_cluster 来查看集群信息

查看集群健康状态

查看集群健康状态，包括集群名称、节点数、数据节点数、分片等的一些统计信息。

查看集群状况

查看集群统计信息

查看集群统计信息，有助于基本故障排除

查看集群配置

查看索引健康状态

查看分片健康状态

2.2 节点 API

通常使用 /_nodes 来查看节点信息

查看所有节点的统计信息

查看所有节点的统计信息，包括堆使用情况等

查看所有节点的索引信息

查看某个节点的统计信息

查看某个节点的索引信息

2.3 CAT API

CAT API 仅适用于使用 Kibana 控制台或命令行供人类使用，输出以表格的形式的文本，而不是 JSON。可以通过下面命令列出所有可用的 API。

输出默认是没有表头的，可以在最后加上 ?v 参数输出表头。这都是模仿 Linix 工具设计的，因为它假设一旦你对输出熟悉了，你就再也不想看见表头了。

查看集群健康状态

查看集群节点状态

查看集群各个节点的当前状态, 包括节点的物理参数(包括os/jdk版本, uptime, 当前mem/disk/fd使用情况等), 请求访问情况(如search/index成功和失败的次数)等详细信息

查看所有索引

查看分片情况

查看分片情况，包括shard的分布, 当前状态(对于分配失败的shard会有失败原因), doc数量, 磁盘占用情况, shard的访问情况(如所有get请求的成功/失败次数以及对应耗时等)

查看master信息

查看lucence的段信息

查看lucence的段信息，包括segment名, 所属shard, 内存/磁盘占用大小, 是否刷盘, 是否merge为compound文件等. 可以查看指定index的segment信息()

查看索引别名

查看索引别名，包括alias对应的index，路由配置等

查看分配资源接口

查看文档数量

查看模板

2.4 索引 API

创建索引

有两种方式，第一种是提交数据自动创建索引。

如果你想禁止自动创建索引，你可以通过在 config/elasticsearch.yml 的每个节点下添加下面的配置：

第二种方式是手动创建索引，指定 mappings 和 settings。

查看索引

修改索引

删除索引

查看索引分片信息

索引别名

索引模板

2.5 文档

新增文档

新增可以使用 PUT 请求或者 POST 请求。

PUT请求，必须带 id。如果 id 不存在，则会新建一个文档。如果 id 存在，则会用当前数据更新原来的文档。

POST请求，可以带id，也可以不带 id。不带 id 就是新增操作，带 id 可以为新增或者更新操作。

更新文档

PUT/POST操作带id，直接更新整个文档，version号会一直增加。

如果想增加或者更新某些字段，可以使用 POST 操作的 _update 。_update 会对比元数据，有差异才会更新，然后增加 version 号，否则不进行任何操作。

更新携带 ?if_seq_no=0&if_primary_term=1，还可以实现乐观锁的功能。只有 seq_no 和 primary_term 和当前的文档相同才能更新成功，否则会返回 409 错误。在更新完后 seq_no 会往上叠加。

查看文档

返回数据

删除文档

检索文档

批量操作

语法格式

bulk API 以此按顺序执行所有的 action（动作）。如果一个单个的动作因任何原因而失败，它将继续处理它后面剩余的动作。当 bulk API 返回，它将提供每个动作的状态（与发送的顺序相同），所以可以检查是否一个指定的动作是不是失败了。例如批量插入id为5和6的两条数据：

还可以不指定索引，对整个 es 进行整体操作。例如下面一共进行了 delete、create、index和 update 四个操作。

可以导入官方示例数据进行测试 https://www.elastic.co/guide/cn/kibana/current/tutorial-load-dataset.html

文档操作的并发控制

如果我们同时修改一个文档，Elasticsearch 通过乐观锁确保文档的原子性。Elasticsearch的乐观锁是基于版本号实现的，前面的章节介绍文档 CRUD 的时候，提到文档的元数据中_seq_no、version，都代表当前文档的版本号，每次更新、删除文档的时候，版本号都会加1，ES就是借着这个版本号实现乐观锁。

Elasticsearch 7.x 的版本已经不再使用 version 字段作为乐观锁判断的依据，主要使用seq_no作为版本号，结合_primary_term字段实现乐观锁控制。

下面介绍如何使用Elasticsearch的乐观锁机制确保数据的原子性。

首先插入一个文档

然后我们查询下插入的文档，观察下版本号

然后增加请求参数 ?if_seq_no=6&if_primary_term=1，指定和文档相同的 seq_no 和 primary_term 更新数据

ES就会输出下面的错误提示：版本冲突（version conflict）。