› ›

Elasticsearch API

Elasticsearch API编辑

elasticsearch-api 库提供了 Elasticsearch REST API 的 Ruby 实现。

安装编辑

从 Rubygems 安装包

gem install elasticsearch-api

要使用未发布的版本，请将其添加到您的 Gemfile 中，用于 Bundler

gem 'elasticsearch-api', git: 'git://github.com/elasticsearch/elasticsearch-ruby.git'

或从源代码检出安装

git clone https://github.com/elasticsearch/elasticsearch-ruby.git
cd elasticsearch-ruby/elasticsearch-api
bundle install
rake install

示例用法编辑

该库被设计为一组独立的 Ruby 模块，可以混合到一个类中，该类提供与 Elasticsearch 的连接——一个 Elasticsearch 客户端。

与 `elasticsearch` gem 一起使用编辑

当您从 elasticsearch-ruby 客户端使用客户端时，库模块已被包含，因此您只需调用 API 方法。

响应将是一个 Elasticsearch::API::Response 对象，它包装一个 Elasticsearch::Transport::Transport::Response 对象。它提供了 body、status 和 headers 方法，但您可以将其视为一个哈希并直接访问键。

require 'elasticsearch'

client = Elasticsearch::Client.new

>response = client.index(index: 'myindex', id: 1, body: { title: 'Test' })
=> #<Elasticsearch::API::Response:0x00007fc9564b4980
 @response=
  #<Elastic::Transport::Transport::Response:0x00007fc9564b4ac0
   @body=
    {"_index"=>"myindex",
     "_id"=>"1",
     "_version"=>2,
     "result"=>"updated",
     "_shards"=>{"total"=>1, "successful"=>1, "failed"=>0},
     "_seq_no"=>1,
     "_primary_term"=>1},
   @headers=
    {"x-elastic-product"=>"Elasticsearch",
     "content-type"=>"application/json",
     "content-encoding"=>"gzip",
     "content-length"=>"130"},
   @status=200>>

> response['result']
=> "updated"

client.search(index: 'myindex', body: { query: { match: { title: 'test' } } })
# => => #<Elasticsearch::API::Response:0x00007fc95674a550
 @response=
  #<Elastic::Transport::Transport::Response:0x00007fc95674a5c8
   @body=
    {"took"=>223,
     "timed_out"=>false,
     "_shards"=>{"total"=>2, "successful"=>2, "skipped"=>0, "failed"=>0},
     "hits"=>
      {"total"=>{"value"=>1, "relation"=>"eq"},
       "max_score"=>0.2876821,
       "hits"=>[{"_index"=>"myindex", "_id"=>"1", "_score"=>0.2876821, "_source"=>{"title"=>"Test"}}]}},
   @headers=
    {"x-elastic-product"=>"Elasticsearch",
     "content-type"=>"application/json",
     "content-encoding"=>"gzip",
     "content-length"=>"188"},
   @status=200>>

完整的文档和示例包含在源代码中的 RDoc 注释中，并在线提供，网址为 http://rubydoc.info/gems/elasticsearch-api。

使用自定义客户端编辑

当您想将库与您自己的客户端混合使用时，它必须符合以下契约

它响应一个 perform_request(method, path, params, body, headers) 方法，
该方法返回一个具有 status、body 和 headers 方法的对象。

一个简单的客户端可能看起来像这样（依赖于 active_support 来解析查询参数）

require 'multi_json'
require 'faraday'
require 'elasticsearch/api'

class MySimpleClient
  include Elasticsearch::API

  CONNECTION = ::Faraday::Connection.new(url: 'https://127.0.0.1:9200')

  def perform_request(method, path, params, body, headers = nil)
    puts "--> #{method.upcase} #{path} #{params} #{body} #{headers}"

    CONNECTION.run_request \
      method.downcase.to_sym,
      path_with_params(path, params),
      ( body ? MultiJson.dump(body): nil ),
      {'Content-Type' => 'application/json'}
  end

  private

  def path_with_params(path, params)
    return path if params.blank?

    case params
    when String
      "#{path}?#{params}"
    when Hash
      "#{path}?#{URI.encode_www_form(params)}"
    else
      raise ArgumentError, "Cannot parse params: '#{params}'"
    end
  end
end

client = MySimpleClient.new

p client.cluster.health
# --> GET _cluster/health {}
# => "{"cluster_name":"elasticsearch" ... }"

p client.index(index: 'myindex', id: 'custom', body: { title: "Indexing from my client" })
# --> PUT myindex/mytype/custom {} {:title=>"Indexing from my client"}
# => "{"ok":true, ... }"

使用 JSON 生成器编辑

与其将 :body 参数作为 Ruby Hash 传递，不如将其作为String 传递，这可能会利用 JSON 生成器，例如 JBuilder 或 Jsonify

require 'jbuilder'

query = Jbuilder.encode do |json|
  json.query do
    json.match do
      json.title do
        json.query    'test 1'
        json.operator 'and'
      end
    end
  end
end

client.search(index: 'myindex', body: query)

# 2013-06-25 09:56:05 +0200: GET https://127.0.0.1:9200/myindex/_search [status:200, request:0.015s, query:0.011s]
# 2013-06-25 09:56:05 +0200: > {"query":{"match":{"title":{"query":"test 1","operator":"and"}}}}
# ...
# => {"took"=>21, ..., "hits"=>{"total"=>1, "hits"=>[{ "_source"=>{"title"=>"Test 1", ...}}]}}

使用哈希包装器编辑

为了更方便地访问响应属性，您可以将其包装在其中一个Hash“对象访问”包装器中，例如 Hashie::Mash

require 'hashie'

response = client.search(
  index: 'myindex',
  body: {
    query: { match: { title: 'test' } },
    aggregations: { tags: { terms: { field: 'tags' } } }
  }
)

mash = Hashie::Mash.new(response)

mash.hits.hits.first._source.title
# => 'Test'

使用自定义 JSON 序列化器编辑

该库默认使用 MultiJson gem，但允许您设置自定义 JSON 库，前提是它使用标准的 load/dump 接口

Elasticsearch::API.settings[:serializer] = JrJackson::Json
Elasticsearch::API.serializer.dump({foo: 'bar'})
# => {"foo":"bar"}

« 传输使用 OpenTelemetry »

Elasticsearch API