[7.x][DOCS] Adds Connecting section to Node.JS docs (#1344)
This commit is contained in:
István Zoltán Szabó
committed by
delvedor
delvedor
parent
11c11e4568
commit
dfb09b4827
@ -1,133 +0,0 @@
|
|||||||
[[auth-reference]]
|
|
||||||
== Authentication
|
|
||||||
|
|
||||||
This document contains code snippets to show you how to connect to various {es}
|
|
||||||
providers.
|
|
||||||
|
|
||||||
|
|
||||||
[discrete]
|
|
||||||
=== 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]
|
|
||||||
=== 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]
|
|
||||||
=== 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 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: {
|
|
||||||
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]
|
|
||||||
=== 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
|
|
||||||
}
|
|
||||||
})
|
|
||||||
----
|
|
||||||
@ -1,5 +1,164 @@
|
|||||||
|
[[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>>
|
||||||
|
|
||||||
|
[discrete]
|
||||||
|
[[authentication]]
|
||||||
|
=== 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]]
|
[[client-usage]]
|
||||||
== Usage
|
=== Usage
|
||||||
|
|
||||||
Using the client is straightforward, it supports all the public APIs of {es},
|
Using the client is straightforward, it supports all the public APIs of {es},
|
||||||
and every method exposes the same signature.
|
and every method exposes the same signature.
|
||||||
@ -33,7 +192,7 @@ client.search({
|
|||||||
})
|
})
|
||||||
----
|
----
|
||||||
|
|
||||||
The returned value of every API call is formed as follows:
|
The returned value of every API call is designed as follows:
|
||||||
|
|
||||||
[source,ts]
|
[source,ts]
|
||||||
----
|
----
|
||||||
@ -82,11 +241,13 @@ client.search({
|
|||||||
|
|
||||||
|
|
||||||
[discrete]
|
[discrete]
|
||||||
=== Aborting a request
|
==== Aborting a request
|
||||||
|
|
||||||
If needed, you can abort a running request by calling the `request.abort()` method returned by the API.
|
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`.
|
CAUTION: If you abort a request, the request will fail with a
|
||||||
|
`RequestAbortedError`.
|
||||||
|
|
||||||
|
|
||||||
[source,js]
|
[source,js]
|
||||||
@ -113,6 +274,7 @@ request.abort()
|
|||||||
----
|
----
|
||||||
|
|
||||||
The same behavior is valid for the promise style API as well.
|
The same behavior is valid for the promise style API as well.
|
||||||
|
|
||||||
[source,js]
|
[source,js]
|
||||||
----
|
----
|
||||||
const request = client.search({
|
const request = client.search({
|
||||||
@ -136,7 +298,8 @@ request.abort()
|
|||||||
|
|
||||||
|
|
||||||
[discrete]
|
[discrete]
|
||||||
=== Request specific options
|
==== Request specific options
|
||||||
|
|
||||||
If needed you can pass request specific options in a second object:
|
If needed you can pass request specific options in a second object:
|
||||||
|
|
||||||
[source,js]
|
[source,js]
|
||||||
@ -214,13 +377,14 @@ _Default:_ `null`
|
|||||||
|
|
||||||
|
|
||||||
[discrete]
|
[discrete]
|
||||||
|
[[client-connect-proxy]]
|
||||||
=== Connecting through a proxy
|
=== Connecting through a proxy
|
||||||
|
|
||||||
~Added~ ~in~ ~`v7.10.0`~
|
~Added~ ~in~ ~`v7.10.0`~
|
||||||
|
|
||||||
If you need to pass through an http(s) proxy for connecting to Elasticsearch, the client offers
|
If you need to pass through an http(s) proxy for connecting to {es}, the client
|
||||||
out of the box a handy configuration for helping you with it. Under the hood it
|
offers out of the box a handy configuration for helping you with it. Under the
|
||||||
uses the https://github.com/delvedor/hpagent[`hpagent`] module.
|
hood, it uses the https://github.com/delvedor/hpagent[`hpagent`] module.
|
||||||
|
|
||||||
[source,js]
|
[source,js]
|
||||||
----
|
----
|
||||||
@ -256,6 +420,7 @@ const client = new Client({
|
|||||||
|
|
||||||
|
|
||||||
[discrete]
|
[discrete]
|
||||||
|
[[client-error-handling]]
|
||||||
=== Error handling
|
=== Error handling
|
||||||
|
|
||||||
The client exposes a variety of error objects that you can use to enhance your
|
The client exposes a variety of error objects that you can use to enhance your
|
||||||
@ -5,12 +5,11 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
|
|||||||
|
|
||||||
include::introduction.asciidoc[]
|
include::introduction.asciidoc[]
|
||||||
include::installation.asciidoc[]
|
include::installation.asciidoc[]
|
||||||
|
include::connecting.asciidoc[]
|
||||||
include::changelog.asciidoc[]
|
include::changelog.asciidoc[]
|
||||||
include::usage.asciidoc[]
|
|
||||||
include::configuration.asciidoc[]
|
include::configuration.asciidoc[]
|
||||||
include::reference.asciidoc[]
|
include::reference.asciidoc[]
|
||||||
include::breaking-changes.asciidoc[]
|
include::breaking-changes.asciidoc[]
|
||||||
include::authentication.asciidoc[]
|
|
||||||
include::observability.asciidoc[]
|
include::observability.asciidoc[]
|
||||||
include::child.asciidoc[]
|
include::child.asciidoc[]
|
||||||
include::extend.asciidoc[]
|
include::extend.asciidoc[]
|
||||||
@ -18,3 +17,4 @@ include::helpers.asciidoc[]
|
|||||||
include::typescript.asciidoc[]
|
include::typescript.asciidoc[]
|
||||||
include::testing.asciidoc[]
|
include::testing.asciidoc[]
|
||||||
include::examples/index.asciidoc[]
|
include::examples/index.asciidoc[]
|
||||||
|
include::redirects.asciidoc[]
|
||||||
|
|||||||
@ -18,4 +18,41 @@ npm install @elastic/elasticsearch@<major>
|
|||||||
----
|
----
|
||||||
|
|
||||||
To learn more about the supported major versions, please refer to the
|
To learn more about the supported major versions, please refer to the
|
||||||
<<js-compatibility-matrix>>.
|
<<js-compatibility-matrix>>.
|
||||||
|
|
||||||
|
[discrete]
|
||||||
|
[[js-compatibility-matrix]]
|
||||||
|
=== Compatibility matrix
|
||||||
|
|
||||||
|
The minimum supported version of Node.js is `v8`.
|
||||||
|
|
||||||
|
The library is compatible with all {es} versions since 5.x. We recommend you to
|
||||||
|
use the same major version of the client as the {es} instance that you are
|
||||||
|
using.
|
||||||
|
|
||||||
|
|
||||||
|
[%header,cols=2*]
|
||||||
|
|===
|
||||||
|
|{es} Version
|
||||||
|
|Client Version
|
||||||
|
|
||||||
|
|`master`
|
||||||
|
|`master`
|
||||||
|
|
||||||
|
|`7.x`
|
||||||
|
|`7.x`
|
||||||
|
|
||||||
|
|`6.x`
|
||||||
|
|`6.x`
|
||||||
|
|
||||||
|
|`5.x`
|
||||||
|
|`5.x`
|
||||||
|
|===
|
||||||
|
|
||||||
|
|
||||||
|
[discrete]
|
||||||
|
==== Browser
|
||||||
|
|
||||||
|
WARNING: There is no official support for the browser environment. It exposes
|
||||||
|
your {es} instance to everyone, which could lead to security issues. We
|
||||||
|
recommend you to write a lightweight proxy that uses this client instead.
|
||||||
@ -17,44 +17,6 @@ about the features of the client.
|
|||||||
* TypeScript support out of the box.
|
* TypeScript support out of the box.
|
||||||
|
|
||||||
|
|
||||||
[discrete]
|
|
||||||
[[js-compatibility-matrix]]
|
|
||||||
=== Compatibility matrix
|
|
||||||
|
|
||||||
The minimum supported version of Node.js is `v8`.
|
|
||||||
|
|
||||||
The library is compatible with all {es} versions since 5.x. We recommend you to
|
|
||||||
use the same major version of the client as the {es} instance that you are
|
|
||||||
using.
|
|
||||||
|
|
||||||
|
|
||||||
[%header,cols=2*]
|
|
||||||
|===
|
|
||||||
|{es} Version
|
|
||||||
|Client Version
|
|
||||||
|
|
||||||
|`master`
|
|
||||||
|`master`
|
|
||||||
|
|
||||||
|`7.x`
|
|
||||||
|`7.x`
|
|
||||||
|
|
||||||
|`6.x`
|
|
||||||
|`6.x`
|
|
||||||
|
|
||||||
|`5.x`
|
|
||||||
|`5.x`
|
|
||||||
|===
|
|
||||||
|
|
||||||
|
|
||||||
[discrete]
|
|
||||||
==== Browser
|
|
||||||
|
|
||||||
WARNING: There is no official support for the browser environment. It exposes
|
|
||||||
your {es} instance to everyone, which could lead to security issues. We
|
|
||||||
recommend you to write a lightweight proxy that uses this client instead.
|
|
||||||
|
|
||||||
|
|
||||||
[discrete]
|
[discrete]
|
||||||
=== Quick start
|
=== Quick start
|
||||||
|
|
||||||
|
|||||||
9
docs/redirects.asciidoc
Normal file
9
docs/redirects.asciidoc
Normal file
@ -0,0 +1,9 @@
|
|||||||
|
"appendix",role="exclude",id="redirects"]
|
||||||
|
= Deleted pages
|
||||||
|
|
||||||
|
The following pages have moved or been deleted.
|
||||||
|
|
||||||
|
[role="exclude",id="auth-reference"]
|
||||||
|
== Authentication
|
||||||
|
|
||||||
|
This page has moved. See <<authentication>>.
|
||||||
Reference in New Issue
Block a user