500 lines
11 KiB
Plaintext
500 lines
11 KiB
Plaintext
[[client-connecting]]
|
||
== Connecting
|
||
|
||
This page contains the information you need to connect and use the Client with
|
||
{es}.
|
||
|
||
**On this page**
|
||
|
||
* <<auth-reference, Authentication options>>
|
||
* <<client-usage, Using the client>>
|
||
* <<client-connect-proxy, Connecting through a proxy>>
|
||
* <<client-error-handling, Handling errors>>
|
||
|
||
[[auth-reference]]
|
||
[discrete]
|
||
=== Authentication
|
||
|
||
This document contains code snippets to show you how to connect to various {es}
|
||
providers.
|
||
|
||
|
||
[discrete]
|
||
[[auth-ec]]
|
||
==== Elastic Cloud
|
||
|
||
If you are using https://www.elastic.co/cloud[Elastic Cloud], the client offers
|
||
an easy way to connect to it via the `cloud` option. You must pass the Cloud ID
|
||
that you can find in the cloud console, then your username and password inside
|
||
the `auth` option.
|
||
|
||
NOTE: When connecting to Elastic Cloud, the client will automatically enable
|
||
both request and response compression by default, since it yields significant
|
||
throughput improvements. Moreover, the client will also set the ssl option
|
||
`secureProtocol` to `TLSv1_2_method` unless specified otherwise. You can still
|
||
override this option by configuring them.
|
||
|
||
IMPORTANT: Do not enable sniffing when using Elastic Cloud, since the nodes are
|
||
behind a load balancer, Elastic Cloud will take care of everything for you.
|
||
Take a look https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how[here]
|
||
to know more.
|
||
|
||
[source,js]
|
||
----
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({
|
||
cloud: {
|
||
id: 'name:bG9jYWxob3N0JGFiY2QkZWZnaA==',
|
||
},
|
||
auth: {
|
||
username: 'elastic',
|
||
password: 'changeme'
|
||
}
|
||
})
|
||
----
|
||
|
||
|
||
[discrete]
|
||
[[auth-apikey]]
|
||
==== ApiKey authentication
|
||
|
||
You can use the
|
||
https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-api-create-api-key.html[ApiKey]
|
||
authentication by passing the `apiKey` parameter via the `auth` option. The
|
||
`apiKey` parameter can be either a base64 encoded string or an object with the
|
||
values that you can obtain from the
|
||
https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-api-create-api-key.html[create api key endpoint].
|
||
|
||
NOTE: If you provide both basic authentication credentials and the ApiKey
|
||
configuration, the ApiKey takes precedence.
|
||
|
||
[source,js]
|
||
----
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({
|
||
node: 'https://localhost:9200',
|
||
auth: {
|
||
apiKey: 'base64EncodedKey'
|
||
}
|
||
})
|
||
----
|
||
|
||
[source,js]
|
||
----
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({
|
||
node: 'https://localhost:9200',
|
||
auth: {
|
||
apiKey: {
|
||
id: 'foo',
|
||
api_key: 'bar'
|
||
}
|
||
}
|
||
})
|
||
----
|
||
|
||
|
||
[discrete]
|
||
[[auth-basic]]
|
||
==== Basic authentication
|
||
|
||
You can provide your credentials by passing the `username` and `password`
|
||
parameters via the `auth` option.
|
||
|
||
NOTE: If you provide both basic authentication credentials and the Api Key
|
||
configuration, the Api Key will take precedence.
|
||
|
||
[source,js]
|
||
----
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({
|
||
node: 'https://localhost:9200',
|
||
auth: {
|
||
username: 'elastic',
|
||
password: 'changeme'
|
||
}
|
||
})
|
||
----
|
||
|
||
|
||
Otherwise, you can provide your credentials in the node(s) URL.
|
||
|
||
[source,js]
|
||
----
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({
|
||
node: 'https://username:password@localhost:9200'
|
||
})
|
||
----
|
||
|
||
|
||
[discrete]
|
||
[[auth-ssl]]
|
||
==== SSL configuration
|
||
|
||
Without any additional configuration you can specify `https://` node urls, and
|
||
the certificates used to sign these requests will be verified. To turn off
|
||
certificate verification, you must specify an `ssl` object in the top level
|
||
config and set `rejectUnauthorized: false`. The default `ssl` values are the
|
||
same that Node.js's https://nodejs.org/api/tls.html#tls_tls_connect_options_callback[`tls.connect()`]
|
||
uses.
|
||
|
||
[source,js]
|
||
----
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({
|
||
node: 'https://localhost:9200',
|
||
auth: {
|
||
username: 'elastic',
|
||
password: 'changeme'
|
||
},
|
||
ssl: {
|
||
ca: fs.readFileSync('./cacert.pem'),
|
||
rejectUnauthorized: false
|
||
}
|
||
})
|
||
----
|
||
|
||
|
||
[discrete]
|
||
[[client-usage]]
|
||
=== Usage
|
||
|
||
Using the client is straightforward, it supports all the public APIs of {es},
|
||
and every method exposes the same signature.
|
||
|
||
|
||
[source,js]
|
||
----
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({ node: 'http://localhost:9200' })
|
||
|
||
// promise API
|
||
const result = await client.search({
|
||
index: 'my-index',
|
||
body: {
|
||
query: {
|
||
match: { hello: 'world' }
|
||
}
|
||
}
|
||
})
|
||
|
||
// callback API
|
||
client.search({
|
||
index: 'my-index',
|
||
body: {
|
||
query: {
|
||
match: { hello: 'world' }
|
||
}
|
||
}
|
||
}, (err, result) => {
|
||
if (err) console.log(err)
|
||
})
|
||
----
|
||
|
||
The returned value of every API call is designed as follows:
|
||
|
||
[source,ts]
|
||
----
|
||
{
|
||
body: object | boolean
|
||
statusCode: number
|
||
headers: object
|
||
warnings: [string],
|
||
meta: object
|
||
}
|
||
----
|
||
|
||
NOTE: The body is a boolean value when you use `HEAD` APIs.
|
||
|
||
The above value is returned even if there is an error during the execution of
|
||
the request, this means that you can safely use the
|
||
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment[destructuring assignment].
|
||
|
||
The `meta` key contains all the information about the request, such as attempt,
|
||
options, and the connection that has been used.
|
||
|
||
[source,js]
|
||
----
|
||
// promise API
|
||
const { body } = await client.search({
|
||
index: 'my-index',
|
||
body: {
|
||
query: {
|
||
match: { hello: 'world' }
|
||
}
|
||
}
|
||
})
|
||
|
||
// callback API
|
||
client.search({
|
||
index: 'my-index',
|
||
body: {
|
||
query: {
|
||
match: { hello: 'world' }
|
||
}
|
||
}
|
||
}, (err, { body }) => {
|
||
if (err) console.log(err)
|
||
})
|
||
----
|
||
|
||
|
||
[discrete]
|
||
==== Aborting a request
|
||
|
||
If needed, you can abort a running request by calling the `request.abort()`
|
||
method returned by the API.
|
||
|
||
CAUTION: If you abort a request, the request will fail with a
|
||
`RequestAbortedError`.
|
||
|
||
|
||
[source,js]
|
||
----
|
||
const request = client.search({
|
||
index: 'my-index',
|
||
body: {
|
||
query: {
|
||
match: { hello: 'world' }
|
||
}
|
||
}
|
||
}, {
|
||
ignore: [404],
|
||
maxRetries: 3
|
||
}, (err, result) => {
|
||
if (err) {
|
||
console.log(err) // RequestAbortedError
|
||
} else {
|
||
console.log(result)
|
||
}
|
||
})
|
||
|
||
request.abort()
|
||
----
|
||
|
||
The same behavior is valid for the promise style API as well.
|
||
|
||
[source,js]
|
||
----
|
||
const request = client.search({
|
||
index: 'my-index',
|
||
body: {
|
||
query: {
|
||
match: { hello: 'world' }
|
||
}
|
||
}
|
||
}, {
|
||
ignore: [404],
|
||
maxRetries: 3
|
||
})
|
||
|
||
request
|
||
.then(result => console.log(result))
|
||
.catch(err => console.log(err)) // RequestAbortedError
|
||
|
||
request.abort()
|
||
----
|
||
|
||
|
||
[discrete]
|
||
==== Request specific options
|
||
|
||
If needed you can pass request specific options in a second object:
|
||
|
||
[source,js]
|
||
----
|
||
// promise API
|
||
const result = await client.search({
|
||
index: 'my-index',
|
||
body: {
|
||
query: {
|
||
match: { hello: 'world' }
|
||
}
|
||
}
|
||
}, {
|
||
ignore: [404],
|
||
maxRetries: 3
|
||
})
|
||
|
||
// callback API
|
||
client.search({
|
||
index: 'my-index',
|
||
body: {
|
||
query: {
|
||
match: { hello: 'world' }
|
||
}
|
||
}
|
||
}, {
|
||
ignore: [404],
|
||
maxRetries: 3
|
||
}, (err, { body }) => {
|
||
if (err) console.log(err)
|
||
})
|
||
----
|
||
|
||
|
||
The supported request specific options are:
|
||
[cols=2*]
|
||
|===
|
||
|`ignore`
|
||
|`[number]` - HTTP status codes which should not be considered errors for this request. +
|
||
_Default:_ `null`
|
||
|
||
|`requestTimeout`
|
||
|`number` - Max request timeout for the request in milliseconds, it overrides the client default. +
|
||
_Default:_ `30000`
|
||
|
||
|`maxRetries`
|
||
|`number` - Max number of retries for the request, it overrides the client default. +
|
||
_Default:_ `3`
|
||
|
||
|`compression`
|
||
|`string, boolean` - Enables body compression for the request. +
|
||
_Options:_ `false`, `'gzip'` +
|
||
_Default:_ `false`
|
||
|
||
|`asStream`
|
||
|`boolean` - Instead of getting the parsed body back, you get the raw Node.js stream of data. +
|
||
_Default:_ `false`
|
||
|
||
|`headers`
|
||
|`object` - Custom headers for the request. +
|
||
_Default:_ `null`
|
||
|
||
|`querystring`
|
||
|`object` - Custom querystring for the request. +
|
||
_Default:_ `null`
|
||
|
||
|`id`
|
||
|`any` - Custom request id. _(overrides the top level request id generator)_ +
|
||
_Default:_ `null`
|
||
|
||
|`context`
|
||
|`any` - Custom object per request. _(you can use it to pass data to the clients events)_ +
|
||
_Default:_ `null`
|
||
|===
|
||
|
||
|
||
[discrete]
|
||
[[client-connect-proxy]]
|
||
=== Connecting through a proxy
|
||
|
||
~Added~ ~in~ ~`v7.10.0`~
|
||
|
||
If you need to pass through an http(s) proxy for connecting to {es}, the client
|
||
out of the box offers a handy configuration for helping you with it. Under the
|
||
hood, it uses the https://github.com/delvedor/hpagent[`hpagent`] module.
|
||
|
||
[source,js]
|
||
----
|
||
const client = new Client({
|
||
node: 'http://localhost:9200',
|
||
proxy: 'http://localhost:8080'
|
||
})
|
||
----
|
||
|
||
Basic authentication is supported as well:
|
||
|
||
[source,js]
|
||
----
|
||
const client = new Client({
|
||
node: 'http://localhost:9200',
|
||
proxy: 'http:user:pwd@//localhost:8080'
|
||
})
|
||
----
|
||
|
||
If you are connecting through a not http(s) proxy, such as a `socks5` or `pac`,
|
||
you can use the `agent` option to configure it.
|
||
|
||
[source,js]
|
||
----
|
||
const SocksProxyAgent = require('socks-proxy-agent')
|
||
const client = new Client({
|
||
node: 'http://localhost:9200',
|
||
agent () {
|
||
return new SocksProxyAgent('socks://127.0.0.1:1080')
|
||
}
|
||
})
|
||
----
|
||
|
||
|
||
[discrete]
|
||
[[client-error-handling]]
|
||
=== Error handling
|
||
|
||
The client exposes a variety of error objects that you can use to enhance your
|
||
error handling. You can find all the error objects inside the `errors` key in
|
||
the client.
|
||
|
||
[source,js]
|
||
----
|
||
const { errors } = require('@elastic/elasticsearch')
|
||
console.log(errors)
|
||
----
|
||
|
||
|
||
You can find the errors exported by the client in the table below.
|
||
|
||
[cols=3*]
|
||
|===
|
||
|*Error*
|
||
|*Description*
|
||
|*Properties*
|
||
|
||
|`ElasticsearchClientError`
|
||
|Every error inherits from this class, it is the basic error generated by the client.
|
||
a|* `name` - `string`
|
||
* `message` - `string`
|
||
|
||
|`TimeoutError`
|
||
|Generated when a request exceeds the `requestTimeout` option.
|
||
a|* `name` - `string`
|
||
* `message` - `string`
|
||
* `meta` - `object`, contains all the information about the request
|
||
|
||
|`ConnectionError`
|
||
|Generated when an error occurs during the request, it can be a connection error or a malformed stream of data.
|
||
a|* `name` - `string`
|
||
* `message` - `string`
|
||
* `meta` - `object`, contains all the information about the request
|
||
|
||
|`RequestAbortedError`
|
||
|Generated if the user calls the `request.abort()` method.
|
||
a|* `name` - `string`
|
||
* `message` - `string`
|
||
* `meta` - `object`, contains all the information about the request
|
||
|
||
|`NoLivingConnectionsError`
|
||
|Given the configuration, the ConnectionPool was not able to find a usable Connection for this request.
|
||
a|* `name` - `string`
|
||
* `message` - `string`
|
||
* `meta` - `object`, contains all the information about the request
|
||
|
||
|`SerializationError`
|
||
|Generated if the serialization fails.
|
||
a|* `name` - `string`
|
||
* `message` - `string`
|
||
* `data` - `object`, the object to serialize
|
||
|
||
|`DeserializationError`
|
||
|Generated if the deserialization fails.
|
||
a|* `name` - `string`
|
||
* `message` - `string`
|
||
* `data` - `string`, the string to deserialize
|
||
|
||
|`ConfigurationError`
|
||
|Generated if there is a malformed configuration or parameter.
|
||
a|* `name` - `string`
|
||
* `message` - `string`
|
||
|
||
|`ResponseError`
|
||
|Generated when in case of a `4xx` or `5xx` response.
|
||
a|* `name` - `string`
|
||
* `message` - `string`
|
||
* `meta` - `object`, contains all the information about the request
|
||
* `body` - `object`, the response body
|
||
* `statusCode` - `object`, the response headers
|
||
* `headers` - `object`, the response status code
|
||
|===
|