elasticsearch API约定(二)

前面我们介绍了一些REST API的基本约定，包括多个索引以及索引名称中的Date Math支持，本文我们来继续上文的话题，主要来看看公共参数和URL访问控制。

本文是Elasticsearch系列的第六篇，阅读前面的文章，有助于更好的理解本文

公共参数

下面这些选项可以应用于Elasticsearch中所有的REST API。

Pretty Results

美化响应的JSON格式，当添加 ?pretty=true到请求的后面时，响应的JSON将被格式化，这个选项我们在前面的案例中已经用过多次了。另一种方案是添加 ?format=yaml参数，在有的情况下，可以使请求以更可读的yaml格式响应。

例如如下请求：

curl -X GET "localhost:9200/log-2018.10.20/_search?format=yaml" -H 'Content-Type: application/json' -d'
{
  "query" : {
    "match_all": {}
  }
}
'

该请求执行响应结果如下：

Human readable output

这个是以人类可读的格式来返回数据，例如：

• ?human=true时，返回数据格式如下 {"exists_time":"1h"}或{"size":"1kb"}
• ?human=false时，返回数据格式如下 {"exists_time_in_millis":3600000}或{"size_in_bytes":1024}

该值默认为false。例如查看索引的setting信息，如果不设置human=true，默认返回结果如下：

如果设置了human=true，返回结果如下：

可以看到，此时多了一个人类可读的时间字符串。

Date Math

Date Math和前文说的基本一致，这里再来看看一些细节： 日期表达式以一个锚定日期开始，锚定日期可以是当前日期，也可以是一个以 ||结尾的给定日期字符串，锚定日期的后面可以再跟上一个表达式，如：

在锚定日期的基础上加上1小时

这里支持的时间单位，不同于durations时间支持的时间单位，这里支持的时间单位有：

年

现在假设当前日期是 2001-01-0112:00:00,下面是一些简单例子:

2001-01-01 13:00:00

Response Filtering

这是对响应进行过滤，用户可以通过过滤查看自己关注的信息，例如如下请求：

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

请求结果如下：

这里还支持使用 *通配符去匹配filed名称或者field名称中的部分字符，如下：

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

还可以使用 **指定包括字段，但是不知道字段确切路径的请求，如下：

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

执行结果如下：

也可以在字段前加上 -前缀来排除一个或者多个字段，例如如下请求：

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

执行结果如下：

为了实现更多控制，inclusive和exclusive可以出现在同一个表达式中，此时首先使用exclusive filters，然后再对过滤的结果使用inclusive filters，例如如下案例：

curl -X GET "localhost:9200/_cluster/state?pretty&filter_path=metadata.indices.*.state,-metadata.indices.log-*"

执行结果如下：

对于 _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?pretty&filter_path=hits.hits._source&_source=title&sort=rating:desc"

执行结果如下：

Flat Settings

这个还是用来设置响应格式，默认值为false，响应格式如下：

上图展示了flat_settings为true和false时的两种不同情况。

Parameters

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

Boolean Values

在请求参数或者请求体JSON中，都支持使用false来描述boolean值false，使用true来描述boolean值true。

Number Values

所有的REST API都支持在原生的JSON number基础之上，将numbered parameters作为字符串来提供。

Time units

每当需要指定durations时间时，时间必须指定单位，单位有如下几种：

days

Byte size units

当需要指定数据的字节单位时，也需要指定单位，可用单位如下：

Bytes

Unit-less quantities

无单位数量，意味者这些数量没有单位，但是如果这些数字比较大，直接打印出来可能不利于阅读，此时可以用10M代替10,000,000，用7k代替7000，用87代替87，支持的乘数有：

Single

Distance Units

在需要指定距离单位的时候，如果没有指定，默认的距离单位是meter（米），也可以手动指定距离单位，支持的距离单位如下：

Mile

Fuzziness

fuzziness用来实现模糊查询，这里的模糊查询被定义为Levenshtein Edit Distance，指将一个字符串变为另外一个字符串所需要操作的步数，默认值为AUTO，AUTO策略如下：

• 字符长度在0～2之间，必须全部匹配
• 字符长度在3～5之间，允许编辑一次
• 字符长度大于5，允许编辑两次

例如，我的test1索引中，有一个文档的name属性值为sang，我可以使用如下方式查询：

curl -X GET "localhost:9200/test1/_doc/_search?pretty" -H 'Content-Type: application/json' -d'
{
  "query": {
    "fuzzy": {
      "name": "song" 
    }               
  }                  
}     
'

song和sang有一个字符之差，但是由于字符长度为4，因此默认允许编辑一次，所以这个查询是可以查到相关结果的，如下：

如果将song改为soog就会查询失败，此时，可以手动指定fuzziness的值，如下：

curl -X GET "localhost:9200/test1/_doc/_search?pretty" -H 'Content-Type: application/json' -d'
{
  "query": {
    "fuzzy": {
      "name": {
         "value": "soog",
         "fuzziness": 2
       }
    }
  }
}
'

上面的请求表示允许对字符编辑两次，如果编辑两次，则soog就可以匹配上sang了，如下：

Enabling stack traces

默认情况下，当执行的请求出错时，不包括堆栈追踪信息，例如如下请求：

curl -X POST "localhost:9200/twitter/_search?size=surprise_me&pretty"

执行结果如下：

如果加上 error_trace=true就可以查看错误的堆栈信息，如下：

curl -X POST "localhost:9200/twitter/_search?size=surprise_me&pretty&error_trace=true"

请求执行结果如下：

Request body in query string

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

Content-Type Requirements

必须使用Content-Type头信息指定请求正文中发送的内容类型，Content-Type的值必须映射到API支持的一种格式，大多数API支持JSON，YAML，CBOR和SMILE。批量和多搜索API支持NDJSON，JSON和SMILE，其他类型将导致错误响应。 此外，在使用source查询字符串参数时，必须使用sourcecontenttype查询字符串参数指定内容类型。

URL访问控制

当多用户通过URL访问Elasticsearch时，为了防止用户误删等操作，可以通过基于URL的访问控制来限制用户对某个具体索引的访问，在elasticsearch.yml配置文件中添加如下配置：

rest.action.multi.allow_explicit_index: false

将此属性设置为“false”，即禁止了在HTTP请求正文中显式引用索引，这样可防止用户绕过子资源的访问控制。默认情况下，此值为true。

例如如下请求，在修改 rest.action.multi.allow_explicit_index之前是可以执行的：

curl -X POST "localhost:9200/_bulk?pretty" -H 'Content-Type: application/json' -d'
{"index":{"_id":"1","_index":"test2","_type":"doc1"}}
{"name": "John Doe" }
'

修改之后再执行，结果如下：

好了，本文先介绍到这里，有问题欢迎留言讨论。