[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]]
|
||||
== Usage
|
||||
=== Usage
|
||||
|
||||
Using the client is straightforward, it supports all the public APIs of {es},
|
||||
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]
|
||||
----
|
||||
@ -82,11 +241,13 @@ client.search({
|
||||
|
||||
|
||||
[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]
|
||||
@ -113,6 +274,7 @@ request.abort()
|
||||
----
|
||||
|
||||
The same behavior is valid for the promise style API as well.
|
||||
|
||||
[source,js]
|
||||
----
|
||||
const request = client.search({
|
||||
@ -136,7 +298,8 @@ request.abort()
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Request specific options
|
||||
==== Request specific options
|
||||
|
||||
If needed you can pass request specific options in a second object:
|
||||
|
||||
[source,js]
|
||||
@ -214,13 +377,14 @@ _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 Elasticsearch, the client offers
|
||||
out of the box a handy configuration for helping you with it. Under the hood it
|
||||
uses the https://github.com/delvedor/hpagent[`hpagent`] module.
|
||||
If you need to pass through an http(s) proxy for connecting to {es}, the client
|
||||
offers out of the box a handy configuration for helping you with it. Under the
|
||||
hood, it uses the https://github.com/delvedor/hpagent[`hpagent`] module.
|
||||
|
||||
[source,js]
|
||||
----
|
||||
@ -256,6 +420,7 @@ const client = new Client({
|
||||
|
||||
|
||||
[discrete]
|
||||
[[client-error-handling]]
|
||||
=== Error handling
|
||||
|
||||
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::installation.asciidoc[]
|
||||
include::connecting.asciidoc[]
|
||||
include::changelog.asciidoc[]
|
||||
include::usage.asciidoc[]
|
||||
include::configuration.asciidoc[]
|
||||
include::reference.asciidoc[]
|
||||
include::breaking-changes.asciidoc[]
|
||||
include::authentication.asciidoc[]
|
||||
include::observability.asciidoc[]
|
||||
include::child.asciidoc[]
|
||||
include::extend.asciidoc[]
|
||||
@ -18,3 +17,4 @@ include::helpers.asciidoc[]
|
||||
include::typescript.asciidoc[]
|
||||
include::testing.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
|
||||
<<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.
|
||||
|
||||
|
||||
[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]
|
||||
=== 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