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

›

Connecting

edit

Connecting

edit

This page contains the information you need to connect and use the Client with Elastic Enterprise Search.

On this page

Connecting to an Elastic Cloud Instance

edit

To connect to an Elastic Enterprise Search instance hosted in :ecloud: after provisioning an Enterprise Search instance on the deployment screen you’ll see links for Launch and Copy endpoint.

Select Copy endpoint to copy a URL to your clipboard. From there paste the URL into the first parameter of a client like so:

from elastic_enterprise_search import EnterpriseSearch

client = EnterpriseSearch("<paste here>")

The URL will look like this:

"https://3b898c...ent-search.us-central1.gcp.cloud.es.io/login"

Notice the /login at the end, remove this part from the URL so that you end up with a URL like this:

from elastic_enterprise_search import EnterpriseSearch

client = EnterpriseSearch("https://3b898c...ent-search.us-central1.gcp.cloud.es.io")

From here your client only needs authentication and then is ready to be used!

Connecting to Self-Hosted Instance

edit

When connecting to a self-hosted instance provide the scheme, host, port, and URL prefix (if any) for the instance:

from elastic_enterprise_search import EnterpriseSearch

client = EnterpriseSearch("https://self-hosted.ent-search.xyz/url-prefix")

Authentication

edit

This section contains code snippets to show you how to connect to Enterprise Search, App Search, and Workplace Search.

Each service has its own authentication schemes. Using the http_auth property with either a string for a key / token or a tuple of (username, password) for basic authentication will set the proper Authorization HTTP header on the client instance.

Authenticating with App Search

edit

App Search supports authenticating with search keys, private keys, and signed search keys:

from elastic_enterprise_search import AppSearch

# Create an AppSearch client authenticated with a search key.
server_side = AppSearch(
    "https://<...>.ent-search.us-central1.gcp.cloud.es.io",
    http_auth="<search key>"
)

# Creating a Signed Search Key on the server side...
signed_search_key = server_side.create_signed_search_key(
    api_key=server_side.http_auth,
    api_key_name="<api key name>",
    search_fields={
        "body": {}
    }
)

# ...then a different client can then
# use the Signed Search key for searches:
client_side = AppSearch(
    "https://<...>.ent-search.us-central1.gcp.cloud.es.io",
    http_auth=signed_search_key
)
resp = client_side.search(
    engine_name="example-engine",
    body={
        ...
    }
)

Authenticating with Workplace Search

edit

Workplace Search supports authenticating with a custom content source access token and with an OAuth access token:

from elastic_enterprise_search import EnterpriseSearch

ent_search = EnterpriseSearch(
    "https://<...>.ent-search.us-central1.gcp.cloud.es.io"
)

# Authenticating with Workplace Search
# Custom API Content Source access token
ent_search.workplace_search.http_auth = "<content source access token>"

# You can also use an authentication method for a single
# request. This is useful for per-user authentication like OAuth:
ent_search.workplace_search.search(
    body={"query": "That one document"},
    http_auth="<oauth access token>"
)

# You can also create a WorkplaceSearch client on its
# own an authenticate in the constructor:
from elastic_enterprise_search import WorkplaceSearch

workplace_search = WorkplaceSearch(
    "https://<...>.ent-search.us-central1.gcp.cloud.es.io",
    http_auth="<content source access token>"
)

Authenticating with Enterprise Search

edit

Enterprise Search supports HTTP basic authentication with a username and password.

HTTP basic authentication uses the http_auth parameter by passing in a username and password as a tuple:

from elastic_enterprise_search import EnterpriseSearch

# Authenticating via basic auth for Enterprise Search APIs
ent_search = EnterpriseSearch(
    "https://<...>.ent-search.us-central1.gcp.cloud.es.io",
    http_auth=("enterprise_search", "<password>")
)

# You can set `http_auth` property on the client
ent_search.http_auth = ("enterprise_search", "<password>")

# You can also set a per-request `http_auth`
ent_search.get_version(http_auth=("enterprise_search", "<password>"))

Connection Parameters

edit

All connection parameters that can be passed into each client come from elastic-transport-python:

Parameter	Types	Default	Description
`host`	`str`	`"localhost"`	TCP host to connect to. If set to a URL will set `port`, `use_ssl`, and `url_prefix` after parsing.
`port`	`Optional[int]`	`3002`	TCP port to connect to
`use_ssl`	`bool`	`False`	Whether to connect using TLS/SSL
`url_prefix`	`str`	`""`	Path prefix for all requests
`request_timeout`	`Optional[float]`	`10.0`	Amount of time to wait for a response. Set to `None` for no limit
`headers`	`Dict[str, str]`	`{}`	HTTP headers to add to every request
`connections_per_host`	`int`	`10`	Number of concurrent connections to allow per-host. Only matters if making concurrent requests
`verify_cert`	`bool`	`True`	Whether to verify the server certificate during TLS handshake
`ca_certs`	`Optional[str]`	`certifi.where()`	CA certificates to use when verifying server certificate
`client_cert`	`Optional[str]`	`None`	Client certificate to present during TLS/SSL handshake
`client_key`	`Optional[str]`	`None`	Client private key for `client_cert`
`ssl_version`	`ssl.PROTOCOL_TLS*`	`ssl.PROTOCOL_TLS`	TLS version to use when connecting. By default uses the best version.
`ssl_assert_hostname`	`Union[str, bool]`	`host`	Expected hostname on the server certificate. By default is the same as `host`. If set to `False` will not verify hostname on certificate
`ssl_assert_fingerprint`	`Optional[str]`	`None`	Checksum to verify against the fingerprint of the server certificate
`ssl_context`	`Optional[ssl.SSLContext]`	`None`	Pre-configured `ssl.SSLContext` to use for TLS handshake

from elastic_enterprise_search import EnterpriseSearch

client = EnterpriseSearch(
    "https://localhost:8080",
    request_timeout=5,
    verify_certs=True,
    connections_per_host=5,
)

« Installation App Search APIs »