Elasticsearch7.1中文文档-第四章-API约定

墨蓝 2022-01-08 01:31 267阅读 0赞

Elasticsearch REST APIs是用HTTP暴露的，并且是基于JSON的。

除非另有说明，否则本章中的约定都可以使用REST API来使用。

*  多索引
 *  索引名称中支持日期数学
 *  公用选项
 *  基于URL的访问控制

### 多索引 ###

大多数引用`index`参数的api支持跨多个索引执行，使用简单的`test1，test2，test3`表示法（或`_all`表示所有索引）。

所有多索引API都支持下面的url查询字符串参数：

<table> 
 <thead> 
  <tr> 
   <th><code>ignore_unavailable</code></th> 
   <th>如果指定索引是不可用的，控制是否忽略该索引。包括b不存在的索引和已关闭(closed)的索引，可以指定ture或者false</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>allow_no_indices</code></td> 
   <td>通配符索引表达式没有具体的索引时，控制结果是否失败。可以指定true或false。例如，如果指定通配符表达式<code>foo*</code>，并且没有以foo开头的索引可用，请求将失败。当<code>_all</code>、<code>*</code>或没有指定索引时，此设置也适用。此设置也适用于别名，以防别名指向已关闭（closed）索引。</td> 
  </tr> 
  <tr> 
   <td><code>expand_wildcards</code></td> 
   <td>控制通配符索引表达式可以扩展为何种具体索引。如果指定了<code>open</code>，则通配符表达式将扩展为仅打开索引。如果指定了<code>closed</code>，则通配符表达式仅扩展到封闭索引。还可以指定这两个值(<code>open</code>和<code>closed</code>)扩展到所有索引。</td> 
  </tr> 
 </tbody> 
</table>

上述参数的默认设置取决于所使用的API。

> 与多索引API相对的是单索引API，例如DocumentAPI和`alias`API就不支持多索引。

### 索引名称中支持日期数学 ###

日期数学索引名称解析可以让你搜索一段time-series区间的索引，而不是搜索所有time-series索引并过滤结果或维护别名。限制搜索索引的数量可以减少集群上的负载并提高执行性能。例如，如果在日常日志中搜索错误，可以使用date math name模板将搜索限制在过去两天。

几乎所有具有`index`参数的api都在`index`参数值中支持日期数学。

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

<static_name{ date_math_expr{ date_format|time_zone}}>

<table> 
 <thead> 
  <tr> 
   <th>static_name是名称的静态文本部分</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>date_math_expr</code>是动态日期表达式，用来动态的计算</td> 
  </tr> 
  <tr> 
   <td><code>date_format</code>日期的展现格式，是可选的，默认为<code>yyyy.MM.dd</code>。格式应该与<code>Java-time</code>兼容</td> 
  </tr> 
  <tr> 
   <td><code>time_zone</code>可选的时区，默认为<code>utc</code></td> 
  </tr> 
 </tbody> 
</table>

注意在date\_format中使用小写字母vs大写字母。例如:mm表示每小时的分钟，而mm表示一年的月份。同样，hh表示1-12小时范围内的小时与AM/PM相结合，而hh表示0-23 24小时范围内的小时。

> 注意`date_format`中小写和大写字母的使用。 例如：mm表示分钟，而MM表示一年中的月份。 类似地，hh表示1-12范围内的小时与AM / PM的组合，而HH表示0-23小时范围内的小时。

日期数学表达式与区域时间无关。 因此，除了公历之外，不可能使用任何其他日历。

必须将date math索引名称表达式括在大括号内，并且所有特殊字符都应该是URI编码的。例如:

# GET /<logstash-{now/d}>/_search
    curl -X GET "localhost:9200/%3Clogstash-%7Bnow%2Fd%7D%3E/_search" -H 'Content-Type: application/json' -d' { "query" : { "match": { "test": "data" } } } '

> **date math 字符对应的编码**
> 
> 日期的括号，必须使用URI编码，可参照下表：
> 
> <table> 
>  <thead> 
>   <tr> 
>    <th><code>&lt;</code></th> 
>    <th><code>%3C</code></th> 
>   </tr> 
>  </thead> 
>  <tbody> 
>   <tr> 
>    <td><code>&gt;</code></td> 
>    <td><code>%3E</code></td> 
>   </tr> 
>   <tr> 
>    <td><code>/</code></td> 
>    <td><code>%2F</code></td> 
>   </tr> 
>   <tr> 
>    <td><code>{ </code></td> 
>    <td><code>%7B</code></td> 
>   </tr> 
>   <tr> 
>    <td><code>}</code></td> 
>    <td><code>%7D</code></td> 
>   </tr> 
>   <tr> 
>    <td><code>|</code></td> 
>    <td><code>%7C</code></td> 
>   </tr> 
>   <tr> 
>    <td><code>+</code></td> 
>    <td><code>%2B</code></td> 
>   </tr> 
>   <tr> 
>    <td><code>:</code></td> 
>    <td><code>%3A</code></td> 
>   </tr> 
>   <tr> 
>    <td><code>,</code></td> 
>    <td><code>%2C</code></td> 
>   </tr> 
>  </tbody> 
> </table>

下面的示例显示了不同形式的日期数学索引名，它们根据当前时间解析的最终索引名是22nd March 2024 noon utc。

<table> 
 <thead> 
  <tr> 
   <th align="left">Expression</th> 
   <th align="left">Resolves to</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><code>&lt;logstash-{now/d}&gt;</code></td> 
   <td align="left"><code>logstash-2024.03.22</code></td> 
  </tr> 
  <tr> 
   <td align="left"><code>&lt;logstash-{now/M}&gt;</code></td> 
   <td align="left"><code>logstash-2024.03.01</code></td> 
  </tr> 
  <tr> 
   <td align="left"><code>&lt;logstash-{now/M{yyyy.MM}}&gt;</code></td> 
   <td align="left"><code>logstash-2024.03</code></td> 
  </tr> 
  <tr> 
   <td align="left"><code>&lt;logstash-{now/M-1M{yyyy.MM}}&gt;</code></td> 
   <td align="left"><code>logstash-2024.02</code></td> 
  </tr> 
  <tr> 
   <td align="left"><code>&lt;logstash-{now/d{yyyy.MM.dd|+12:00}}&gt;</code></td> 
   <td align="left"><code>logstash-2024.03.23</code></td> 
  </tr> 
 </tbody> 
</table>

要在索引名称模板的静态部分中使用字符`{`和`}`，请使用反斜杠\\来转义它们，例如：

*  `<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
    curl -X GET "localhost:9200/%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E/_search" -H 'Content-Type: application/json' -d' { "query" : { "match": { "test": "data" } } } '

### 公用选项 ###

下面所有的选项可以用在所有的API上。

#### 美化的结果 ####

当对请求添加`pretty = true`时，返回的JSON将被格式化（仅用于调试！）。 另一种选择是设置`format = yaml`，这将导致以可读的yaml格式返回结果。

#### 可读的输出 ####

统计以可读的格式（例如`“exists_time”：“1h”`或`“size”：“1kb”`）和计算机（例如`“exists_time_in_millis”：3600000`或`“size_in_bytes”：1024`）返回。 可以通过向查询字符串添加`human = false`来关闭可读取的格式。 当统计结果被监视工具使用而不是供人使用时。默认值为false。

#### 日期数学（Date Math） ####

大多数参数接受一个格式化的日期值，例如在`range`查询的`gt`和`lt`，或者`daterange`聚合中的`from`和`to`

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

*  `+1h`: 加一个小时
 *  `-1d`: 减少一个小时
 *  `/d`: 舍入到最近的一天

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

假设`now` 是 `2001-01-01 12:00:00`, 例如：

<table> 
 <thead> 
  <tr> 
   <th><code>now+1h</code></th> 
   <th><code>now</code>以毫秒为单位上加一小时. 结果是: <code>2001-01-01 13:00:00</code></th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>now-1h</code></td> 
   <td><code>now</code> 以毫秒为单位减去一小时. 结果是: <code>2001-01-01 11:00:00</code></td> 
  </tr> 
  <tr> 
   <td><code>now-1h/d</code></td> 
   <td><code>now</code> 以毫秒为单位减去1小时, 四舍五入到UTC 00:00.结果为: <code>2001-01-01 00:00:00</code></td> 
  </tr> 
  <tr> 
   <td><code>2001.02.01\|\|+1M/d</code></td> 
   <td><code>2001-02-01</code> 以毫秒为单位加一个月. 结果为: <code>2001-03-01 00:00:00</code></td> 
  </tr> 
 </tbody> 
</table>

#### 响应过滤 ####

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

curl -X GET "localhost:9200/_search?q=elasticsearch&filter_path=took,hits.hits._id,hits.hits._score"

响应结果：

{ 
      "took" : 3,
      "hits" : { 
        "hits" : [
          { 
            "_id" : "0",
            "_score" : 1.6375021
          }
        ]
      }
    }

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

curl -X GET "localhost:9200/_cluster/state?filter_path=metadata.indices.*.stat*"

响应结果：

{ 
      "metadata" : { 
        "indices" : { 
          "twitter": { "state": "open"}
        }
      }
    }

并且\*\*通配符可用于包括字段而不知道字段的确切路径。 例如，我们可以使用此请求返回每个片的Lucene版本：

curl -X GET "localhost:9200/_cluster/state?filter_path=routing_table.indices.**.state"

响应结果：

{ 
      "routing_table": { 
        "indices": { 
          "twitter": { 
            "shards": { 
              "0": [{ "state": "STARTED"}, { "state": "UNASSIGNED"}]
            }
          }
        }
      }
    }

也可以通过在过滤器前面添加`-`来排除一个或多个字段

curl -X GET "localhost:9200/_count?filter_path=-_shards"

响应结果：

{ 
      "count" : 5
    }

并且为了进行更多控制，可以将包含和排他过滤器组合在同一表达式中。 在这种情况下，将首先应用独占过滤器，并使用包含过滤器再次过滤结果：

curl -X GET "localhost:9200/_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`参数与`filter_path`参数组合起来，如下所示:

curl -X POST "localhost:9200/library/book?refresh" -H 'Content-Type: application/json' -d' {"title": "Book #1", "rating": 200.1} '
    curl -X POST "localhost:9200/library/book?refresh" -H 'Content-Type: application/json' -d' {"title": "Book #2", "rating": 1.7} '
    curl -X POST "localhost:9200/library/book?refresh" -H 'Content-Type: application/json' -d' {"title": "Book #3", "rating": 0.1} '
    curl -X GET "localhost:9200/_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设置 ####

flat\_settings标志会影响设置列表的呈现。 当flat\_settings标志为true时，将以如下格式返回设置：

curl -X GET "localhost:9200/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`.

#### 参数 ####

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

#### 布尔值 ####

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

#### 数值 ####

所有REST api都支持以字符串的形式提供参数（这个字符串必须符合数字格式，例如不能是`12a`）。

#### 时间单位 ####

当需要指定持续时间时，例如对于超时参数，持续时间必须指定单位，比如`2d`，持续2天。支持单位包括:

<table> 
 <thead> 
  <tr> 
   <th><code>d</code></th> 
   <th>天</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>h</code></td> 
   <td>时</td> 
  </tr> 
  <tr> 
   <td><code>m</code></td> 
   <td>分</td> 
  </tr> 
  <tr> 
   <td><code>s</code></td> 
   <td>秒</td> 
  </tr> 
  <tr> 
   <td><code>ms</code></td> 
   <td>毫秒</td> 
  </tr> 
  <tr> 
   <td><code>micros</code></td> 
   <td>微秒</td> 
  </tr> 
  <tr> 
   <td><code>nanos</code></td> 
   <td>纳秒</td> 
  </tr> 
 </tbody> 
</table>

#### 字节大小单位 ####

每当需要指定数据的字节大小时，例如， 设置缓冲区大小参数时，该值必须指定单位，如10千字节为10千字节。 请注意，这些单位使用1024的幂，因此1kb表示1024字节。 支持的单位是：

<table> 
 <thead> 
  <tr> 
   <th><code>b</code></th> 
   <th>Bytes</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>kb</code></td> 
   <td>Kilobytes</td> 
  </tr> 
  <tr> 
   <td><code>mb</code></td> 
   <td>Megabytes</td> 
  </tr> 
  <tr> 
   <td><code>gb</code></td> 
   <td>Gigabytes</td> 
  </tr> 
  <tr> 
   <td><code>tb</code></td> 
   <td>Terabytes</td> 
  </tr> 
  <tr> 
   <td><code>pb</code></td> 
   <td>Petabytes</td> 
  </tr> 
 </tbody> 
</table>

#### 无单位数量 ####

无单位数量意味着它们没有“单位”，如“字节”、“赫兹”、“米”或“吨”。

如果这些量中有一个很大，我们将打印出来，比如10m(10,000,000)或7k(7000)。当我们的意思是87时，我们仍然会打印87。这些是支持的乘数:

#### 距离单位 ####

在需要指定距离的地方，比如地理距离查询中的距离参数，如果没有指定距离，默认单位是米。距离可以用其他单位表示，如“1km”或“2mi”(2英里)。

<table> 
 <thead> 
  <tr> 
   <th>Mile</th> 
   <th><code>mi</code> or <code>miles</code>（英里）</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>Yard</td> 
   <td><code>yd</code> or <code>yards</code>（码）</td> 
  </tr> 
  <tr> 
   <td>Feet</td> 
   <td><code>ft</code> or <code>feet</code>（尺）</td> 
  </tr> 
  <tr> 
   <td>Inch</td> 
   <td><code>in</code> or <code>inch</code>（英寸）</td> 
  </tr> 
  <tr> 
   <td>Kilometer</td> 
   <td><code>km</code> or <code>kilometers</code>（千米）</td> 
  </tr> 
  <tr> 
   <td>Meter</td> 
   <td><code>m</code> or <code>meters</code>（米）</td> 
  </tr> 
  <tr> 
   <td>Centimeter</td> 
   <td><code>cm</code> or <code>centimeters</code>（厘米）</td> 
  </tr> 
  <tr> 
   <td>Millimeter</td> 
   <td><code>mm</code> or <code>millimeters</code>（毫米）</td> 
  </tr> 
  <tr> 
   <td>Nautical mile</td> 
   <td><code>NM</code>, <code>nmi</code>, or <code>nauticalmiles</code>（纳米）</td> 
  </tr> 
 </tbody> 
</table>

#### 模糊 ####

一些查询和api支持使用模糊参数进行模糊匹配。

当查询`text`或`keyword`字段时，模糊性被解释为Levenshtein编辑距离——需要对一个字符串进行的字符数更改，以使其与另一个字符串相同。

`fuzziness`可以被指定为：

<table> 
 <thead> 
  <tr> 
   <th><code>0</code>, <code>1</code>, <code>2</code></th> 
   <th>最大允许的 Levenshtein Edit Distance (或者编辑数)</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>AUTO</code></td> 
   <td>根据术语的长度生成编辑距离。 可选择提供低距离和高距离参数<code>AUTO:[low],[high]</code>。 如果未指定，则默认值为3和6，相当于<code>AUTO:3,6</code>表示长度：<br><br>0…2<br>必须完全匹配<br>3…5<br>允许一次编辑<br>&gt;5<br>允许两次编辑<br>AUTO通常应该是模糊的首选值。</td> 
  </tr> 
 </tbody> 
</table>

#### 启用堆栈跟踪 ####

当请求时返回一个错误，默认情况下，Elasticsearch不会包含错误的堆栈跟踪。你可以通过设置`error_trace`url参数为`true`l来启用堆栈跟踪，例如：默认的，当你发送一个无效的`size`给`_search`API:

curl -X POST "localhost:9200/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`

curl -X POST "localhost:9200/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请求头指定请求体中发送的内容类型。Content-type的值必须是API支持格式之一。大多数api支持JSON、YAML、CBOR和SMILE。批量和多搜索api支持NDJSON、JSON和SMILE;其他类型将导致错误响应。

或者，当我们使用`source`查询字符串参数，必须使用`source_content_type`指定Content-Type。

### 基于URL的访问控制 ###

许多用户使用基于url的访问控制代理来确保对Elasticsearch索引的访问。对于多搜索、多获取和批量请求，用户可以选择在URL中指定索引，也可以选择在请求体中指定每个请求的索引。

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

rest.action.multi.allow_explicit_index: false

默认值为`true`，但是当你设置为`false`，Elasticsearch将拒绝在请求体中指定显式索引的请求。