elastic-enterprise-search 7.10.0.beta.1 → 7.11.0

data/docs/guide/connecting.asciidoc

@@ -0,0 +1,125 @@
+[[connecting]]
+== Connecting
+
+
+This page contains the information you need to connect and use the Client with Elastic Enterprise Search.
+
+**On this page**
+
+* <<authentication>>
+* <<custom_headers>>
+
+
+[discrete]
+[[authentication]]
+=== Authentication
+
+
+This section contains code snippets to show you how to connect to Enterprise Search, App Search, and Workplace Search.
+
+Each service has its own authentication schemes. Using the `http_auth` property with either a string for a key / token or a tuple of `(username, password)` for basic authentication will set the proper `Authorization` HTTP header on the client instance.
+
+[discrete]
+[[auth-ent]]
+==== Authenticating with Enterprise Search
+
+Enterprise Search supports HTTP basic authentication with a username and password.
+
+HTTP basic authentication uses the `http_auth` parameter by passing in a username and password as a tuple:
+
+[source,rb]
+----------------------------
+http_auth = {user: 'elastic', password: 'password'}
+host = 'https://id.ent-search.europe-west2.gcp.elastic-cloud.com'
+
+ent_client = Elastic::EnterpriseSearch::Client.new(host: host, http_auth: http_auth)
+----------------------------
+
+
+[discrete]
+[[auth-as]]
+==== Authenticating with App Search
+
+In your Elastic App Search dashboard, navigate to Credentials and Create a Key for the client to use. Make sure to read https://www.elastic.co/guide/en/app-search/current/authentication.html[the documentation on Authentication] to understand which key you want to use. Once you've created your key, you need to copy the key value to use on your client.
+
+The App Search client can be accessed from an existing Enterprise Search Client, or you can initialize a new one. If you instantiate the App Search client from an existing Enterprise Search Client, it's going to share the HTTP transport instance, so it's going to connect to the same host which is a common scenario. However, if you want to connect to a different host, you should instantiate a new App Search Client on its own.
+
+[source,rb]
+----------------------------
+host = 'https://id.ent-search.europe-west2.gcp.elastic-cloud.com'
+api_key = 'private-api-key'
+
+# From the Enterprise Search client:
+ent_client = Elastic::EnterpriseSearch::Client.new(host: host)
+ent_client.app_search.http_auth = api_key
+
+# On its own
+client = Elastic::EnterpriseSearch::AppSearch::Client.new(host: host, http_auth: api_key)
+----------------------------
+
+[discrete]
+[[signed-search-key]]
+===== Signed search key
+
+App Search also supports https://www.elastic.co/guide/en/app-search/current/authentication.html#authentication-signed[authenticating with signed search keys]. Here's an example on how to use it:
+
+[source,rb]
+----------------------------
+public_search_key = 'search-key-value'
+# This name must match the name of the key above from your App Search dashboard
+public_search_key_name = 'search-key'
+
+# Say we have documents with a title and an author. We want this key to be able
+#  to search by title, but only return the author:
+options = {
+  search_fields: { title: {} },
+  result_fields: { author: { raw: {} } }
+}
+
+signed_search_key = Elastic::EnterpriseSearch::AppSearch::Client.create_signed_search_key(public_search_key, public_search_key_name, options)
+
+client = Elastic::EnterpriseSearch::AppSearch::Client.new(http_auth: signed_search_key)
+
+client.search(engine_name, query: 'jungle')
+----------------------------
+
+[discrete]
+[[auth-ws]]
+==== Authenticating with Workplace Search
+
+In your Elastic Workplace Search dashboard navigate to _Sources/Add a Shared Content Source_ and select _Custom API Source_ to create a new source. Name your source (e.g. `Enterprise Search Ruby Client`) and once it's created you'll get an `access token` and an `ID`. You'll need these in the following steps.
+
+The Workplace Search client can be accessed from an existing Enterprise Search Client, or you can initialize a new one. If you instantiate the Workplace Search client from an existing Enterprise Search Client, it's going to share the HTTP transport instance, so it's going to connect to the same host, which is a common scenario. However, if you want to connect to a different host, you should instantiate a new Workplace Client on its own:
+
+[source,rb]
+----------------------------
+host = 'https://id.ent-search.europe-west2.gcp.elastic-cloud.com'
+access_token = '<access token>'
+content_source_id = '<content source id>'
+
+# From the Enterprise Search client:
+ent_client = Elastic::EnterpriseSearch::Client.new(host: host)
+ent_client.workplace_search.http_auth = access_token
+ent_client.workplace_search.index_documents(content_source_id, body: documents)
+
+# On its own
+workplace_search_client = Elastic::EnterpriseSearch::WorkplaceSearch::Client.new(
+  host: host,
+  http_auth: access_token
+)
+----------------------------
+
+[discrete]
+[[custom_headers]]
+=== Custom HTTP Headers
+
+You can pass in headers as a parameter to any of the API Endpoints to set custom headers for the request:
+
+[source,rb]
+----------------------------
+headers = { 'x-custom-header' => 'Header value' }
+workplace_search_client.index_documents(
+  content_source_id,
+  { body: documents, headers: headers }
+)
+----------------------------

data/docs/guide/development.asciidoc

@@ -0,0 +1,42 @@
+[[development]]
+== Development
+
+[discrete]
+=== Run Stack locally
+
+A rake task is included to run the Elastic Enterprise Search stack locally via Docker:
+
+[source,bash]
+----------------------------
+$ rake stack[7.10.0]
+----------------------------
+
+This will run Elastic Enterprise Search in http://localhost:3002
+- Username: `enterprise_search`
+- Password: `changeme`
+
+[discrete]
+=== Run Tests
+
+Unit tests for the clients:
+
+[source,bash]
+----------------------------
+$ rake spec:client
+----------------------------
+
+Integration tests: you need to have an instance of Enterprise Search running either locally or remotely, and specify the host and credentials in environment variables (see below for a complete dockerized setup). If you're using the included rake task `rake stack[:version]`, you can run the integration tests with the following command:
+
+[source,bash]
+----------------------------
+$ ELASTIC_ENTERPRISE_HOST='http://localhost:3002' \
+  ELASTIC_ENTERPRISE_USER='elastic' \
+  ELASTIC_ENTERPRISE_PASSWORD='changeme' \
+  rake spec:integration
+----------------------------
+
+Run integration tests completely within containers, the way we run them on our CI:
+[source,bash]
+----------------------------
+RUNSCRIPTS=enterprise-search STACK_VERSION=7.10.0 ./.ci/run-tests
+----------------------------

data/docs/guide/enterprise-search-api.asciidoc

@@ -0,0 +1,46 @@
+[[enterprise-search-api]]
+== Enterprise Search API
+
+=== Health API
+
+[source,rb]
+----------------------------
+> response = ent_client.health
+> response.body
+ => {"name"=>"...",
+     "version"=>{"number"=>"7.10.0", "build_hash"=>"...", "build_date"=>"..."},
+     "jvm"=>{...},
+     "filebeat"=>{...},
+     "system"=>{...}
+    }
+----------------------------
+
+=== Version API
+
+[source,rb]
+----------------------------
+> response = ent_client.version
+> response.body
+ => {"number"=>"7.10.0", "build_hash"=>"...", "build_date"=>"..."}
+----------------------------
+
+=== Managing Read-Only mode:
+
+[source,rb]
+----------------------------
+# Set read-only flag state
+ent_client.put_read_only(body: { enabled: false })
+
+# Get read-only flag state
+ent_client.read_only
+----------------------------
+
+=== Stats API
+
+[source,rb]
+----------------------------
+> ent_client.stats.body
+ => {"app"=>{"pid"=>1, "start"=>"...", "end"=>"", "metrics"=>{...}},
+     "queues"=>{"connectors"=>{...}, "document_destroyer"=>{...}, "engine_destroyer"=>{...}, "index_adder"=>{...}, ...},
+     "connectors"=>{"alive"=>true, "pool"=>{...}, "job_store"=>{...}}}}
+----------------------------

data/docs/guide/index.asciidoc

@@ -0,0 +1,17 @@
+= enterprise-search-ruby
+
+:doctype: book
+
+include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
+
+include::overview.asciidoc[]
+
+include::installation.asciidoc[]
+
+include::connecting.asciidoc[]
+
+include::enterprise-search-api.asciidoc[]
+
+include::app-search-api.asciidoc[]
+
+include::workplace-search-api.asciidoc[]

data/docs/guide/installation.asciidoc

@@ -0,0 +1,18 @@
+[[installation]]
+== Installation
+
+You can install Enterprise Search Client from Rubygems:
+
+[source,sh]
+---------------------------------------------------
+$ gem install elastic-enterprise-search --pre
+---------------------------------------------------
+
+Or add it to your project's Gemfile:
+
+[source,sh]
+---------------------------------------------------
+gem 'elastic-enterprise-search'
+---------------------------------------------------
+
+The version follows the Elastic Stack version so 7.10.0 is compatible with Enterprise Search released in Elastic Stack 7.10.0.

data/docs/guide/overview.asciidoc

@@ -0,0 +1,59 @@
+[[overview]]
+== Overview
+
+This is the official Ruby client for Elastic Enterprise Search.
+
+[discrete]
+=== Compatibility
+
+Current development happens in the master branch.
+
+The library is compatible with all Elastic Enterprise Search versions since `7.x` but you **have to use a matching major version**:
+
+For **Elastic Enterprise Search 7.0** and later, use the major version 7 (`7.x.y`) of the library.
+
+[discrete]
+=== HTTP Library
+This library uses https://github.com/elastic/elasticsearch-ruby/tree/master/elasticsearch-transport[elasticsearch-transport], the low-level Ruby client for connecting to an Elasticsearch cluster - also used in the official https://github.com/elastic/elasticsearch-ruby[Elasticsearch Ruby Client].
+
+All requests, if successful, will return an `Elasticsearch::Transport::Transport::Response` instance. You can access the response `body`, `headers` and `status`.
+
+`elasticsearch-transport` defines a https://github.com/elasticsearch/elasticsearch-ruby/blob/master/elasticsearch-transport/lib/elasticsearch/transport/transport/errors.rb[number of exception classes] for various client and server errors, as well as unsuccessful HTTP responses, making it possible to rescue specific exceptions with desired granularity. More details https://github.com/elastic/elasticsearch-ruby/tree/master/elasticsearch-transport#exception-handling[here]. You can find the full documentation for `elasticsearch-transport` at https://rubydoc.info/gems/elasticsearch-transport[RubyDoc].
+
+The clients pass different options to transport, you can check them out https://rubydoc.info/github/elastic/enterprise-search-ruby/Elastic/EnterpriseSearch/Client[on RubyDocs].
+
+[discrete]
+==== Setting the host and port
+
+If you don't specify a host and port, the client will default to `http://localhost:3002`. Otherwise pass in the `:host` parameter as a String.
+
+[discrete]
+=== Logging
+
+You can enable logging with the default logger by passing `log: true` as a parameter to the client's initializer, or pass in a Logger object with the `:logger` parameter:
+
+[source,rb]
+----------------------------
+logger = MyLogger.new
+client = Elastic::EnterpriseSearch::Client.new(logger: logger)
+----------------------------
+
+[discrete]
+=== License
+
+Licensed to Elasticsearch B.V. under one or more contributor
+license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright
+ownership. Elasticsearch B.V. licenses this file to you under
+the Apache License, Version 2.0 (the "License"); you may
+not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.

data/docs/guide/workplace-search-api.asciidoc

@@ -0,0 +1,121 @@
+[[workplace-search-api]]
+== Workplace Search API
+
+=== Documents
+
+[source,rb]
+----------------------------
+# Index Documents
+documents = [
+  { id: 'e68fbc2688f1', title: 'Frankenstein; Or, The Modern Prometheus', author: 'Mary Wollstonecraft Shelley' },
+  { id: '0682bb06af1a', title: 'Jungle Tales', author: 'Horacio Quiroga' },
+  { id: '75015d85370d', title: 'Lenguas de diamante', author: 'Juana de Ibarbourou' },
+  { id: 'c535e226aee3', title: 'Metamorphosis', author: 'Franz Kafka' }
+]
+
+response = client.index_documents(content_source_id, body: documents)
+
+# Delete Documents
+response = client.delete_documents(content_source_id, body: ['e68fbc2688f1', 'c535e226aee3'])
+----------------------------
+
+=== OAuth Authentication
+
+You need to configure the OAuth Application for Search in order to use the Workplace Search client's `search` and `create_analytics` endpoints. You need to follow the steps in https://www.elastic.co/guide/en/workplace-search/current/building-custom-search-workplace-search.html#configuring-search-oauth[Configuring the OAuth Application for Search] to retrieve the credentials: Client ID and Client Secret to request access tokens from the authentication server.
+
+[source,rb]
+----------------------------
+client = Elastic::EnterpriseSearch::WorkplaceSearch::Client.new(http_auth: <access_token>)
+
+client_id = <client_id>
+client_secret = <client_secret>
+redirect_uri = <redirect_uri>
+
+# Get the authorization URL:
+client.authorization_url(client_id, redirect_uri)
+> https://host:port/ws/oauth/authorize?response_type=code&client_id=client_id&redirect_uri=https%3A%2F%2Flocalhost%3A3002
+----------------------------
+
+Open the URL to authorize your application. Successful authorization redirects the user in accordance to the redirect URI provided (and configured for the application). The application server must now request for an access_token, which is generated by Workplace Search using the oauth/token endpoint, using the Client ID and Client Secret.
+
+[source,rb]
+----------------------------
+authorization_code = '<paste code from redirect>'
+
+access_token = client.request_access_token(client_id, client_secret, authorization_code, redirect_uri)
+
+# The access_token can now be used to issue a search request:
+client.search(body: {query: 'search query'}, access_token: access_token)
+----------------------------
+
+See https://www.elastic.co/guide/en/workplace-search/current/workplace-search-search-api.html#search-api-overview[Search API Overview] for more search parameters.
+
+=== Permissions
+
+[source,rb]
+----------------------------
+# List permissions
+client.list_permissions(content_source_id)
+
+# Get a user permissions
+response = client.user_permissions(content_source_id, { user: 'enterprise_search' })
+
+# Clear user permissions
+client.put_user_permissions(content_source_id, { permissions: [], user: 'enterpise_search' })
+
+# Add permissions to a user
+client.add_user_permissions(
+  content_source_id,
+  { permissions: ['permission1', 'permission2'], user: user }
+)
+
+# Updates user permissions
+client.put_user_permissions(content_source_id, { permissions: [], user: user })
+
+# Remove permissions from a user
+client.remove_user_permissions(
+  content_source_id,
+  { permissions: ['permission1', 'permission2'], user: user }
+)
+----------------------------
+
+=== External Identities
+
+[source,rb]
+----------------------------
+# Create external identities
+body = { user: 'elastic_user', source_user_id: 'example@elastic.co' }
+client.create_external_identity(content_source_id, body: body)
+
+# Retrieve an external identity
+client.external_identity(content_source_id, user: 'elastic_user')
+
+# List external identities
+client.list_external_identities(content_source_id)
+
+# Update external identity
+body = { source_user_id: 'example2@elastic.co' }
+client.put_external_identity(content_source_id, user: 'elastic_user', body: body)
+
+# Delete an external identity
+client.delete_external_identity(content_source_id, user: 'elastic_user')
+----------------------------
+
+=== Create Analytics Event
+
+You need to set up OAuth Authentication for analytics events.
+
+[source,rb]
+----------------------------
+body = {
+  type: 'click',
+  query_id: 'search_query_id',
+  document_id: 'document_id',
+  page: 1,
+  content_source_id: 'content_source_id',
+  rank: 1,
+  event: 'api'
+}
+
+client.create_analytics_event(access_token: oauth_access_token, body: body)
+----------------------------

data/elastic-enterprise-search.gemspec

@@ -28,15 +28,15 @@ Gem::Specification.new do |s|
   s.authors     = ['Fernando Briano']
   s.email       = ['support@elastic.co']
   s.homepage    = 'https://github.com/elastic/enterprise-search-ruby'
-  s.summary     = 'Official gem for accessing the Elastic Enterprise Search APIs'
+  s.summary     = 'Official API client for Elastic Enterprise Search'
   s.description = <<~DESCRIPTION
-    API client for accessing the Elastic Enterprise APIs. This gem is in a beta state.
+    Official API client for Elastic Enterprise Search APIs.
   DESCRIPTION
   s.licenses = ['Apache-2.0']
 
   s.metadata = {
     'bug_tracker_uri' => 'https://github.com/elastic/enterprise-search-ruby/issues',
-    'documentation_uri' => 'https://github.com/elastic/enterprise-search-ruby/blob/master/README.md',
+    'documentation_uri' => 'https://www.elastic.co/guide/en/enterprise-search-clients/ruby/current/index.html',
     'homepage_uri' => 'https://www.elastic.co/enterprise-search',
     'source_code_uri' => 'https://github.com/elastic/enterprise-search-ruby'
   }
@@ -46,7 +46,8 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
   s.require_paths = ['lib']
 
-  s.add_dependency 'elasticsearch-transport'
+  s.add_dependency 'elasticsearch-transport', '~> 7.11'
+  s.add_runtime_dependency 'jwt', '>= 1.5', '< 3.0'
   s.add_development_dependency 'awesome_print'
   s.add_development_dependency 'byebug' unless defined?(JRUBY_VERSION)
   s.add_development_dependency 'rspec', '~> 3.9.0'