Elasticsearch 的 RESTful API解析

Elasticsearch 使用 RESTful API 作为其主要的交互方式，允许用户通过标准的 HTTP 请求与 Elasticsearch 集群进行通信，进行索引管理、文档操作、搜索查询、集群监控等各种任务。

一、RESTful 原则

Elasticsearch 的 RESTful API 设计遵循 REST（Representational State Transfer）架构风格的主要原则：

1. 资源导向：所有的操作围绕着对资源（如索引、文档、映射、节点信息等）的访问和管理。每个资源都有一个唯一的 URI（Uniform Resource Identifier）。

2. HTTP 方法：使用标准的 HTTP 方法（如 GET、POST、PUT、DELETE 等）来表示对资源的不同操作意图：

   • GET：获取资源信息，无副作用。
   • POST：创建新资源或执行某个操作（如批量操作、脚本执行等）。
   • PUT：更新现有资源（完全替换）或创建资源（如果不存在）。
   • DELETE：删除指定资源。

3. 状态转移：通过请求和响应间的交互，客户端可以影响服务器端资源的状态。例如，通过 PUT 请求更新文档内容，改变了文档在 Elasticsearch 中的状态。

4. 统一接口：所有的资源都通过相同的接口风格进行访问，即通过 HTTP 协议加上资源的 URI，并使用标准的 HTTP 方法。

二、URI 结构

Elasticsearch 的 RESTful API URI 通常遵循以下结构：

http(s)://<server>:<port>/<index>(/<type>/)?<request_params>

• <server> 和 <port>：Elasticsearch 集群中的节点地址和端口号。
• <index>：要操作的索引名称，可以是单个索引名或使用通配符表示多个索引。
• <type>（已弃用）：在 Elasticsearch 7.x 版本之前，每个索引可以包含多个类型（type）。但在 7.x 版本之后，单个索引只允许一个类型 _doc，且在后续版本中彻底移除了类型概念。因此，现代的 Elasticsearch API 中通常不再包含 <type> 部分。
• <request_params>：可选的查询参数，以 ? 开始，以 & 分隔多个参数，如 ?pretty=true&size=10。

三、请求体与响应格式

• 请求体：对于 POST、PUT 等方法，请求体通常包含 JSON 格式的数据，如索引文档时的文档内容、更新文档时的更新指令、搜索查询时的查询 DSL 等。

• 响应格式：Elasticsearch 的响应也是 JSON 格式，通常包含以下部分：

  • status_code：HTTP 状态码，如 200 OK 表示成功，404 Not Found 表示资源未找到等。
  • headers：HTTP 响应头，如 Content-Type、Etag 等。
  • body：JSON 格式的响应主体，包含请求结果的具体数据，如索引操作的成功确认、查询结果列表、集群状态信息等。

四、常见操作示例

以下是一些使用 Elasticsearch RESTful API 进行常见操作的命令行示例：

1.索引操作

• 创建索引：

curl -X PUT "http://localhost:9200/my_index" -H 'Content-Type: application/json' -d'
{
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 0
  },
  "mappings": {
    "properties": {
      "title": { "type": "text" },
      "content": { "type": "text" },
      "date": { "type": "date" }
    }
  }
}'

2.文档操作

• 索引（创建或更新）文档：

curl -X PUT "http://localhost:9200/my_index/_doc/1" -H 'Content-Type: application/json' -d'
{
  "title": "My First Document",
  "content": "This is the content of my first document.",
  "date": "2024-04-18T10:30:00Z"
}'

• 获取文档：

curl -X GET "http://localhost:9200/my_index/_doc/1"

• 删除文档：

curl -X DELETE "http://localhost:9200/my_index/_doc/1"

3.搜索操作

• 执行搜索查询：

curl -X GET "http://localhost:9200/my_index/_search" -H 'Content-Type: application/json' -d'
{
  "query": {
    "match": {
      "title": "first document"
    }
  }
}'

4.其他操作

除了上述基本操作，Elasticsearch RESTful API 还支持更多高级功能，如：

• 批量操作：使用 _bulk 端点进行批量索引、更新、删除文档。
• 聚合查询：使用 _search 端点配合 aggs 参数进行数据统计、分桶分析等。
• 映射管理：使用 _mapping 端点查看、更新索引映射。
• 索引设置管理：使用 _settings 端点查看、更新索引设置。
• 集群健康检查：使用 _cluster/health 端点获取集群健康状态。
• 节点信息：使用 _nodes 端点查询集群节点详细信息。