def get_health(
self,
params=None,
headers=None,
http_auth=DEFAULT,
request_timeout=DEFAULT,
ignore_status=(),
):
"""
Get information on the health of a deployment and basic statistics around
resource usage
`<https://www.elastic.co/guide/en/enterprise-search/current/monitoring-apis.html#health-api-example>`_
:arg params: Additional query params to send with the request
:arg headers: Additional headers to send with the request
:arg http_auth: Access token or HTTP basic auth username
and password to send with the request
:arg request_timeout: Timeout in seconds
:arg ignore_status: HTTP status codes to not raise an error
:raises elastic_enterprise_search.UnauthorizedError:
"""
params = QueryParams(params)
return self.perform_request(
"GET",
"/api/ent/v1/internal/health",
params=params,
headers=headers,
http_auth=http_auth,
request_timeout=request_timeout,
ignore_status=ignore_status,
)
def get_read_only(
self,
params=None,
headers=None,
http_auth=DEFAULT,
request_timeout=DEFAULT,
ignore_status=(),
):
"""
Get the read-only flag's state
`<https://www.elastic.co/guide/en/enterprise-search/current/read-only-api.html#getting-read-only-state>`_
:arg params: Additional query params to send with the request
:arg headers: Additional headers to send with the request
:arg http_auth: Access token or HTTP basic auth username
and password to send with the request
:arg request_timeout: Timeout in seconds
:arg ignore_status: HTTP status codes to not raise an error
:raises elastic_enterprise_search.UnauthorizedError:
"""
params = QueryParams(params)
return self.perform_request(
"GET",
"/api/ent/v1/internal/read_only_mode",
params=params,
headers=headers,
http_auth=http_auth,
request_timeout=request_timeout,
ignore_status=ignore_status,
)
def test_to_params():
params = QueryParams(
[
("a", 1),
("b", u"z"),
("c", ["d", 2]),
("e", datetime.date(year=2020, month=1, day=1)),
(
"f",
datetime.datetime(
year=2020,
month=2,
day=3,
hour=4,
minute=5,
second=6,
microsecond=7,
tzinfo=tz.gettz("HST"),
),
),
("g", (True, False)),
("h", b"hello-world"),
("i", None),
("z", "[]1234567890-_~. `=!@#$%^&*()+;'{}:,<>?/\\\""),
]
)
assert _utils.default_params_encoder(params) == (
"a=1&b=z&c=d,2&e=2020-01-01&f=2020-02-03T04:05:06-10:00&"
"g=true,false&h=hello-world&i&z=[]1234567890-_~."
"%20%60%3D%21%40%23%24%25%5E%26*%28%29%2B%3B%27%7B%7D:,%3C%3E%3F%2F%5C%22"
)
def get_version(
self,
params=None,
headers=None,
http_auth=DEFAULT,
request_timeout=DEFAULT,
ignore_status=(),
):
"""
Get version information for this server
`<https://www.elastic.co/guide/en/enterprise-search/current/management-apis.html>`_
:arg params: Additional query params to send with the request
:arg headers: Additional headers to send with the request
:arg http_auth: Access token or HTTP basic auth username
and password to send with the request
:arg request_timeout: Timeout in seconds
:arg ignore_status: HTTP status codes to not raise an error
:raises elastic_enterprise_search.UnauthorizedError:
"""
params = QueryParams(params)
return self.perform_request(
"GET",
"/api/ent/v1/internal/version",
params=params,
headers=headers,
http_auth=http_auth,
request_timeout=request_timeout,
ignore_status=ignore_status,
)
def add_user_permissions(
self,
content_source_id,
user,
body,
params=None,
headers=None,
http_auth=DEFAULT,
request_timeout=DEFAULT,
ignore_status=(),
):
"""
Adds one or more new permissions atop existing permissions
`<https://www.elastic.co/guide/en/workplace-search/current/workplace-search-document-permissions-api.html#add-one>`_
:arg content_source_id: Unique ID for a Custom API source, provided upon
creation of a Custom API Source
:arg user: The username in context
:arg body: HTTP request body
:arg params: Additional query params to send with the request
:arg headers: Additional headers to send with the request
:arg http_auth: Access token or HTTP basic auth username
and password to send with the request
:arg request_timeout: Timeout in seconds
:arg ignore_status: HTTP status codes to not raise an error
:raises elastic_enterprise_search.BadRequestError:
:raises elastic_enterprise_search.UnauthorizedError:
:raises elastic_enterprise_search.PaymentRequiredError:
:raises elastic_enterprise_search.NotFoundError:
"""
for param in (
content_source_id,
user,
):
if param in SKIP_IN_PATH:
raise ValueError("Empty value passed for a required argument")
params = QueryParams(params)
return self.perform_request(
"POST",
to_path(
"api",
"ws",
"v1",
"sources",
content_source_id,
"permissions",
user,
"add",
),
body=body,
params=params,
headers=headers,
http_auth=http_auth,
request_timeout=request_timeout,
ignore_status=ignore_status,
)
def get_external_identity(
self,
content_source_id,
user,
params=None,
headers=None,
http_auth=DEFAULT,
request_timeout=DEFAULT,
ignore_status=(),
):
"""
Retrieves an external identity
`<https://www.elastic.co/guide/en/workplace-search/current/workplace-search-external-identities-api.html#show-external-identity>`_
:arg content_source_id: Unique ID for a Custom API source, provided upon
creation of a Custom API Source
:arg user: The username in context
:arg params: Additional query params to send with the request
:arg headers: Additional headers to send with the request
:arg http_auth: Access token or HTTP basic auth username
and password to send with the request
:arg request_timeout: Timeout in seconds
:arg ignore_status: HTTP status codes to not raise an error
:raises elastic_enterprise_search.UnauthorizedError:
:raises elastic_enterprise_search.NotFoundError:
"""
for param in (
content_source_id,
user,
):
if param in SKIP_IN_PATH:
raise ValueError("Empty value passed for a required argument")
params = QueryParams(params)
return self.perform_request(
"GET",
to_path(
"api",
"ws",
"v1",
"sources",
content_source_id,
"external_identities",
user,
),
params=params,
headers=headers,
http_auth=http_auth,
request_timeout=request_timeout,
ignore_status=ignore_status,
)
def index_documents(
self,
content_source_id,
documents,
params=None,
headers=None,
http_auth=DEFAULT,
request_timeout=DEFAULT,
ignore_status=(),
):
"""
Indexes one or more new documents into a custom content source, or updates one
or more existing documents
`<https://www.elastic.co/guide/en/workplace-search/current/workplace-search-custom-sources-api.html#index-and-update>`_
:arg content_source_id: Unique ID for a Custom API source, provided upon
creation of a Custom API Source
:arg documents: HTTP request body
:arg params: Additional query params to send with the request
:arg headers: Additional headers to send with the request
:arg http_auth: Access token or HTTP basic auth username
and password to send with the request
:arg request_timeout: Timeout in seconds
:arg ignore_status: HTTP status codes to not raise an error
:raises elastic_enterprise_search.BadRequestError:
:raises elastic_enterprise_search.UnauthorizedError:
:raises elastic_enterprise_search.NotFoundError:
:raises elastic_enterprise_search.PayloadTooLargeError:
"""
if content_source_id in SKIP_IN_PATH:
raise ValueError("Empty value passed for a required argument")
params = QueryParams(params)
return self.perform_request(
"POST",
to_path(
"api",
"ws",
"v1",
"sources",
content_source_id,
"documents",
"bulk_create",
),
body=documents,
params=params,
headers=headers,
http_auth=http_auth,
request_timeout=request_timeout,
ignore_status=ignore_status,
)
def get_stats(
self,
include=None,
params=None,
headers=None,
http_auth=DEFAULT,
request_timeout=DEFAULT,
ignore_status=(),
):
"""
Get information about the resource usage of the application, the state of
different internal queues, etc.
`<https://www.elastic.co/guide/en/enterprise-search/current/monitoring-apis.html#stats-api-example>`_
:arg include: Comma-separated list of stats to return
:arg params: Additional query params to send with the request
:arg headers: Additional headers to send with the request
:arg http_auth: Access token or HTTP basic auth username
and password to send with the request
:arg request_timeout: Timeout in seconds
:arg ignore_status: HTTP status codes to not raise an error
:raises elastic_enterprise_search.UnauthorizedError:
"""
params = QueryParams(params)
if include is not None:
params.add("include", include)
return self.perform_request(
"GET",
"/api/ent/v1/internal/stats",
params=params,
headers=headers,
http_auth=http_auth,
request_timeout=request_timeout,
ignore_status=ignore_status,
)
def list_permissions(
self,
content_source_id,
current_page=None,
page_size=None,
params=None,
headers=None,
http_auth=DEFAULT,
request_timeout=DEFAULT,
ignore_status=(),
):
"""
Lists all permissions for all users
`<https://www.elastic.co/guide/en/workplace-search/current/workplace-search-document-permissions-api.html#list>`_
:arg content_source_id: Unique ID for a Custom API source, provided upon
creation of a Custom API Source
:arg current_page: Which page of results to request
:arg page_size: The number of results to return in a page
:arg params: Additional query params to send with the request
:arg headers: Additional headers to send with the request
:arg http_auth: Access token or HTTP basic auth username
and password to send with the request
:arg request_timeout: Timeout in seconds
:arg ignore_status: HTTP status codes to not raise an error
:raises elastic_enterprise_search.BadRequestError:
:raises elastic_enterprise_search.UnauthorizedError:
:raises elastic_enterprise_search.PaymentRequiredError:
:raises elastic_enterprise_search.NotFoundError:
"""
if content_source_id in SKIP_IN_PATH:
raise ValueError("Empty value passed for a required argument")
params = QueryParams(params)
if current_page is not None:
params.add("page[current]", current_page)
if page_size is not None:
params.add("page[size]", page_size)
return self.perform_request(
"GET",
to_path(
"api",
"ws",
"v1",
"sources",
content_source_id,
"permissions",
),
params=params,
headers=headers,
http_auth=http_auth,
request_timeout=request_timeout,
ignore_status=ignore_status,
)
def delete_content_source(
self,
content_source_id,
params=None,
headers=None,
http_auth=DEFAULT,
request_timeout=DEFAULT,
ignore_status=(),
):
"""
Deletes a content source by ID
`<https://www.elastic.co/guide/en/workplace-search/current/workplace-search-content-sources-api.html#remove-content-source-api>`_
:arg content_source_id: Unique ID for a Custom API source, provided upon
creation of a Custom API Source
:arg params: Additional query params to send with the request
:arg headers: Additional headers to send with the request
:arg http_auth: Access token or HTTP basic auth username
and password to send with the request
:arg request_timeout: Timeout in seconds
:arg ignore_status: HTTP status codes to not raise an error
:raises elastic_enterprise_search.BadRequestError:
:raises elastic_enterprise_search.UnauthorizedError:
:raises elastic_enterprise_search.NotFoundError:
"""
if content_source_id in SKIP_IN_PATH:
raise ValueError("Empty value passed for a required argument")
params = QueryParams(params)
return self.perform_request(
"DELETE",
to_path(
"api",
"ws",
"v1",
"sources",
content_source_id,
),
params=params,
headers=headers,
http_auth=http_auth,
request_timeout=request_timeout,
ignore_status=ignore_status,
)
def test_datetime_with_timezone():
# Hawaii Standard Time is UTC-10 and doesn't observe
# daylight savings so this should continue to pass :)
params = QueryParams(
{
"dt": datetime.datetime(
year=2020,
month=1,
day=1,
hour=10,
minute=0,
second=0,
tzinfo=tz.gettz("HST"),
)
}
)
assert _utils.default_params_encoder(params) == "dt=2020-01-01T10:00:00-10:00"
dt = datetime.datetime(
year=2020, month=1, day=1, hour=10, minute=0, second=0, tzinfo=tz.UTC
)
params["dt"] = dt
assert _utils.default_params_encoder(params) == "dt=2020-01-01T10:00:00Z"
def search(
self,
body,
params=None,
headers=None,
http_auth=DEFAULT,
request_timeout=DEFAULT,
ignore_status=(),
):
"""
Search across available sources with various query tuning options
`<https://www.elastic.co/guide/en/workplace-search/current/workplace-search-search-api.html>`_
:arg body: HTTP request body
:arg params: Additional query params to send with the request
:arg headers: Additional headers to send with the request
:arg http_auth: Access token or HTTP basic auth username
and password to send with the request
:arg request_timeout: Timeout in seconds
:arg ignore_status: HTTP status codes to not raise an error
:raises elastic_enterprise_search.BadRequestError:
:raises elastic_enterprise_search.UnauthorizedError:
"""
params = QueryParams(params)
return self.perform_request(
"POST",
"/api/ws/v1/search",
body=body,
params=params,
headers=headers,
http_auth=http_auth,
request_timeout=request_timeout,
ignore_status=ignore_status,
)
def create_analytics_event(
self,
body,
params=None,
headers=None,
http_auth=DEFAULT,
request_timeout=DEFAULT,
ignore_status=(),
):
"""
Capture click and feedback analytic events
`<https://www.elastic.co/guide/en/workplace-search/current/workplace-search-analytics-api.html>`_
:arg body: HTTP request body
:arg params: Additional query params to send with the request
:arg headers: Additional headers to send with the request
:arg http_auth: Access token or HTTP basic auth username
and password to send with the request
:arg request_timeout: Timeout in seconds
:arg ignore_status: HTTP status codes to not raise an error
:raises elastic_enterprise_search.BadRequestError:
:raises elastic_enterprise_search.UnauthorizedError:
"""
params = QueryParams(params)
return self.perform_request(
"POST",
"/api/ws/v1/analytics/event",
body=body,
params=params,
headers=headers,
http_auth=http_auth,
request_timeout=request_timeout,
ignore_status=ignore_status,
)
def list_content_sources(
self,
current_page=None,
page_size=None,
params=None,
headers=None,
http_auth=DEFAULT,
request_timeout=DEFAULT,
ignore_status=(),
):
"""
Retrieves all content sources
`<https://www.elastic.co/guide/en/workplace-search/current/workplace-search-content-sources-api.html#list-content-sources-api>`_
:arg current_page: Which page of results to request
:arg page_size: The number of results to return in a page
:arg params: Additional query params to send with the request
:arg headers: Additional headers to send with the request
:arg http_auth: Access token or HTTP basic auth username
and password to send with the request
:arg request_timeout: Timeout in seconds
:arg ignore_status: HTTP status codes to not raise an error
:raises elastic_enterprise_search.UnauthorizedError:
:raises elastic_enterprise_search.NotFoundError:
"""
params = QueryParams(params)
if current_page is not None:
params.add("page[current]", current_page)
if page_size is not None:
params.add("page[size]", page_size)
return self.perform_request(
"GET",
"/api/ws/v1/sources",
params=params,
headers=headers,
http_auth=http_auth,
request_timeout=request_timeout,
ignore_status=ignore_status,
)
def oauth_exchange_for_access_token(self,
client_id,
client_secret,
redirect_uri,
code=None,
refresh_token=None):
"""Exchanges either an authorization code or refresh token for
an access token via the confidential OAuth flow.
:param client_id: Client ID as generated when setting up an OAuth application
:param client_secret: Client secret as generated when setting up an OAuth application
:param redirect_uri: Location to redirect user once the OAuth process is completed.
Must match one of the URIs configured in the OAuth application
:param code: Authorization code as returned by the '/ws/oauth/authorize' endpoint
:param refresh_token: Refresh token returned at the same time as receiving an access token
:returns: The HTTP response containing the access_token and refresh_token
along with other token-related metadata
"""
values = [client_id, client_secret, redirect_uri]
# Check that 'code' and 'refresh_token' are mutually exclusive
if code is None and refresh_token is None:
raise ValueError(
"Either the 'code' or 'refresh_token' parameter must be used")
elif code is not None and refresh_token is not None:
raise ValueError(
"'code' and 'refresh_token' parameters are mutually exclusive")
elif code is not None:
values.append(code)
grant_type = "authorization_code"
else:
assert refresh_token is not None
values.append(refresh_token)
grant_type = "refresh_token"
if not all(isinstance(value, str) for value in values):
raise TypeError("All parameters must be of type 'str'")
params = QueryParams()
params.add("grant_type", grant_type)
params.add("client_id", client_id)
params.add("client_secret", client_secret)
params.add("redirect_uri", redirect_uri)
if code is not None:
params.add("code", code)
else:
params.add("refresh_token", refresh_token)
return self.perform_request(
method="POST",
path="/ws/oauth/token",
params=params,
# Note that we don't want any authentication on this
# request, the 'code'/'refresh_token' is enough!
http_auth=None,
)