elasticsearch API约定(二)

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

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


1.elasticsearch安装与配置
2.初识elasticsearch中的REST接口
3.elasticsearch修改数据
4.elasticsearch文档操作
5.elasticsearch API约定(一)


公共参数

下面这些选项可以应用于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": {}	
  }	
}	
'

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

640?wx_fmt=png

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,默认返回结果如下:

640?wx_fmt=png

如果设置了human=true,返回结果如下:

640?wx_fmt=png

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

Date Math

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

表达式含义
+1h在锚定日期的基础上加上1小时
-1d在锚定日期的基础上减去1天
/d在锚定日期的基础上向下舍入到最近的一天

这里支持的时间单位,不同于durations时间支持的时间单位,这里支持的时间单位有:

时间单位含义
y
M
w
d
h小时(12)
H小时(24)
m分钟
s

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

表达式计算结果
now+1h2001-01-01 13:00:00
now-1h2001-01-01 11:00:00
now-1h/d2001-01-01 00:00:00
2001.02.01\|\|+1M/d2001-03-01 00:00:00(2001.02.01加上1个月,再向下舍入到最近一天)

Response Filtering

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

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

请求结果如下:

640?wx_fmt=png

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

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

640?wx_fmt=png

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

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

执行结果如下:

640?wx_fmt=png

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

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

执行结果如下:

640?wx_fmt=png

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

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

执行结果如下:

640?wx_fmt=png

对于 _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"

执行结果如下:

640?wx_fmt=png

Flat Settings

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

640?wx_fmt=png

上图展示了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时间时,时间必须指定单位,单位有如下几种:

符号含义
ddays
hhours
mminutes
sseconds
msmilliseconds
microsmicroseconds
nanosnanoseconds

Byte size units

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

符号含义
bBytes
kbKilobytes
mbMegabytes
gbGigabytes
tbTerabytes
pbPetabytes

Unit-less quantities

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

符号含义

Single
kKilo
mMega
gGiga
tTera
pPeta

Distance Units

在需要指定距离单位的时候,如果没有指定,默认的距离单位是meter(米),也可以手动指定距离单位,支持的距离单位如下:

符号含义
mimilesMile
ydyardsYard
ftfeetFeet
ininchInch
kmkilometersKilometer
mmetersMeter
cmcentimetersCentimeter
mmmillimetersMillimeter
NMnminauticalmilesNauticalmile

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,因此默认允许编辑一次,所以这个查询是可以查到相关结果的,如下:

640?wx_fmt=png

如果将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了,如下:

640?wx_fmt=png

Enabling stack traces

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

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

执行结果如下:

640?wx_fmt=png

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

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

请求执行结果如下:

640?wx_fmt=png

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" }	
'

修改之后再执行,结果如下:

640?wx_fmt=png

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

640?wx_fmt=png

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值