Skip to content

Latest commit

 

History

History
619 lines (519 loc) · 13.4 KB

workplace-search-api.asciidoc

File metadata and controls

619 lines (519 loc) · 13.4 KB

Workplace Search APIs

On this page

Initializing the Client

The WorkplaceSearch client can either be configured directly:

# Use the Workplace client directly:
from elastic_enterprise_search import WorkplaceSearch

workplace_search = WorkplaceSearch(
    "http://localhost:3002"
)
# Now call API methods
workplace_search.search(..., http_auth="<oauth-access-token>")

…​or can be used via a configured EnterpriseSearch.workplace_search instance:

from elastic_enterprise_search import EnterpriseSearch

ent_search = EnterpriseSearch("http://localhost:3002")

# Now call API methods
ent_search.workplace_search.search(..., http_auth="<oauth-access-token>")

Document APIs

To ingest documents into Workplace Search with the API you must first create a Custom Content Source and get the Content Source ID and Content Source Access Token.

In the examples below assume that CONTENT_SOURCE_ID is the Content Source ID and CONTENT_SOURCE_ACCESS_TOKEN is the Content Source Access Token from above.

Create or update Documents

To create new documents or update existing documents use the index_documents() method.

The _allow_permissions and _deny_permissions properties can be used to control visibility of the documents for users. See the Permissions section below for more information on Permissions.

# Request:
workplace_search.index_documents(
    http_auth="<CONTENT_SOURCE_ACCESS_TOKEN>",
    content_source_id="<CONTENT_SOURCE_ID>",
    documents=[
      {
        "_allow_permissions": ["permission1"],
        "_deny_permissions": [],
        "id" : 1234,
        "title" : "The Meaning of Time",
        "body" : "Not much. It is a made up thing.",
        "url" : "https://example.com/meaning/of/time",
        "created_at": "2019-06-01T12:00:00+00:00",
        "type": "list"
      },
      {
        "_allow_permissions": [],
        "_deny_permissions": ["permission2"],
        "id" : 1235,
        "title" : "The Meaning of Sleep",
        "body" : "Rest, recharge, and connect to the Ether.",
        "url" : "https://example.com/meaning/of/sleep",
        "created_at": "2019-06-01T12:00:00+00:00",
        "type": "list"
      }
    ]
)

# Response:
{
  "results": [
    {
       "id":"1234",
       "errors":[]
    },
    {
       "id":"1235",
       "errors":[]
    }
  ]
}

Get Document

To get a single document by ID use the get_document() method:

# Request:
workplace_search.get_document(
    content_source_id="<CONTENT_SOURCE_ID>",
    document_id="<DOCUMENT_ID>"
)

# Response:
{
  "id":  "<DOCUMENT_ID>",
  "source": "custom",
  "content_source_id": "<CONTENT_SOURCE_ID>",
  "last_updated": "2021-03-02T22:41:16+00:00",
  "text_field": "some text value",
  "number_field": 42,
  "date_field": "2021-03-02T22:41:16+00:00",
  "geolocation_field": "44.35,-68.21",
  "_allow_permissions": ["perm1", "perm2"],
  "_deny_permissions": ["perm3", "perm4"]
}

List Documents

List documents inside a Content Source

# Request:
workplace_search.list_documents(
    content_source_id="<CONTENT_SOURCE_ID>"
)

# Response:
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 2,
      "size": 10
    },
    "warnings": [],
    "cursor": {
      "current": null,
      "next": "eyJzb3J0Ijp7Il9zY29yZSI6ImRlc2MifSwic2VhcmNoX2FmdGVyIjpbMS4wLCJkb2MtNjFiY2VkNjQ1MzU5OTEyMjlmNTM1MWEzIl19"
    }
  },
  "results": [
    {
      "last_updated": "2021-12-17T20:04:37+00:00",
      "updated_at": "2021-12-17T20:04:37+00:00",
      "content_source_id": "61bced325359912c2f5351a0",
      "source": "custom",
      "id": "doc-61bced5553599152f25351a2"
    },
    ...
  ]
}

Delete documents

To remove documents from a custom content source use the delete_documents() method and supply a list of document IDs to body:

# Request:
workplace_search.delete_documents(
    http_auth="<CONTENT_SOURCE_ACCESS_TOKEN>",
    content_source_id="<CONTENT_SOURCE_ID>",
    document_ids=[1234, 1235]
)

# Response:
{
  "results": [
    {
      "id": 1234,
      "success": True
    },
    {
      "id": 1235,
      "success": True
    }
  ]
}

Delete documents by Query

Deletes documents that match a query or filters

# Request
workplace_search.delete_documents_by_query(
    content_source_id="<CONTENT_SOURCE_ID>",
    filters={
        "last_updated_at": {
            "from": "2020-06-01T12:00:00+00:00"
        }
    }
)

# Response
{"total": 100, "deleted": 100, "failures": []}

Delete all documents

Deletes all the documents in a Content Source

workplace_search.delete_documents_by_query(
    content_source_id="<CONTENT_SOURCE_ID>"
)

Content Source APIs

Create Content Source

workplace_search.create_content_source(
    name="Content Source Name",
    schema={
        "title": "text",
        "body": "text",
        "url": "text"
    },
    display={
        "title_field": "title",
        "url_field": "url",
        "color": "#f00f00"
    },
    is_searchable=True
)

Get Content Source

workplace_search.get_content_source(
    content_source_id="<CONTENT_SOURCE_ID>"
)

List Content Sources

# Request:
workplace_search.list_content_sources()

# Response:
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 4,
      "size": 25
    }
  },
  "results": [
    { <CONTENT SOURCE> },
    ...
  ]
}

Update Content Source

workplace_search.put_content_source(
    content_source_id="<CONTENT_SOURCE_ID>",
    name="Content Source Name",
    schema={
        "title": "text",
        "body": "text",
        "url": "text"
    },
    display={
        "title_field": "title",
        "url_field": "url",
        "color": "#f00f00"
    },
    is_searchable=True
)

Delete Content Source

workplace_search.delete_content_source(
    content_source_id="<CONTENT_SOURCE_ID>"
)

Upload Content Source Icons

The data for the Content Source icons must be a PNG that is encoded in base64.

import base64

# Read 'main-icon.png' and 'alt-icon.png' and base64-encode the data
with open("main-icon.png", "rb") as f:
    main_icon = base64.b64encode(f.read()).decode()
with open("alt-icon.png", "rb") as f:
    alt_icon = base64.b64encode(f.read()).decode()

workplace_search.put_content_source_icon(
    content_source_id="<CONTENT_SOURCE_ID>",
    main_icon=main_icon,
    # This icon is optional, if not provided 'main_icon' will be used.
    alt_icon=alt_icon
)

Search APIs

Search requires an OAuth access token in the http_auth parameter to authenticate.

# Request:
workplace_search.search(
    query="sleep"
)

# Response:
{
  "meta": {
    ...
  },
  "results": [
    {
      "title": {
        "raw": "The Meaning of Sleep",
        "snippet": "The Meaning of <em>Sleep</em>",
      },
      "_meta": {
        "source": "custom-source",
        "last_updated": "2020-03-27T20:10:33+00:00",
        "content_source_id": "<CONTENT_SOURCE_ID>",
        "id": "1235",
        "score": 6.359234
      },
      "source": {
        "raw": "custom-source"
      },
      "content_source_id": {
        "raw": "<CONTENT_SOURCE_ID>"
      },
      "id": {
        "raw": "park_american-samoa"
      },
      ...
    },
    ...
  ]
}

Permissions APIs

Permissions can be set per-user and then applied to documents either by _allow_permissions or _deny_permissions to control access to documents.

Get User Permissions

To view a users permissions use the get_permissions() method:

# Request:
workplace_search.get_user_permissions(
    content_source_id="<CONTENT_SOURCE_ID>",
    http_auth="<CONTENT_SOURCE_ACCESS_TOKEN>",
    user="example.user"
)

# Response:
{
 "user": "example.user",
 "permissions": [
   "permission1",
   "permission2"
 ]
}

Listing Permissions for Content Source

To view all users permissions for a custom content source use the list_permissions() method:

# Request:
workplace_search.options(
  bearer_auth="<CONTENT_SOURCE_ACCESS_TOKEN>"
).list_permissions(
    content_source_id="<CONTENT_SOURCE_ID>"
)

# Response:
[
  {
   "user": "example.user",
   "permissions": [
     "permission1",
     "permission2"
   ]
  }
]

Get current User

Gets the currently authenticated user

# Request
workplace_search.get_current_user()

# Response
{"email": "email@example.com", "username": "example"}

Synonyms APIs

Create Synonym Set

# Request
workplace_search.create_batch_synonym_sets(
    synonym_sets=[
        {"synonyms": ["house", "home", "abode"]},
        {"synonyms": ["cat", "feline", "kitty"]}
    ]
)

# Response
{
    "has_errors": True,
    "synonym_sets": [
        {
            "synonyms": ["house","home","abode"],
            "errors": [
                "Duplicate terms - the following terms already exist in an existing synonym set: house, home"
            ]
        },
        {"id": "<ID>", "synonyms": ["cat","feline","kitty"]}
    ]
}

Get Synonym Set

# Request
workplace_search.get_synonym_set(
    synonym_set_id="<ID>"
)

# Response
{
    "id": "<ID>",
    "synonyms": ["house","home","abode"],
    "created_at": "2021-01-02T10:00:00Z",
    "updated_at": "2021-04-22T00:00:05Z"
}

List Synonym Sets

# Request
workplace_search.list_synonym_sets(
    filter={
        "terms": ["home"]
    }
)

# Response
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 10,
      "size": 25
    },
    "filter": { "terms": ["house", "books"] },
    "sort": {
      { "updated_at": "desc" },
      { "created_at": "asc" }
    }
  },
  "results": [
    {
        "id": "<ID>",
        "synonyms": ["house","home","abode"],
        "created_at": "2021-01-02T10:00:00Z",
        "updated_at": "2021-04-22T00:00:05Z"
    }, ...
  ]
}

Delete Synonym Set

workplace_search.delete_synonym_set(
    synonym_set_id="<ID>"
)

Update Synonym Set

workplace_search.put_synonym_set(
    synonym_set_id="<ID>",
    synonyms=["mouses", "mice", "rat"]
)

OAuth Applications with Workplace Search

Workplace Search supports creating an OAuth Application and authenticating users via OAuth. The Workplace Search Python client has helper methods that make using OAuth easier.

The below example uses the recommended Confidential Flow and assumes an OAuth application has already been created and the values for Client ID, Client Secret, and Redirect URI have been gathered:

from elastic_enterprise_search import WorkplaceSearch

workplace_search = WorkplaceSearch(
    "https://<...>.ent-search.us-central1.gcp.cloud.es.io"
)
url = workplace_search.oauth_authorize_url(
    response_type="code",
    client_id="<client_id>",
    redirect_uri="<redirect_uri>"
)
# Redirect user via HTTP redirect with 'Location: <url>'

# ...When user is redirected back to <redirect_uri>
# get the '?code=...' from the request query parameters:
code = "<code>"

# Exchange the 'code' for an 'access_token':
resp = workplace_search.oauth_exchange_for_access_token(
    client_id="<client_id>",
    client_secret="<client_secret>",
    redirect_uri="<redirect_uri>",
    code=code
)

# Store these values somewhere for this user:
access_token = resp["access_token"]
refresh_token = resp["refresh_token"]

# Use the 'access_token' to make search requests
results = workplace_search.options(bearer_auth=access_token).search(
    query="Things I want to find"
)

# When the access token eventually expires, use the
# 'refresh_token' to get a new access token:
resp = workplace_search.oauth_exchange_for_access_token(
    client_id="<client_id>",
    client_secret="<client_secret>",
    redirect_uri="<redirect_uri>",
    refresh_token=refresh_token
)

# Update the stored values with new ones:
access_token = resp["access_token"]
refresh_token = resp["refresh_token"]