elastic-enterprise-search 0.2.1 → 7.12.0

data/docs/guide/release_notes/710.asciidoc

@@ -0,0 +1,4 @@
+[[release_notes_710]]
+=== 7.10.0.beta.1 Release notes
+
+First beta release. It supports the 7.10.0 API for Elastic Enterprise Search, App Search and Workplace Search.

data/docs/guide/release_notes/711.asciidoc

@@ -0,0 +1,27 @@
+[[release_notes_711]]
+=== 7.11.0 Release notes
+
+First General Availability Release
+
+[discrete]
+==== General
+
+- All App Search, Workplace Search and Enterprise Search API endpoints have been implemented updated to the 7.11 specification, and have been tested and documented.
+- Docs were moved from the README file to asciidocs.
+- Some endpoints both in App Search and Workplace Search have changed to have named parameters for `body` when it makes sense.
+- Support for per request custom HTTP headers was added. See docs.
+- Support for per request http authentication was added when using OAuth. See docs.
+- Tested with Ruby 3.
+- Sends the `X-Elastic-Client-Meta` HTTP header which is used by Elastic Cloud and can be disabled with the `enable_meta_header` parameter.
+
+[discrete]
+==== App Search
+
+- Added support for signed search key in App Search.
+
+[discrete]
+==== Workplace Search
+
+- `content_source_key` was deprecated in favour of `content_source_id`.
+- Added support for OAuth.
+- With OAuth support, `search` and `create_analytics` APIs are now also available.

data/docs/guide/release_notes/712.asciidoc

@@ -0,0 +1,26 @@
+[[release_notes_712]]
+=== 7.12.0 Release notes
+
+[discrete]
+==== General
+
+- Tested with Elastic Enterprise Search API version 7.12.0.
+- https://www.elastic.co/guide/en/enterprise-search-clients/ruby/7.12/app-search-api.html#_search[Adds multi filter example to App Search docs].
+- Bumps `elasticsearch-transport` dependency to version 7.11 and up.
+- Updates `run-local` script to fix rake `stack` task.
+
+[discrete]
+==== App Search
+
+- Updates source code documentation for `current_page` and `page_size` parameters from type `String` to `Integer`.
+- In `multi_search`, the body parameter is renamed to `body` from `queries` to avoid repetition and potential confusion.
+
+[discrete]
+==== Workplace Search
+
+- Body parameter renamed to `document_ids` in `delete_documents`:
+
+[source,rb]
+----------------------------
+client.delete_documents(content_source_id, document_ids: ['e68fbc2688f1', 'c535e226aee3'])
+----------------------------

data/docs/guide/release_notes/index.asciidoc

@@ -0,0 +1,14 @@
+[[release_notes]]
+== Release Notes
+
+
+[discrete]
+=== 7.x
+
+* <<release_notes_712, 7.12.0 Release Notes>>
+* <<release_notes_711, 7.11.0 Release Notes>>
+* <<release_notes_710, 7.10.0.beta.1 Release Notes>>
+
+include::712.asciidoc[]
+include::711.asciidoc[]
+include::710.asciidoc[]

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, document_ids: ['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

@@ -1,23 +1,60 @@
-$:.push File.expand_path("../lib", __FILE__)
-require "elastic/enterprise-search/version"
+# 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.
 
+# frozen_string_literal: true
+
+$LOAD_PATH.push File.expand_path('lib', __dir__)
+require 'elastic/enterprise-search/version'
+
+# rubocop:disable Metrics/BlockLength
 Gem::Specification.new do |s|
-  s.name        = "elastic-enterprise-search"
+  s.required_ruby_version = '>= 2.5'
+  s.name        = 'elastic-enterprise-search'
   s.version     = Elastic::EnterpriseSearch::VERSION
-  s.authors     = ["Quin Hoxie"]
-  s.email       = ["support@elastic.co"]
-  s.homepage    = "https://github.com/elastic/enterprise-search-ruby"
-  s.summary     = %q{Official gem for accessing the Elastic Enterprise Search API}
-  s.description = %q{API client for accessing the Elastic Enterprise Search API with no dependencies.}
-  s.licenses    = ['Apache-2.0']
+  s.authors     = ['Fernando Briano']
+  s.email       = ['support@elastic.co']
+  s.homepage    = 'https://github.com/elastic/enterprise-search-ruby'
+  s.summary     = 'Official API client for Elastic Enterprise Search'
+  s.description = <<~DESCRIPTION
+    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://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',
+    'changelog_uri' => 'https://www.elastic.co/guide/en/enterprise-search-clients/ruby/current/release_notes.html'
+  }
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  s.require_paths = ["lib"]
+  s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.require_paths = ['lib']
 
-  s.add_development_dependency 'rspec', '~> 3.0.0'
+  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'
+  s.add_development_dependency 'rspec_junit_formatter'
+  s.add_development_dependency 'rubocop', '~> 1.0.0'
   s.add_development_dependency 'vcr', '~> 3.0.3'
   s.add_development_dependency 'webmock'
 end
+# rubocop:enable Metrics/BlockLength

data/lib/elastic-enterprise-search.rb

@@ -1 +1,20 @@
-require 'elastic/enterprise-search'
+# 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.
+
+# frozen_string_literal: true
+
+require 'elastic/enterprise_search'

data/lib/elastic/.rubocop.yml

@@ -0,0 +1,6 @@
+inherit_from: ../../.rubocop.yml
+
+Layout/LineLength:
+  Enabled: false
+Style/Documentation:
+  Enabled: false

data/lib/elastic/app-search/api/add_meta_engine_source.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# 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.
+
+module Elastic
+  module EnterpriseSearch
+    module AppSearch
+      module Actions
+        # Engine - Add a source engine to an existing meta engine
+        #
+        # @param engine_name [String]  (*Required*)
+        # @param arguments [Hash] endpoint arguments
+        # @option arguments [Array] :source_engines List of engine names (*Required*)
+        # @option arguments [Hash] :headers optional HTTP headers to send with the request
+        #
+        # @see https://www.elastic.co/guide/en/app-search/current/meta-engines.html#meta-engines-add-source-engines
+        #
+        def add_meta_engine_source(engine_name, arguments = {})
+          raise ArgumentError, "Required parameter 'engine_name' missing" unless engine_name
+          raise ArgumentError, "Required parameter 'source_engines' missing" unless arguments[:source_engines]
+
+          source_engines = arguments.delete(:source_engines) || {}
+          headers = arguments.delete(:headers) || {}
+
+          request(
+            :post,
+            "api/as/v1/engines/#{engine_name}/source_engines/",
+            arguments,
+            source_engines,
+            headers
+          )
+        end
+      end
+    end
+  end
+end

data/lib/elastic/app-search/api/api_logs.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# 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.
+
+module Elastic
+  module EnterpriseSearch
+    module AppSearch
+      module Actions
+        # Logs - The API Log displays API request and response data at the Engine level
+        #
+        # @param engine_name [String]  (*Required*)
+        # @param arguments [Hash] endpoint arguments
+        # @option arguments [String] :from_date Filter date from (*Required*)
+        # @option arguments [String] :to_date Filter date to (*Required*)
+        # @option arguments [Integer] :current_page The page to fetch. Defaults to 1
+        # @option arguments [Integer] :page_size The number of results per page
+        # @option arguments [String] :query Use this to specify a particular endpoint, like analytics, search, curations and so on
+        # @option arguments [String] :http_status_filter Filter based on a particular status code: 400, 401, 403, 429, 200
+        # @option arguments [String] :http_method_filter Filter based on a particular HTTP method: GET, POST, PUT, PATCH, DELETE
+        # @option arguments [String] :sort_direction Would you like to have your results ascending, oldest to newest, or descending, newest to oldest?
+        # @option arguments [Hash] :body The request body
+        # @option arguments [Hash] :headers optional HTTP headers to send with the request
+        #
+        # @see https://www.elastic.co/guide/en/app-search/current/api-logs.html
+        #
+        def api_logs(engine_name, arguments = {})
+          raise ArgumentError, "Required parameter 'from_date' missing" unless arguments[:from_date]
+          raise ArgumentError, "Required parameter 'to_date' missing" unless arguments[:to_date]
+          raise ArgumentError, "Required parameter 'engine_name' missing" unless engine_name
+
+          body = arguments.delete(:body) || {}
+          headers = arguments.delete(:headers) || {}
+          arguments['filters[date][from]'] = date_to_rfc3339(arguments.delete(:from_date))
+          arguments['filters[date][to]'] = date_to_rfc3339(arguments.delete(:to_date))
+
+          request(
+            :get,
+            "api/as/v1/engines/#{engine_name}/logs/api/",
+            arguments,
+            body,
+            headers
+          )
+        end
+      end
+    end
+  end
+end

data/lib/elastic/app-search/api/count_analytics.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# 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.
+
+module Elastic
+  module EnterpriseSearch
+    module AppSearch
+      module Actions
+        # Analytics - Returns the number of clicks and total number of queries over a period
+        #
+        # @param engine_name [String]  (*Required*)
+        # @param arguments [Hash] endpoint arguments
+        # @option arguments [Array] :filters Analytics filters
+        # @option arguments [String] :interval You can define an interval along with your date range. Can be either hour or day
+        # @option arguments [Hash] :body The request body
+        # @option arguments [Hash] :headers optional HTTP headers to send with the request
+        #
+        # @see https://www.elastic.co/guide/en/app-search/current/counts.html
+        #
+        def count_analytics(engine_name, arguments = {})
+          raise ArgumentError, "Required parameter 'engine_name' missing" unless engine_name
+
+          body = arguments.delete(:body) || {}
+          headers = arguments.delete(:headers) || {}
+
+          request(
+            :get,
+            "api/as/v1/engines/#{engine_name}/analytics/counts/",
+            arguments,
+            body,
+            headers
+          )
+        end
+      end
+    end
+  end
+end