7. API Conventions(API 规范)

原文链接:API Conventions

版本:6.0.0

译者:felayman

API Conventions(API 规范)

Elasticsearch REST API 通过 HTTP 协议使用 JSON 格式来暴露其 API.

除非另有说明，本章中列出的约定可以在整个 REST API 中应用。

• 多索引
• 索引名称支持日期格式的数学运算
• 常规选项
• 基于 URL 的访问控制

多索引

大多数引用 index 参数的 API 支持跨多个索引执行，使用简单的 test1,test2,test3 符号（或_all 所有索引）。它还支持通配符，例如：test*或*test 或 te*t 或*test*，以及“排除”（-）的能力，例如：test*,-test3。

所有多索引 API 都支持在 url 中使用以下查询字符串参数：

ignore_unavailable

控制是否忽略任何指定的索引不可用，这包括不存在的索引或关闭的索引。无论是 true 或 false 都可以指定。

allow_no_indices

控制如果通配符表达式结果不成为具体的索引时是否失败。无论是 true 或 false 可以指定。例如，如果通配符表达式 foo*被指定，并且没有索引可用，foo 那么根据这个设置，请求将失败。此设置也适用时_all，*或没有索引已经指定。这个设置也适用于别名，以防别名指向一个关闭的索引。

expand_wildcards

控制扩展为何种类型的具体索引通配符索引表达式。如果 open 被指定，那么通配符表达式被扩展为仅打开索引，如果 closed 被指定，则通配符表达式仅扩展到闭合索引。也 open,closed 可以指定这两个值（open,closed）来扩展到所有的索引。

如果 none 被指定，那么通配符扩展将被禁用，如果 all 被指定，通配符表达式将扩展到所有的索引（这相当于指定 open,closed）。

上述参数的默认设置取决于正在使用的 api。

单个索引 API（如 Document API 和单索引 alias API）不支持多个索引。

索引名称支持日期格式的数学运算

日期数学索引名称解析使您能够搜索一系列时间序列索引，而不是搜索所有时间序列索引，并过滤结果或保留别名。限制搜索索引的数量会减少集群的负载，并提高执行性能。例如，如果要在日常日志中搜索错误，则可以使用日期数学名称模板将搜索限制在过去两天。

几乎所有具有 index 参数的 API 都支持 index 参数值中的数学运算。

日期数学索引名称采用以下形式：

<static_name {date_math_expr {DATE_FORMAT |的time_zone}}>

说明:

您必须将日期数学索引名称表达式括在尖括号内，并且所有特殊字符都应该是 URI 编码的。例如：

# GET /<logstash-{now/d}>/_search
GET /%3Clogstash-%7Bnow%2Fd%7D%3E/_search
{
  "query" : {
    "match": {
      "test": "data"
    }
  }
}

日期数学字符的百分比编码,用于日期舍入的特殊字符必须如下进行 URI 编码：

| %3E
/ | %2F
{ | %7B
} | %7D
| | %7C

• | %2B
  : | %3A
  , | %2C

以下示例显示了不同形式的日期数学索引名称以及在当前时间为 2024 年 3 月 22 日中午 utc 时解析的最终索引名称。

要使用字符{和}索引名称模板的静态部分，请使用反斜杠\进行转义，例如：

• <elastic\{ON\}-{now/M}> 解决 elastic{ON}-2024.03.01

以下示例显示了一个搜索请求，它在过去三天中搜索 Logstash 索引，假设索引使用默认的 Logstash 索引名称格式 logstash-YYYY.MM.dd。

# GET /<logstash-{now/d-2d}>,<logstash-{now/d-1d}>,<logstash-{now/d}>/_search
GET /%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E/_search
{
  "query" : {
    "match": {
      "test": "data"
    }
  }
}

常规选项

以下选项可以应用于所有 REST API。

格式化相应

追加?pretty=true 任何请求时，返回的 JSON 格式都会非常好（仅用于调试！）。另一个选择是设置?format=yaml 哪一个会导致以（有时）更可读的 yaml 格式返回结果。

人类可读式输出

统计数据以适合人类（例如"exists_time": "1h"或"size": "1kb"）和计算机（例如"exists_time_in_millis": 3600000 或"size_in_bytes": 1024）的格式返回。可以通过添加?human=false 查询字符串来关闭可读取的值。当统计结果被监测工具消耗时，这是有意义的，而不是用于人类消耗。human 标志的默认值是 false。

日期数学

它接受一个格式化的日期值大多数参数—比如 gt 和 lt 在范围查询 range 的查询，或 from 与 to 在 daterange aggregations -了解日期数学计算。

表达式以锚点日期开始，可以是，也可以是以 now 日期结束的日期字符串 ||。这个锚定日期可以选择跟随一个或多个数学表达式：

• +1h - 加一小时
• -1d - 减去一天
• /d - 向下舍入为最近的一天

支持的时间单位与持续时间单位支持的时间单位不同。支持的单位是：

假设 now 是 2001-01-01 12:00:00，一些例子是：

now+1h

now 以毫秒格式加一个小时。解析后为：2001-01-01 13:00:00

now-1h
now 以毫秒格式加一个小时。解析后为：2001-01-01 11:00:00

now-1h/d
now 以毫秒为单位舍入到 UTC 00:00。解析后为：2001-01-01 00:00:00`

2001-01-01||+1M/d

now 以毫秒格式加一个月。解析后为：2001-02-01 00:00:00

响应过滤

所有 REST API 都接受一个 filter_path 参数，可以用来减少 Elasticsearch 返回的响应。该参数采用逗号分隔的以点表示法表示的过滤器列表：

GET /_search?q=elasticsearch&filter_path=took，hits.hits._id，hits.hits._score

响应

{ 
  “took”：3，
  “hits”：{ 
    “hits”：[ 
      { 
        “_id”：
        “0”，“_score”：1.6375021 
      } 
    ] 
  } 
}

它还支持*通配符来匹配任何字段或字段名称的一部分：

GET /_cluster/state?filter_path=metadata.indices.*.stat*

响应

{ 
  “metadata”：{ 
    “indices”：{ 
      “twitter”：{“state”：“open”} 
    } 
  } 
}

而**通配符可以用来包含字段而不知道字段的确切路径。例如，我们可以用这个请求返回每个段的 Lucene 版本信息：

GET /_cluster/state?filter_path=routing_table.indices.**.state

响应

{
  "routing_table": {
    "indices": {
      "twitter": {
        "shards": {
          "0": [{"state": "STARTED"}, {"state": "UNASSIGNED"}],
          "1": [{"state": "STARTED"}, {"state": "UNASSIGNED"}],
          "2": [{"state": "STARTED"}, {"state": "UNASSIGNED"}],
          "3": [{"state": "STARTED"}, {"state": "UNASSIGNED"}],
          "4": [{"state": "STARTED"}, {"state": "UNASSIGNED"}]
        }
      }
    }
  }
}

也可以通过用 char 前缀过滤器来排除一个或多个字段-：

GET / _count？filter_path = -_ shards

响应

{ 
  “count”：5 
}

而对于更多的控制，包容性和排他性的过滤器可以组合在同一个表达式中。在这种情况下，首先应用排他性过滤器，并使用包含性过滤器再次过滤结果：

GET /_cluster/state?filter_path=metadata.indices.*.state,-metadata.indices.logstash-*

响应

{ 
  “metadata”：{ 
    “indices”：{ 
      “index-1”：{“state”：“open”}，
      “index-2”：{“state”：“open”}，
      “index-3” “state”：“open”} 
    } 
  } 
}

请注意，Elasticsearch 有时直接返回字段的原始值，如_source 字段。如果你想过滤_source 字段，你应该考虑把已经存在的_source 参数（参见 Get API 获取更多细节）和 filter_path 参数结合起来：

POST / library / book？refresh 
{“title”：“Book＃1”，“rating”：200.1} 
POST / library / book？refresh 
{“title”：“Book＃2”，“rating”：1.7} 
POST / library / book？refresh 
{“title”：“Book＃3”，“rating”：0.1} 
GET /_search?filter_path=hits.hits._source&_source=title&sort=rating:desc

{ 
  “hits”：{ 
    “hits”：{ 
      “ _ source”：{“title”：“Book＃1”} 
    }，{ 
      “ _ source”：{“title”：“Book＃2”} 
    }，{ 
      “ _ source “：{”title“：”Book＃3“} 
    }] 
  } 
}

平面设置

该 flat_settings 标志会影响设置列表的呈现。当 flat_settings 标志被 true 设置返回在一个平面格式：

GET twitter/_settings?flat_settings=true

将返回

{
  "twitter" : {
    "settings": {
      "index.number_of_replicas": "1",
      "index.number_of_shards": "1",
      "index.creation_date": "1474389951325",
      "index.uuid": "n6gzFZTgS664GUfx0Xrpjw",
      "index.version.created": ...,
      "index.provided_name" : "twitter"
    }
  }
}

当 flat_settings 标志是 false 设置返回在一个更人类可读的结构化格式：

GET twitter/_settings?flat_settings=false

返回

{
  "twitter" : {
    "settings" : {
      "index" : {
        "number_of_replicas": "1",
        "number_of_shards": "1",
        "creation_date": "1474389951325",
        "uuid": "n6gzFZTgS664GUfx0Xrpjw",
        "version": {
          "created": ...
        },
        "provided_name" : "twitter"
      }
    }
  }
}

默认情况下 flat_settings 设置为 false。

参数

Rest 参数（使用 HTTP 时，映射到 HTTP URL 参数）遵循使用下划线框的约定。

布尔值

所有 REST API 参数（请求参数和 JSON 主体）都支持提供布尔值“false”作为值 false，布尔值“true”作为值 true。所有其他值将引发错误。

数值

所有 REST API 都支持提供编号参数，string 以支持本机 JSON 数字类型。

时间单位

无论何时需要指定持续时间，例如对于 timeout 参数，持续时间必须指定该单位，如 2d 代表 2 天。支持的单位是：

字节大小单位

无论何时需要指定数据的字节大小，例如设置缓冲区大小参数时，该值必须指定单位，例如 10kb10 千字节。请注意，这些单位使用 1024 的权力，所以 1kb 意味着 1024 字节。支持的单位是：

单位数量

单位数量意味着它们没有像“字节”或“赫兹”或“米”或“长吨”这样的“单位”。如果其中一个数量很大，我们会打印出来，如 1000 万 1000 万或 7 万 7000。我们仍然打印 87，但我们的意思是 87。这些是受支持的乘数：

距离单位

在需要指定距离的地方，例如 distance“ 地理距离查询”中的参数），如果没有指定默认单位，则为仪表。其他单位可以指定距离，例如"1km"或 "2mi"（2 英里）。

模糊性

一些查询和 API 支持使用参数进行不精确模糊匹配的 fuzziness 参数。

当查询 text 或 keyword 字段时，fuzziness 被解释为 Levenshtein 编辑距离 - 一个字符的数量改变，需要对一个字符串进行修改，使其与另一个字符串相同。

该 fuzziness 参数可以被指定为：

• 0，1，2

最大允许的 Levenshtein 编辑距离（或编辑数量）

• AUTO
  根据术语的长度生成编辑距离。对于长度：

  • 0..2

    必须完全匹配

  • 3..5

    允许一个编辑距离

  • 5

    允许两个编辑距离

AUTO 应该是一般的首选值 fuzziness。

启用堆栈轨迹

默认情况下，当请求返回错误时，Elasticsearch 不包括错误的堆栈跟踪。您可以通过设置 error_traceurl 参数来启用该行为 true。例如，默认情况下 size 向_searchAPI 发送无效参数时：

POST /twitter/_search?size=surprise_me

响应可能如下:

{
  "error" : {
    "root_cause" : [
      {
        "type" : "illegal_argument_exception",
        "reason" : "Failed to parse int parameter [size] with value [surprise_me]"
      }
    ],
    "type" : "illegal_argument_exception",
    "reason" : "Failed to parse int parameter [size] with value [surprise_me]",
    "caused_by" : {
      "type" : "number_format_exception",
      "reason" : "For input string: \"surprise_me\""
    }
  },
  "status" : 400
}

但是如果你设置 error_trace=true:

POST /twitter/_search?size=surprise_me&error_trace=true

响应可能如下:

{
  "error": {
    "root_cause": [
      {
        "type": "illegal_argument_exception",
        "reason": "Failed to parse int parameter [size] with value [surprise_me]",
        "stack_trace": "Failed to parse int parameter [size] with value [surprise_me]]; nested: IllegalArgumentException..."
      }
    ],
    "type": "illegal_argument_exception",
    "reason": "Failed to parse int parameter [size] with value [surprise_me]",
    "stack_trace": "java.lang.IllegalArgumentException: Failed to parse int parameter [size] with value [surprise_me]\n    at org.elasticsearch.rest.RestRequest.paramAsInt(RestRequest.java:175)...",
    "caused_by": {
      "type": "number_format_exception",
      "reason": "For input string: \"surprise_me\"",
      "stack_trace": "java.lang.NumberFormatException: For input string: \"surprise_me\"\n    at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65)..."
    }
  },
  "status": 400
}

查询字符串中的请求正文

对于不接受非 POST 请求的请求主体的库，您可以将请求主体作为 source 查询字符串参数进行传递。使用此方法时，source_content_type 还应该使用指示源格式的媒体类型值传递该参数，例如 application/json。

必要的 Content-Type

在请求体中发送的内容的类型必须使用 Content-Type 标题来指定。此标头的值必须映射到 API 支持的其中一种支持的格式。大多数 API 支持 JSON，YAML，CBOR 和 SMILE。批量和多搜索 API 支持 NDJSON，JSON 和 SMILE; 其他类型将导致错误响应。

此外，使用 source 查询字符串参数时，必须使用 source_content_type 查询字符串参数指定内容类型。

基于 URL 的访问控制

许多用户使用基于 URL 访问控制的代理来保护对 Elasticsearch 索引的访问。对于 multi-search、multi-get 以及 bulk 请求,用户可以选择在 URL 中指定一个索引，也可以在请求主体中的每个请求中指定一个索引。这可以使基于 URL 的访问控制具有挑战性。

为防止用户覆盖 URL 中指定的索引，请将此设置添加到 elasticsearch.yml 文件中：

rest.action.multi.allow_explicit_index：false

默认值是 true，但是当设置 false 为时，Elasticsearch 将拒绝在请求正文中指定具有显式索引的请求。