Workplace Search API
editWorkplace Search API
editContent Sources
edit# Create a custom content source client.create_content_source(body: { name: 'test' }) # Retrieve a content source by ID content_source_id = client.create_content_source(body: { name: 'books' }).body['id'] client.content_source(content_source_id) # Delete a content source by ID client.delete_content_source(content_source_id) # Retrieve all content sources client.list_content_sources # Update a custom content source body = { name: new_name, schema: { title: 'text', body: 'text', url: 'text' }, display: { title_field: 'title', url_field: 'url', color: '#f00f00' }, is_searchable: true } client.put_content_source(id, body: body) # Issue commands to a Content Source's sync jobs client.command_sync_jobs(content_source_id, body: { command: 'interrupt' }) # Update a content source icon # You need to encode the file with Base64: require 'base64' path = File.expand_path("#{File.dirname(__FILE__)}/icon.png") icon = Base64.strict_encode64(File.read(path)) response = client.put_content_source_icons(content_source_id, main_icon: icon, alt_icon: icon) # Retrieves a content source's automatic query refinement details client.auto_query_refinement_details(content_source_id)
Documents
edit# 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) # Retrieve a document by ID from a specified content source client.document(content_source_id, document_id: '75015d85370d') # List documents from a custom content source client.list_documents(content_source_id) # Delete Documents 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) # Delete documents by query client.delete_documents_by_query(content_source_id, query: query)
OAuth Authentication
editYou 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 Configuring the OAuth Application for Search to retrieve the credentials: Client ID and Client Secret to request access tokens from the authentication server.
The client implements Authenticating Users with a Confidential OAuth Flow. It provides a helper to obtain the autorization URL directly from the client once you’ve set the necessary values.
The authorization endpoint is hosted by your Kibana deployment, so you need to provide the client with the base URL of your Kibana instance. You can do this when you initialize the client:
client = Elastic::EnterpriseSearch::WorkplaceSearch::Client.new(http_auth: <access_token>, kibana_url: <kibana_url>)
Or you can set in an existing client:
client = Elastic::EnterpriseSearch::WorkplaceSearch::Client.new(http_auth: <access_token>) client.kibana_url = <kibana_url>
Once you’ve instantiated a client and the base URL of your Kibana instance is set, you can get the URL for authorization like so:
# You get the values for client_id and client_secret when configuring the OAuth Application: client_id = <client_id> client_secret = <client_secret> redirect_uri = <redirect_uri> # Get the authorization URL: client.authorization_url(client_id, redirect_uri) > https://kibana_url/app/enterprise_search/workplace_search/p/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.
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 Search API Overview for more search parameters.
Permissions
edit# 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
edit# Create external identities body = { external_user_id: external_user_id, permissions: [], external_user_properties: [ 'attribute_name' => '_elasticsearch_username', 'attribute_value' => 'fernando' ] } client.create_external_identity(content_source_id, body: body) # Retrieve an external identity client.external_identity(content_source_id, external_user_id: external_user_id) # List external identities client.list_external_identities(content_source_id) # Update external identity body = { external_user_id: external_user_id, permissions: ['permission1'] } client.put_external_identity(content_source_id, external_user_id: external_user_id, body: body) # Delete an external identity client.delete_external_identity(content_source_id, external_user_id: external_user_id)
Search
editYou need to set up OAuth Authentication and use the access token for Search. See Search API Reference for available parameters and more details about search.
client.search(body: {query: 'search query'}, access_token: access_token)
Create Analytics Event
editYou need to set up OAuth Authentication to use analytics events.
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)
Synonym Sets
editbody = { synonym_sets: [ { 'synonyms' => ['house', 'home', 'abode'] }, { 'synonyms' => ['cat', 'feline', 'kitty'] }, { 'synonyms' => ['mouses', 'mice'] } ] } # Create batch synonym set client.create_batch_synonym_sets(body: body) # Delete synonym set client.delete_synonym_set(synonym_set_id: id) # List synonym sets client.list_synonym_sets # Get a synonym set client.synonym_set(synonym_set_id: id) # Update a synonym set body = { synonyms: ['mouses', 'mice', 'luch'] } client.put_synonym_set(synonym_set_id: id, body: body)
Current User
edit# Get the current user client.current_user # Get the current user and return the access token client.current_user(get_token: true)
Triggers Blocklist
edit# Get current triggers blocklist client.triggers_blocklist # Update current triggers blocklist client.put_triggers_blocklist(body: { blocklist: ['in', 'it', 'page'] })