第三讲—RESTful API探索（一）

本节大部分内容转载至(

         Elasticsearch 基础教程

        翻译:潘飞(tinylambda@gmail.com) 

)

 

探索你的集群

一、rest 接口

        现在我们已经有一个正常运行的节点(和集群)了,下一步就是要去理解怎样与其 通信了。幸运的是,Elasticsearch 提供了非常全面和强大的 REST API,利用这个 REST API 你可以同你的集群交互。下面是利用这个 API,可以做的几件事情:  

        - 检查你的集群、节点和索引的健康状态、和各种统计信息
        - 管理你的集群、节点、索引数据和元数据
        - 对你的索引进行 CRUD(创建、读取、更新和删除)和搜索操作
        - 执行高级的查询操作,像是分页、排序、过滤、脚本编写(scripting)、小平面刻画(faceting)、聚合(aggregations)和许多其它操作

        

        1.1 检查集群的健康状态：http://localhost:9200/_cat/health?v 返回结果如下:

        

 

        可以看到,我们集群的名字是“Minutch”,正常运行,并且状态是绿色。 

 

        当我们询问集群状态的时候,我们要么得到绿色、黄色或红色。绿色代表一切正常 (集群功能齐全),黄色意味着所有的数据都是可用的,但是某些复制没有被分配(集群功 能齐全),红色则代表因为某些原因,某些数据不可用。注意,即使是集群状态是红色的, 集群仍然是部分可用的(它仍然会利用可用的分片来响应搜索请求),但是可能你需要尽快 修复它,因为你有丢失的数据。

        也是从上面的响应中,我们可以看到,一共有一个节点,由于里面没有数据,我们 有 0 个分片。注意,由于 Elasticsearch 默认使用网络多播(multicast)发现其它节点,如果你在你的网络中启动了多个节点,你就 已经把她们加入到一个集群中了。在这种情形下,你可能在上面的响应中看到多个节点。 

        

        1.2 获得节集群中的节点列表: http://localhost:9200/_cat/nodes?v 为了结果全面，我使用另一台电脑启动了elastic search，结果如下：

        

        1.3 列出所有的索引：http://localhost:9200/_cat/indices?v 结果如下：

         

         这个结果意味着,在我们的集群中,我们没有任何索引，事实上，我真的没有创建任何索引。

         1.4 创建一个名称为'customer'的索引，在终端执行：curl -XPUT 'localhost:9200/customer?pretty'  返回结果：

         

          使用 PUT 创建了一个叫做“customer”的索引。我们简单地将 pretty 附 加到调用的尾部,使其以美观的形式打印出 JSON 响应。再去执行1.3的命令

         

        现在有一个叫做 customer 的索引,并且它有 5 个主分片和 1 份复制(都是默认值),其中包含 0 个文档。 

        你可能也注意到了这个 customer 索引有一个黄色健康标签。回顾我们之前的讨论, 黄色意味着某些复制没有(或者还未)被分配。这个索引之所以这样,是因为 Elasticsearch 默认为这个索引创建一份复制。由于现在我们只有一个节点在运行,那一份复制就分配不了 了(为了高可用),直到当另外一个节点加入到这个集群后,才能分配。一旦那份复制在第 二个节点上被复制,这个节点的健康状态就会变成绿色。 

         1.5 索引一个文档：curl -XPUT 'localhost:9200/customer/external/1?pretty' -d ' {"name": "John Doe" }'       

         执行后，返回如下结果：

        

        从上面的响应中,我们可以看到,一个新的客户文档在 customer 索引和 external 类型中被成功创建。文档也有一个内部 id 1, 这个 id 是我们在索引的时候指定的。

        有一个关键点需要注意,Elasticsearch 在你想将文档索引到某个索引的时候,并不强制 要求这个索引被显式地创建。在前面这个例子中,如果 customer 索引不存在,Elasticsearch 将会自动地创建这个索引。 

        1.6 取出索引的文档：curl -XGET 'localhost:9200/customer/external/1?pretty' 

         

         除了一个叫做 found 的字段来指明我们找到了一个 ID 为 1 的文档,和另外一个字段——_source——返回我们前一步中索引的完整 JSON 文档之外,其它的都没有什么特别之处。 

        

        1.7 删除一个索引：curl -XDELETE 'localhost:9200/customer?pretty' 

 

         

      

        1.8 小结

        如果我们仔细研究以上的命令,我们可以发现访问 Elasticsearch 中数据的一个模式。这个模式可以被总结为:

        curl -<REST Verb> <Node>:<Port>/<Index>/<Type>/<ID>
        这个 REST 访问模式普遍适用于所有的 API 命令,如果你能记住它,你就会为掌握Elasticsearch 开一个好头。 

 

二、修改数据

        2.1 索引/替换文档

        我们先前看到,怎样索引一个文档。现在我们再次调用那个命令:curl -XPUT 'localhost:9200/customer/external/1?pretty' -d ' {"name": "John Doe" }'

        再次,以上的命令将会把这个文档索引到 customer 索引、external 类型中,其 ID 是 1。如果我们对一个不同(或相同)的文档应用以上的命令,Elasticsearch 将会用一个新 的文档来替换(重新索引)当前 ID 为 1 的那个文档。

        curl -XPUT 'localhost:9200/customer/external/1?pretty' -d ' {"name": "Jane Doe" }'

        以上的命令将 ID 为 1 的文档的 name 字段的值从“John Doe”改成了“Jane Doe”。 如果我们使用一个不同的 ID,一个新的文档将会被索引,当前已经在索引中的文档不会受 到影响。

        curl -XPUT 'localhost:9200/customer/external/2?pretty' -d ' {"name": "Jane Doe" }'

        以上的命令,将会索引一个 ID 为 2 的新文档。

 

        在索引的时候,ID 部分是可选的。如果不指定,Elasticsearch 将产生一个随机的 ID 来索引这个文档。Elasticsearch 生成的 ID 会作为索引 API 调用的一部分被返回。

        以下的例子展示了怎样在没有指定 ID 的情况下来索引一个文档:

                curl -XPOST 'localhost:9200/customer/external?pretty' -d ' {"name": "Minutch" }' 

        注意,在上面的情形中,由于我们没有指定一个 ID,我们使用的是 POST 而不是 PUT，返回结果如下：

        

        2.2 更新文档

        除了可以索引、替换文档之外,我们也可以更新一个文档。但要注意,Elasticsearch 底 层并不支持原地更新。在我们想要做一次更新的时候,Elasticsearch 先删除旧文档,然后在 索引一个更新过的新文档。

        下面的例子展示了怎样将我们 ID 为 1 的文档的 name 字段改成“Jane Doe”:

        curl -XPOST 'localhost:9200/customer/external/1/_update?pretty' -d ' {"doc": { "name": "Jane Doe" } }'

        下面的例子展示了怎样将我们 ID 为 1 的文档的 name 字段改成“Jane Doe”的同时,给 它加上 age 字段:

        curl -XPOST 'localhost:9200/customer/external/1/_update?pretty' -d ' {"doc": { "name": "Jane Doe", "age": 20 } }'

        更新也可以通过使用简单的脚本来进行。这个例子使用一个脚本将 age 加 5:

        curl -XPOST 'localhost:9200/customer/external/1/_update?pretty' -d ' {"script" : "ctx._source.age += 5" }'

        在上面的例子中,ctx._source 指向当前要被更新的文档。

 

        注意,在写作本文时,更新操作只能一次应用在一个文档上。将来,Elasticsearch 将提 供同时更新符合指定查询条件的多个文档的功能(类似于 SQL 的 UPDATE-WHERE 语句) 

 

 

        2.3 删除文档

 

        删除文档是相当直观的。以下的例子展示了我们怎样删除 ID 为 2 的文档:

        curl -XDELETE 'localhost:9200/customer/external/2?pretty'

        我们也能够一次删除符合某个查询条件的多个文档。以下的例子展示了如何删除名字中 包含“John”的所有的客户:  

        curl -XDELETE 'localhost:9200/customer/external/_query?pretty' -d ' {"query": { "match": { "name": "John" } } }'

        注意,以上的 URI 变成了/_query,以此来表明这是一个“查询删除”API,其中删除查 询标准放在请求体中,但是我们仍然使用 DELETE。现在先不要担心查询语法,我们将会在 本教程后面的部分中涉及。 

        2.4 批处理

        除了能够对单个的文档进行索引、更新和删除之外,Elasticsearch 也提供了以上操作的 批量处理功能,这是通过使用_bulk API 实现的。这个功能之所以重要,在于它提供了非常 高效的机制来尽可能快的完成多个操作,与此同时使用尽可能少的网络往返。

        作为一个快速的例子,以下调用在一次 bulk 操作中索引了两个文档(ID 1 - John Doe and ID 2 - Jane Doe):

        curl -XPOST 'localhost:9200/customer/external/_bulk?pretty' -d

                ' {"index":{"_id":"1"}}

                 {"name": "John Doe" }

                 {"index":{"_id":"2"}} 

                 {"name": "Jane Doe" } '

        以下例子在一个 bulk 操作中,首先更新第一个文档(ID 为 1),然后删除第二个文档(ID 为 2 ):

        curl -XPOST 'localhost:9200/customer/external/_bulk?pretty' -d

                '{"update":{"_id":"1"}}

                 {"doc": { "name": "John Doe becomes Jane Doe" } }

                {"delete":{"_id":"2"}}'

        注意上面的 delete 动作,由于删除动作只需要被删除文档的 ID,所以并没有对应的源 文档。

        bulk API 按顺序执行这些动作。如果其中一个动作因为某些原因失败了,将会继续处理 它后面的动作。当 bulk API 返回时,它将提供每个动作的状态(按照同样的顺序),所以你能够看到某个动作成功与否。