12-十二、Elasticsearch 教程： API 约定-Java极客技术学习

上一章节我们有提到 Elasticsearch 的 RESTful API 使用 HTTP 作为传输协议，使用 JSON 作为数据交换格式。但是，在 API 细节方面，Elasticsearch 还有一些简单的约定。

当然了，我们也可以说是 API 接口规范

API

API，是 Application Programming Interface 的简写，中文译为 应用程序编程接口。

API 是对一组函数调用或用于访问特定 Web 应用程序中的软件组件的其他编程指令，例如，微博 ( Weibo ) API 可帮助开发人员通过访问来自微博的数据或其它功能来创建应用程序，比如实现使用微博账号登录

因为 Elasticsearch 的 RESTful API 使用 HTTP 作为传输协议，使用 JSON 作为数据交换格式，所以它对如何使用 HTTP 发起请求和返回响应，如何使用 JSON 制定了一些规范

多个索引

有些时候，我们可能需要一次访问 API 的过程中在多个位置或所有可用数据中进行搜索，这时候就可能用到一个或多个索引。

Elasticsearch RESTful API 中的大部分操作 ( 主要是搜索 ) ，都适用于一个或多个索引的情况

Elasticsearch 提供了有许多不同的符号用于执行多个索引中的操作

逗号分隔符 ( , )

逗号分隔符用于分隔不同的索引

范例

下面发起的请求用于在 index1 ，index2 ，index3 索引中查询所有包含 any_string 数据


POST http://localhost:9200/index1,index2,index3/_search?pretty

请求正文


{
"query":{
  "query_string":{
     "query":"any_string"
  }
}
}

`_all` 关键字用于所有的索引

如果要在所有的索引中查询，则可以使用 _all 关键字

范例

下面发起的请求用于查询当前服务器上所有索引中包含 any_string 的数据


POST http://localhost:9200/_all/_search?pretty

请求正文


{
"query":{
  "query_string":{
     "query":"any_string"
  }
}
}

通配符 `*` , `+` , `–`

通配符 * , + , – 可以单独使用，也可以组合使用

1、通配符 * 用于匹配任意字符串

例如下面的请求在所有以 user 开头的索引中查找包含 ABCD 的数据


POST http://localhost:9200/user*/_search?pretty

请求正文


{
   "query":{
      "query_string":{
         "query":"ABCD"
      }
   }
}

返回结果如下


{
    "took": 29,
    "timed_out": false,
    "_shards": {
        "total": 10,
        "successful": 10,
        "skipped": 0,
        "failed": 0
    },
    "hits": {
        "total": 0,
        "max_score": null,
        "hits": []
    }
}

2、通配符 * 用于排除某些索引

例如下面的请求在所有以 user 开头但不包括 user_admin 的索引中查找包含 ABCD 的数据


POST http://localhost:9200/user*,-user_admin/_search?pretty

请求正文


{
   "query":{
      "query_string":{
         "query":"ABCD"
      }
   }
}

返回结果如下


{
    "took": 28,
    "timed_out": false,
    "_shards": {
        "total": 5,
        "successful": 5,
        "skipped": 0,
        "failed": 0
    },
    "hits": {
        "total": 0,
        "max_score": null,
        "hits": []
    }
}

除了上面说的这些符号，Elasticsearch 还提供了一些 URI 查询字符串用于指定某些条件

1、ignore_unavailable

如果 URL 中指定的一个或多个索引不存在，则不会抛出错误且不会停止操作，例如存在 user 索引但不存在 php 的索引的情况


POST http://localhost:9200/user*,php/_search

请求正文


{
   "query":{
      "query_string":{
         "query":"CBSE"
      }
   }
}

因为没有添加 ignore_unavailable 参数，所以抛出了错误


{
    "error": {
        "root_cause": [
            {
                "type": "index_not_found_exception",
                "reason": "no such index",
                "resource.type": "index_or_alias",
                "resource.id": "php",
                "index_uuid": "_na_",
                "index": "php"
            }
        ],
        "type": "index_not_found_exception",
        "reason": "no such index",
        "resource.type": "index_or_alias",
        "resource.id": "php",
        "index_uuid": "_na_",
        "index": "php"
    },
    "status": 404
}

但如果使用下面的请求


POST http://localhost:9200/user*,php/_search?ignore_unavailable=true&pretty

请求正文


{
   "query":{
      "query_string":{
         "query":"CBSE"
      }
   }
}

则不会抛出任何错误


{
    "took": 164,
    "timed_out": false,
    "_shards": {
        "total": 10,
        "successful": 10,
        "skipped": 0,
        "failed": 0
    },
    "hits": {
        "total": 0,
        "max_score": null,
        "hits": []
    }
}

2、allow_no_indices

如果一个通配符没有任何匹配的索引存在，如果设置 allow_no_indices 为 true ，则可以阻止抛出错误

例如，假如 Elasticsearch 集群中不存在 PHP* 的索引，那么下面的查询请求将不会报错


POST http://localhost:9200/PHP*/_search?allow_no_indices=true&pretty

请求正文


{
   "query":{
      "match_all":{}
   }
}

返回响应 ( 没有报错 )


{
    "took": 0,
    "timed_out": false,
    "_shards": {
        "total": 0,
        "successful": 0,
        "skipped": 0,
        "failed": 0
    },
    "hits": {
        "total": 0,
        "max_score": 0,
        "hits": []
    }
}

3、expand_wildcards

expand_wildcards 用于设置是否需要扩展通配符以打开索引或封闭索引或两者

该参数的指可以是

值	说明
open	打开索引
close	关闭索引
none	未定义，使用系统默认
all	全部打开

例如我们先使用下面的请求关闭索引 user


POST http://localhost:9200/user/_close?pretty

返回响应


{
    "acknowledged": true
}

然后使用下面的请求来查询


POST http://localhost:9200/user*/_search?expand_wildcards=closed

请求正文


{
   "query":{
      "match_all":{}
   }
}

返回响应如下


{
    "error": {
        "root_cause": [
            {
                "type": "index_closed_exception",
                "reason": "closed",
                "index_uuid": "VYLD0ybxRLeVB_KsJ8ZjDw",
                "index": "user"
            }
        ],
        "type": "index_closed_exception",
        "reason": "closed",
        "index_uuid": "VYLD0ybxRLeVB_KsJ8ZjDw",
        "index": "user"
    },
    "status": 400
}

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

Elasticsearch 提供了根据日期和时间搜索索引的功能

当然，我们需要使用特定的日期和时间格式，例如，accountdetail-2015.12.30 索引用于存储 2015 年 12 月 30 日的银行账户详细信息

Elasticsearch 还允许执行数学运算以获取特定日期或日期和时间范围的详细信息

例如下面的语句用于格式化索引中的日期


<static_name{date_math_expr{date_format|time_zone}}>
http://localhost:9200/<accountdetail-{now-2d{YYYY.MM.dd|utc}}>/_search

参数	说明
static_name	是表达式的一部分，它在每个包含了日期的索引(如帐户详细信息)中保持不变
date_math_expr	动态地确定日期和时间的数学表达式，如now-2d
date_format	生成的日期的格式，如YYYY.MM.dd例如今天的日期是2018年6月27日，那么将返回accountdetail-2018.06.25

表达式	结果
	accountdetail-2018.06.26
	accountdetail-2018.05.27
	accountdetail-2018.06

响应参数

接下来我们将介绍一些 Elasticsearch 中常用的用于定制响应的参数

1、pretty=true

通过添加 pretty=true 参数，返回的 JSON 数据将具有良好的格式以方便阅读

例如下面的请求


POST http://localhost:9200/user_admin/_search?pretty=true

请求正文


{
   "query":{
      "match_all":{}
   }
}

返回的响应为


{
    "took": 13,
    "timed_out": false,
    "_shards": {
        "total": 5,
        "successful": 5,
        "skipped": 0,
        "failed": 0
    },
    "hits": {
        "total": 3,
        "max_score": 1,
        "hits": [
            {
                "_index": "user_admin",
                "_type": "user",
                "_id": "2",
                "_score": 1,
                "_source": {
                    "nickname": "雅少",
                    "description": "虚怀若谷",
                    "street": "四川大学",
                    "city": "Chengdu",
                    "state": "Sichuan",
                    "zip": "610044",
                    "location": [
                        104.094537,
                        30.640174
                    ],
                    "money": 68023,
                    "tags": [
                        "Python",
                        "HTML"
                    ],
                    "vitality": "7.8"
                }
            },
            {
                "_index": "user_admin",
                "_type": "user",
                "_id": "1",
                "_score": 1,
                "_source": {
                    "nickname": "站长",
                    "description": "创业是的天赋是天生的，而我偏偏是后生的",
                    "street": "东四十条",
                    "city": "Beijing",
                    "state": "Beijing",
                    "zip": "100007",
                    "location": [
                        116.432727,
                        39.937732
                    ],
                    "money": 5201314,
                    "tags": [
                        "PHP",
                        "Python"
                    ],
                    "vitality": "9.0"
                }
            },
            {
                "_index": "user_admin",
                "_type": "user",
                "_id": "3",
                "_score": 1,
                "_source": {
                    "nickname": "歌者",
                    "description": "程序设计也是设计，研发新菜也是研发",
                    "street": "五道口",
                    "city": "Beijing",
                    "state": "Beijing",
                    "zip": "100083",
                    "location": [
                        116.346346,
                        39.999333
                    ],
                    "money": 71128,
                    "tags": [
                        "Java",
                        "Scala"
                    ],
                    "vitality": "6.9"
                }
            }
        ]
    }
}

2、human=true

通过添加 human=true 参数，可以格式化返回结果中的数字，默认值为 false

假如返回的响应存在某个字段 distance_kilometer，保存的值为 20000

如果 human=true，那么将返回 distance_kilometer=20KM
如果 human=false，那么将返回 distance_meter=20000
3、filter_path

该参数用于筛选响应中的字段

例如下面的请求


POST http://localhost:9200/user/_search?filter_path=hits.total

请求正文


{
   "query":{
      "match_all":{}
   }
}

那么返回结果就只会包含下面的内容


{
    "hits": {
        "total": 3
    }
}

希望读者能够给小编留言，也可以点击[此处扫下面二维码关注微信公众号](https://www.ycbbs.vip/?p=28 "此处扫下面二维码关注微信公众号")

看完两件小事

如果你觉得这篇文章对你挺有启发，我想请你帮我两个小忙：

关注我们的 GitHub 博客，让我们成为长期关系
把这篇文章分享给你的朋友 / 交流群，让更多的人看到，一起进步，一起成长！
关注公众号 「方志朋」，公众号后台回复「666」免费领取我精心整理的进阶资源教程

JS中文网,Javascriptc中文网是中国领先的新一代开发者社区和专业的技术媒体,一个帮助开发者成长的社区，是给开发者用的 Hacker News，技术文章由为你筛选出最优质的干货，其中包括：Android、iOS、前端、后端等方面的内容。目前已经覆盖和服务了超过 300 万开发者，你每天都可以在这里找到技术世界的头条内容。

本文著作权归作者所有，如若转载，请注明出处

转载请注明：文章转载自「 Java极客技术学习 」https://www.javajike.com

标题：12-十二、Elasticsearch 教程： API 约定

链接：https://www.javajike.com/article/1255.html

打赏

微信扫一扫

0 0

12-十二、Elasticsearch 教程： API 约定

API

多个索引

逗号分隔符 ( , )

范例

_all 关键字用于所有的索引

范例

通配符 * , + , –

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

响应参数

看完两件小事

相关推荐

请登录

`_all` 关键字用于所有的索引

通配符 `*` , `+` , `–`