Connectingedit

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 Instanceedit

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 Instanceedit

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")

Authenticationedit

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 Searchedit

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",
    bearer_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",
    bearer_auth=signed_search_key
)
resp = client_side.search(
    engine_name="example-engine",
    query="..."
)

Authenticating with Workplace Searchedit

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.option(bearer_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"},
    bearer_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",
    bearer_auth="<content source access token>"
)

Authenticating with Enterprise Searchedit

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.options(
    basic_auth=("enterprise_search", "<password>")
).get_version()

Connection Parametersedit

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

Parameter Types Default Description

scheme

str

N/A

Whether to use HTTPS or HTTP for connecting to Enterprise Search

host

str

N/A

TCP host to connect to. If set to a URL will set port, use_ssl, and url_prefix after parsing.

port

Optional[int]

N/A

TCP port to connect to

path_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,
)