elastic-enterprise-search 7.12.1 → 7.13.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cc91758d4ef25ab3d509996223bf7c7cb07352e81f5f450fccadf8e0d799a4b
-  data.tar.gz: 646f6a1cb4295263a1dc3ee07441aa8c5bfe20b1692e5f0d970d31a2a14a41c4
+  metadata.gz: 8036e7cf6cee2aa2a4bd8ebe43e8ebd81e46de9849dd785c1185e865cd197a6d
+  data.tar.gz: 0dc716523605727f80cf992537ace657ba4152db79e8b7df08a077d77c40f623
 SHA512:
-  metadata.gz: bddacbdbf0df0b8fe15197e4b3a016743dc7a79854d1de1bc9b5216c6297051808d905daae04c7d1da949840f971b4ad65dfc95b258db063a985380eaa66109c
-  data.tar.gz: 45e7a164a0ee32daa8968b87690c27eead9b3de83e5ae4e72fb7a9d6a496cd2fa4ec24dd696f666ac581c19d541e4cc978423f0b888f6611329b8c351b9408ed
+  metadata.gz: 2a46a41e600dbae30c4f24ff5a76b766ce68ae54d4c322e94c5eb312a1e0ee4bbf55df7bbea572656285078cc3a177b35bd4d8619d3cd706db7500f91ac71c72
+  data.tar.gz: d825c1dccff5af252f2eaba9dd2f84ef47594fbe8e3992a1255433179f44e32d4318a91dc495871d889a273456ef7cf6663184fc2a8f03f32658e560d253a159

data/.ci/jobs/elastic+enterprise-search-ruby+7.10.0.beta.1.yml

@@ -0,0 +1,12 @@
+---
+- job:
+    name: elastic+enterprise-search-ruby+7.10.0.beta.1
+    display-name: 'elastic / enterprise-search-ruby # 7.10.0.beta.1'
+    description: Testing the enterprise-search-ruby 7.10.0.beta.1 branch.
+    junit_results: "*-junit.xml"
+    parameters:
+    - string:
+        name: branch_specifier
+        default: refs/heads/7.10.0.beta.1
+        description: the Git branch specifier to build (<branchName>, <tagName>,
+          <commitId>, etc.)

data/.ci/test-matrix.yml

@@ -6,7 +6,7 @@ RUBY_VERSION:
   - 2.5
 
 STACK_VERSION:
-  - 7.12-SNAPSHOT
+  - 7.13-SNAPSHOT
 
 TEST_SUITE:
   - platinum

data/docs/guide/connecting.asciidoc

@@ -87,7 +87,13 @@ client.search(engine_name, query: 'jungle')
 [[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.
+Workplace Search supports multiple authentication methods:
+
+[discrete]
+[[access-tokens]]
+===== Workplace Search admin user access tokens
+
+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`.
 
 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:
 
@@ -109,6 +115,46 @@ workplace_search_client = Elastic::EnterpriseSearch::WorkplaceSearch::Client.new
 )
 ----------------------------
 
+[discrete]
+[[basic-auth]]
+===== Basic Authentication
+
+Workplace Search APIs support basic authentication headers to authenticate users. All Workplace Search APIs support basic authentication:
+
+[source,rb]
+----------------------------
+host = 'https://id.ent-search.europe-west2.gcp.elastic-cloud.com'
+basic_auth = { user: 'enterprise_search', password: 'changeme' }
+
+workplace_search_client = Elastic::EnterpriseSearch::WorkplaceSearch::Client.new(
+  host: host,
+  http_auth: basic_auth
+)
+----------------------------
+
+[discrete]
+[[es-tokens]]
+===== Elasticsearch tokens
+
+Workplace Search APIs support Elasticsearch tokens generated by the Elasticsearch Token Service. All Workplace Search APIs support Elasticsearch tokens as an authentication method.
+
+[source,rb]
+----------------------------
+host = 'https://id.ent-search.europe-west2.gcp.elastic-cloud.com'
+access_token = '<access token>'
+
+workplace_search_client = Elastic::EnterpriseSearch::WorkplaceSearch::Client.new(
+  host: host,
+  http_auth: access_token
+)
+----------------------------
+
+[discrete]
+[[ws-oauth]]
+===== Workplace Search OAuth access tokens
+
+The Search API and the Analytics Events API support user access tokens generated by the Workplace Search OAuth Service. The token is acquired via an OAuth authorization flow. User access tokens are meant to be used for Custom Search Experiences. Check <<ws-oauth-authentication>>.
+
 [discrete]
 [[custom_headers]]
 === Custom HTTP Headers

data/docs/guide/release_notes/712.asciidoc

@@ -1,18 +1,6 @@
 [[release_notes_712]]
-=== 7.12 Release notes
-
-[discrete]
-[[release_notes_7121]]
-=== 7.12.1 Release notes
-
-- Elastic Transport: Locks dependency version to < 7.14
-- Elastic Transport: Adds ENTERPRISE_SERVICE_VERSION constant for compatibility
-
-[discrete]
-[[release_notes_7120]]
 === 7.12.0 Release notes
 
-
 [discrete]
 ==== General
 
@@ -26,13 +14,3 @@
 
 - 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/workplace-search-api.asciidoc

@@ -15,10 +15,18 @@ documents = [
 
 response = client.index_documents(content_source_id, body: documents)
 
+# Retrieve a document by ID from a specified content source
+client.document(content_source_id, document_id: '75015d85370d')
+
 # Delete Documents
-response = client.delete_documents(content_source_id, document_ids: ['e68fbc2688f1', 'c535e226aee3'])
+client.delete_documents(content_source_id, document_ids: ['e68fbc2688f1', 'c535e226aee3'])
+
+# Delete all documents for a given content source
+client.delete_all_documents(content_source_id)
 ----------------------------
 
+[discrete]
+[[ws-oauth-authentication]]
 === 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.
@@ -101,9 +109,18 @@ client.put_external_identity(content_source_id, user: 'elastic_user', body: body
 client.delete_external_identity(content_source_id, user: 'elastic_user')
 ----------------------------
 
+=== Search
+
+You need to set up <<ws-oauth-authentication>> and use the access token for Search. See https://www.elastic.co/guide/en/workplace-search/current/workplace-search-search-api.html[Search API Reference] for available parameters and more details about search.
+
+[source,rb]
+----------------------------
+client.search(body: {query: 'search query'}, access_token: access_token)
+----------------------------
+
 === Create Analytics Event
 
-You need to set up OAuth Authentication for analytics events.
+You need to set up <<ws-oauth-authentication>> to use analytics events.
 
 [source,rb]
 ----------------------------

data/elastic-enterprise-search.gemspec

@@ -47,7 +47,7 @@ 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', '>= 7.11', '< 7.14'
+  s.add_dependency 'elasticsearch-transport', '7.13.0.pre'
   s.add_runtime_dependency 'jwt', '>= 1.5', '< 3.0'
   s.add_development_dependency 'awesome_print'
   s.add_development_dependency 'byebug' unless defined?(JRUBY_VERSION)

data/lib/elastic/enterprise-search/api/put_read_only.rb

@@ -23,6 +23,8 @@ module Elastic
       # Read-Only - Update the read-only flag's state
       # Update the read-only flag's state
       #
+      # @option arguments [Object] :body
+      # @option body [Boolean] :enabled
       # @option arguments [Hash] :headers optional HTTP headers to send with the request
       #
       # @see https://www.elastic.co/guide/en/enterprise-search/current/read-only-api.html#setting-read-only-state

data/lib/elastic/enterprise-search/client.rb

@@ -22,18 +22,6 @@ require 'elastic/enterprise-search/utils'
 require 'elasticsearch-transport'
 
 module Elastic
-  # If the version is X.X.X.pre/alpha/beta, use X.X.Xp for the meta-header:
-  def self.client_meta_version
-    regexp = /^([0-9]+\.[0-9]+\.[0-9]+)\.?([a-z0-9.-]+)?$/
-    match = Elastic::EnterpriseSearch::VERSION.match(regexp)
-    return "#{match[1]}p" if match[2]
-
-    Elastic::EnterpriseSearch::VERSION
-  end
-
-  META_HEADER_SERVICE_VERSION = [:ent, client_meta_version].freeze
-  ENTERPRISE_SERVICE_VERSION = [:ent, client_meta_version].freeze
-
   module EnterpriseSearch
     # API client for the {Elastic Enterprise Search API}[https://www.elastic.co/enterprise-search].
     # This is the main client from which the Workplace Search and App Search clients inherit.

data/lib/elastic/enterprise-search/request.rb

@@ -60,6 +60,10 @@ module Elastic
       end
 
       def setup_authentication_header
+        basic_auth_header
+      end
+
+      def basic_auth_header
         credentials = Base64.strict_encode64("#{http_auth[:user]}:#{http_auth[:password]}")
         "Basic #{credentials}"
       end

data/lib/elastic/enterprise-search/version.rb

@@ -19,6 +19,6 @@
 
 module Elastic
   module EnterpriseSearch
-    VERSION = '7.12.1'
+    VERSION = '7.13.0.pre'
   end
 end

data/lib/elastic/enterprise_search.rb

@@ -33,6 +33,17 @@ require 'elastic/workplace-search/workplace_search'
 require 'elastic/app-search/app_search'
 
 module Elastic
+  # If the version is X.X.X.pre/alpha/beta, use X.X.Xp for the meta-header:
+  def self.client_meta_version
+    regexp = /^([0-9]+\.[0-9]+\.[0-9]+)\.?([a-z0-9.-]+)?$/
+    match = Elastic::EnterpriseSearch::VERSION.match(regexp)
+    return "#{match[1]}p" if match[2]
+
+    Elastic::EnterpriseSearch::VERSION
+  end
+
+  ENTERPRISE_SERVICE_VERSION = [:ent, client_meta_version].freeze
+
   module EnterpriseSearch
   end
 end

data/lib/elastic/workplace-search/api/content_source.rb

@@ -0,0 +1,49 @@
+# 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 WorkplaceSearch
+      module Actions
+        # ContentSources - Retrieves a content source by ID
+        # Retrieves a content source by ID
+        #
+        # @param content_source_id [String] Unique ID for a Custom API source, provided upon creation of a Custom API Source (*Required*)
+        # @param arguments [Hash] endpoint arguments
+        # @option arguments [Hash] :headers optional HTTP headers to send with the request
+        #
+        # @see https://www.elastic.co/guide/en/workplace-search/current/workplace-search-content-sources-api.html#get-content-source-api
+        #
+        def content_source(content_source_id, arguments = {})
+          raise ArgumentError, "Required parameter 'content_source_id' missing" unless content_source_id
+
+          headers = arguments.delete(:headers) || {}
+
+          request(
+            :get,
+            "api/ws/v1/sources/#{content_source_id}/",
+            arguments,
+            {},
+            headers
+          )
+        end
+      end
+    end
+  end
+end

data/lib/elastic/workplace-search/api/create_analytics_event.rb

@@ -22,11 +22,11 @@ module Elastic
     module WorkplaceSearch
       module Actions
         # Analytics - Capture click and feedback analytic events
-        # Capture Analytic Events
+        # Capture Analytic events for click and feedback
         #
         # @param arguments [Hash] endpoint arguments
         # @option arguments [String] :access_token OAuth Access Token (*Required*)
-        # @option arguments [Object] :body
+        # @option arguments [Object] :body Workplace Search analytics event (Required: type, query_id, page, content_source_id, document_id, rank)
         # @option body [String] :type
         # @option body [String] :query_id query identifier for the event
         # @option body [Integer] :page page number of the document in the query result set

data/lib/elastic/workplace-search/api/create_content_source.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 WorkplaceSearch
+      module Actions
+        # ContentSources - Create a content source
+        # Create a custom content source
+        #
+        # @param arguments [Hash] endpoint arguments
+        # @option arguments [Object] :body Definition to create a Workplace Search Content Source (Required: name)
+        # @option body [String] :name The human readable display name for this Content Source.
+        # @option body :schema The schema that each document in this Content Source will adhere to.
+        # @option body :display The display details which governs which fields will be displayed, and in what order, in the search results.
+        # @option body [Boolean] :is_searchable Whether or not this Content Source will be searchable on the search page.
+        # @option arguments [Hash] :headers optional HTTP headers to send with the request
+        #
+        # @see https://www.elastic.co/guide/en/workplace-search/current/workplace-search-content-sources-api.html#create-content-source-api
+        #
+        def create_content_source(arguments = {})
+          body = arguments.delete(:body) || {}
+          headers = arguments.delete(:headers) || {}
+
+          request(
+            :post,
+            'api/ws/v1/sources/',
+            arguments,
+            body,
+            headers
+          )
+        end
+      end
+    end
+  end
+end

data/lib/elastic/workplace-search/api/create_external_identity.rb

@@ -27,6 +27,8 @@ module Elastic
         # @param content_source_id [String] Unique ID for a Custom API source, provided upon creation of a Custom API Source (*Required*)
         # @param arguments [Hash] endpoint arguments
         # @option arguments [Object] :body  (Required: source_user_id, user)
+        # @option body [String] :source_user_id
+        # @option body [String] :user
         # @option arguments [Hash] :headers optional HTTP headers to send with the request
         #
         # @see https://www.elastic.co/guide/en/workplace-search/current/workplace-search-external-identities-api.html#add-external-identity

data/lib/elastic/workplace-search/api/delete_all_documents.rb

@@ -0,0 +1,49 @@
+# 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 WorkplaceSearch
+      module Actions
+        # Documents - Deletes all documents in a custom content source
+        # Deletes all documents in a custom content source
+        #
+        # @param content_source_id [String] Unique ID for a Custom API source, provided upon creation of a Custom API Source (*Required*)
+        # @param arguments [Hash] endpoint arguments
+        # @option arguments [Hash] :headers optional HTTP headers to send with the request
+        #
+        # @see https://www.elastic.co/guide/en/workplace-search/current/workplace-search-custom-sources-api.html#delete-all-documents
+        #
+        def delete_all_documents(content_source_id, arguments = {})
+          raise ArgumentError, "Required parameter 'content_source_id' missing" unless content_source_id
+
+          headers = arguments.delete(:headers) || {}
+
+          request(
+            :delete,
+            "api/ws/v1/sources/#{content_source_id}/documents/",
+            arguments,
+            {},
+            headers
+          )
+        end
+      end
+    end
+  end
+end

data/lib/elastic/workplace-search/api/delete_content_source.rb

@@ -0,0 +1,49 @@
+# 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 WorkplaceSearch
+      module Actions
+        # ContentSources - Deletes a content source by ID
+        # Deletes a content source by ID
+        #
+        # @param content_source_id [String] Unique ID for a Custom API source, provided upon creation of a Custom API Source (*Required*)
+        # @param arguments [Hash] endpoint arguments
+        # @option arguments [Hash] :headers optional HTTP headers to send with the request
+        #
+        # @see https://www.elastic.co/guide/en/workplace-search/current/workplace-search-content-sources-api.html#remove-content-source-api
+        #
+        def delete_content_source(content_source_id, arguments = {})
+          raise ArgumentError, "Required parameter 'content_source_id' missing" unless content_source_id
+
+          headers = arguments.delete(:headers) || {}
+
+          request(
+            :delete,
+            "api/ws/v1/sources/#{content_source_id}/",
+            arguments,
+            {},
+            headers
+          )
+        end
+      end
+    end
+  end
+end