IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« App Search APIs Enterprise Search APIs »

›

Workplace Search APIs

edit

Workplace Search APIs

edit

On this page

Initializing the Client

edit

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

edit

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

edit

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":[]
    }
  ]
}

Delete Documents

edit

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
    }
  ]
}

Search APIs

edit

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

# Request:
workplace_search.search(
    body={
        "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

edit

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

Add Permission to User

edit

To add permissions to a user example.user use the add_user_permissions() method:

# Request:
workplace_search.add_user_permissions(
    content_source_id="<CONTENT_SOURCE_ID>",
    http_auth="<CONTENT_SOURCE_ACCESS_TOKEN>",
    user="example.user",
    body={
        "permissions": ["permission1", "permission2"]
    }
)

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

Get User Permissions

edit

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

edit

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

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

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

Remove Permissions from User

edit

To remove one or more permissions from a user use the delete_user_permissions() method:

# Request:
workplace_search.delete_user_permissions(
    content_source_id="<CONTENT_SOURCE_ID>",
    http_auth="<CONTENT_SOURCE_ACCESS_TOKEN>",
    user="example.user",
    body={
        "permissions": ["permission2"]
    }
)

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

« App Search APIs Enterprise Search APIs »