API Conventions

elasticsearch的REST的API是使用HTTP的JSON格式暴露的。

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

1、多索引

大多数引用index参数的API 支持跨多个索引执行,使用简单的test1,test2,test3符号(或_all用于所有的索引 )。

它还支持通配符,例如:test*或 *test 或 te*t或*test*,以及“排除”(-)的能力,例如:test*,-test3。

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

1.1 ignore_unavailable

​ 控制是否忽略任何指定的索引是否不可用,包括不存在的索引或闭合索引。可以指定true或false。

1.2 allow_no_indices

​ 如果通配符索引表达式导致没有具体索引,则控制是否失败。可以指定true或false。例如,如果指定了通配符表达式 foo 并且没有以 foo 开头的索引,则根据此设置,请求将失败。当指定了 _all,或 no index 时,此设置也适用。如果别名指向封闭索引,则此设置也适用于别名。

1.3 expand_wildcards

​ 控制通配符索引表达式可以扩展到的具体索引类型。如果指定了open,则通配符表达式将扩展为仅打开索引。如果指定closed,则通配符表达式仅扩展为闭合索引。此外,可以指定两个值(openclosed)以扩展到所有索引。

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

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

单个索引API(如Document API单索引alias API)不支持多个索引。

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

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

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

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

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

说明:

参数 说明
static_name 是名称的静态文本部分
date_math_expr 是动态计算日期的动态日期数学表达式
date_format 是应该呈现计算日期的可选格式。默认为yyyy.MM.dd.格式应与java-time兼容
time_zone 是可选的时区。默认为utc

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

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

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

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

符号 URI编码
< %3C
> %3E
/ %2F
{ %7B
} %7D
| %7C
+ %2B
: %3A
, %2C

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

表达式 解析为
<logstash-{now/d}> logstash-2024.03.22
<logstash-{now/M}> logstash-2024.03.01
<logstash-{now/M{YYYY.MM}}> logstash-2024.03
<logstash-{now/M-1M{YYYY.MM}}> logstash-2024.02
<logstash-{now/d{YYYY.MM.dd|+12:00}}> logstash-2024.03.23

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

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

3、常规选项

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

3.1 格式化相应(Pretty Result)

在任何请求后追加?pretty=true,返回的JSON格式都会非常好(仅用于调试!)。另一个选项是追加

?format=yaml,有时这将导致结果以更可读的yaml格式返回。

3.2 人类可读式输出(Human readable output)

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

3.3 日期数学(Date Math)

它接受一个格式化的日期值参数—比如在范围(range)查询的gt和lt,或在daterange aggregations中的from与to。

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

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

支持的时间单位与持续时间单位支持的时间单位不同。支持的单位如下:

单位 含义
y
M
w
d
h 小时
H 小时
m 分钟
s

假设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.02.01||+1M/d

​ 2001.02.1以毫秒格式加一个月。解析后为:2001-03-01 00:00:00

响应过滤(Response Filtering)

所有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
      }
    ]
  }
}

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

curl -X GET "localhost:9200/_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"}]
        }
      }
    }
  }
}

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

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参数(参见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"}
    } ]
  }
}

3.4 平面设置(Flat Settings)

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。

3.5 参数(Parameters)

Rest参数(使用HTTP时,映射到HTTP URL参数)遵循使用下划线框的约定。

3.6 布尔值(Boolean Values)

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

3.7 数值(Number Values)

所有REST API都支持在JSON数字类型的基础上将编号参数作为字符串提供。

3.8 时间单位(Time units)

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

单位 含义
d
h 小时
m 分钟
s
ms 毫秒
micros 微秒
nanos 纳秒

3.9 字节大小单位(Byte size units)

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

单位 含义
b 字节
kb 千字节
mb 兆字节
gb 千兆字节
tb 兆兆字节
pb 拍字节

3.10 无单位量化(Unit-less quantities)

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

如果这些数量中的一个很大,我们会将其打印出来,例如10万,10,000,000或7k,7,000。当我们的意思是87时,我们仍会打印87。这些是受支持的乘数:

缩写 含义
k Kilo(公斤)
m Mega(兆)
g Giga(千兆)
t Tera(万亿)
p Peta(千兆)

3.11 距离单位(Distance Units)

无论何处需要指定距离,例如地理距离查询中的距离参数,如果未指定距离,则默认单位为米。距离可以在其他单位中指定,例如“1km”或“2mi”(2英里)。

名称 单位参数
Mile(英里) mi 或 miles
Yard(码) yd or yards
Feet(英尺) ft or feet
Inch(英寸) in or inch
Kilometer(公里) km or kilometers
Meter(米) m or meters
Centimeter(厘米) cm or centimeters
Millimeter(毫米) mm or millimeters
Nautical mile(纳米) NM, nmi, or nauticalmiles

3.12 模糊性(Fuzziness)

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

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

fuzziness参数可以被指定为:

0,1,2
​ 最大允许的Levenshtein编辑距离(或编辑数量)

AUTO
​ 根据术语的长度生成编辑距离。低距离和高距离参数可以选择提供AUTO:[Low],[high],如果没有指定,默认值是3和6,相当于AUTO:3,6:
​ 0..2

​ 必须完全匹配

​ 3..5

​ 允许一个编辑距离

​ >5

​ 允许两个编辑距离

对于fuzziness最好首先使用AUTO

3.13 启用堆栈轨迹(Enabling stack traces)

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

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
}

3.14 查询字符串中的请求正文(Request body in query string)

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

3.15 必要的Content-Type

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

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

4、基于URL的访问控制(Content-Type Requirements)

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

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

rest.action.multi.allow_explicit_index:false

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

elasticsearch6.7 04.API规范的更多相关文章

  1. 后端api规范说明文档

    我们此次后端api的实现主要是按照RESTful api规范来设计的,就是符合REST架构下设计api的规范.简单的来说REST结构就是:利用URL定位资源,用HTTP动词(GET,POST,PUT, ...

  2. ElasticSearch6.0 Java API 使用 排序,分组 ,创建索引,添加索引数据,打分等(一)

    ElasticSearch6.0  Java API  使用     排序,分组 ,创建索引,添加索引数据,打分等 如果此文章对你有帮助,请关注一下哦 1.1 搭建maven 工程  创建web工程 ...

  3. 从入门到自闭之Python--RESTful API规范与序列化

    RESTful API规范 REST全称是Representational State Transfer,中文意思是表述(编者注:通常译为表征)性状态转移. 它首次出现在2000年Roy Fieldi ...

  4. day71:drf:API接口&Restful API规范&Django Rest Framework&drf中的序列化和反序列化功能

    目录 1.web应用模式 2.API接口 3.Restful API规范 4.序列化 5.Django Rest Framework 1.drf的简单介绍 2.drf的特点 3.如何安装drf 4.d ...

  5. 【译】Android API 规范

    [译]Android API 规范 译者按: 修改R代码遇到Lint tool的报错,搜到了这篇文档,aosp仓库地址:Android API Guidelines. 58e9b5f Project ...

  6. 【译】Android NDK API 规范

    [译]Android NDK API 规范 译者按: 修改R代码遇到Lint tool的报错,搜到了这篇文档,aosp仓库地址:Android NDK API Guidelines. 975a589 ...

  7. restful API 规范(转)

    1. URI URI 表示资源,资源一般对应服务器端领域模型中的实体类. URI规范 不用大写: 用中杠-不用下杠_: 参数列表要encode: URI中的名词表示资源集合,使用复数形式. 资源集合 ...

  8. RESTful API规范

    1. 域名 应该尽量将API部署在专用的域名下. https://api.example.com 如果确定API简单,不会有进一步的括在,可以考虑放在主域名之下. https://example.or ...

  9. API规范约定

    为了高效开发,节约编写文档的成本,API服务使用Swagger来描述 一.API设计原则 控制API的粒度和数量 命名要遵循简单.可读.统一原则: 优先设计API,然后编码 二.URL设计[针对后端开 ...

随机推荐

  1. 剑指offer编程题Java实现——面试题4替换空格

    题目描述 请实现一个函数,将一个字符串中的空格替换成“%20”.例如,当字符串为We Are Happy.则经过替换之后的字符串为We%20Are%20Happy. package Solution; ...

  2. 【BZOJ3280】 小R的烦恼(费用流,建模)

    有很浓厚的熟悉感?餐巾计划问题? 不就是多了几个医院,相当于快洗部和慢洗部开了分店. 考虑建图: 如果把每一天拆成两个点,一个表示需求,另一个表示拥有的话. 显然就是一个两边的图,考虑如果我现在有人, ...

  3. Linux系统软件包的管理(4)

    虽然使用源码编译安装可以具有提高速度个性化的定制等优点,但对于 Linux发行商来说,则不容易管理软件包,毕竟不是每个人都会进行源码编译的,如果能够将软件预先在相同的硬体与系统上面编译好在发布的话,不 ...

  4. 分布式锁实现思路及开源项目集成到springmvc并使用

    分布式锁顾名思义就是在分布式系统下的锁,而使用锁的唯一目的就是为了防止多个请求同时对某一个资源进行竞争性读写 在使用多线程时,为了让某一资源某一时刻只能有一个操作者,经常使用synchronized, ...

  5. spring mvc开发过程中的乱码问题

    在保证jsp,xml,数据库,编辑器编码一致的情况下. 1,用户输入中文,后台接收到也是中文,但是保存到数据库时乱码, 解决方法: 链接数据库的url="jdbc:mysql://local ...

  6. Windows平台下搭建自己的Git服务器

    该文章转自:http://www.codeceo.com/article/windows-git-server.html Gitblit 是一个纯 Java 库用来管理.查看和处理 Git 资料库,相 ...

  7. log4j UdpAppender

    package cappender;import org.apache.log4j.AppenderSkeleton;import org.apache.log4j.Layout;import org ...

  8. EFCore.MySql当模型遇到int[]怎么办

    我使用的是Pomole.EntityFrameworkCore.MySql 需要将旧项目中的excels表转成实体,其中有一列是json格式的int[] 当遇到第一张表的时候,我使用了这样的方法来读取 ...

  9. Windows 8.1 GetVersionEx返回6.2.9200 的问题!

    http://msdn.microsoft.com/en-us/library/windows/desktop/dn302074.aspx http://tunps.com/getversionex- ...

  10. js实现生成中间带图片的二维码

    之前需要实现生成中间带图片的二维码,所以找了半天终于找到一个可以用的.于是在这里记录一下. 下面是需要注意的几点: 1.使用的js为jquery-qrcode 但是已经经过别人的修改,和网上原来的那些 ...