Skip to content

Commit e82e42f

Browse files
szabosteveszabosteve
authored
[7.x][DOCS] Adds Connecting section to Ruby docs (#1094)
* [7.x][DOCS] Adds Connecting section to Ruby docs. * [DOCS] Minor edits.
1 parent 62cf769 commit e82e42f

File tree

4 files changed

+170
-36
lines changed

4 files changed

+170
-36
lines changed

‎docs/connecting.asciidoc

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
[[connecting]]
2+
== Connecting
3+
4+
This page contains the information you need to connect and use the Client with
5+
{es}.
6+
7+
**On this page**
8+
9+
* <<client-auth, Authentication options>>
10+
* <<client-usage, Using the client>>
11+
12+
13+
[discrete]
14+
[[client-auth]]
15+
=== Authentication
16+
17+
This document contains code snippets to show you how to connect to various {es}
18+
providers.
19+
20+
21+
[discrete]
22+
[[auth-ec]]
23+
==== Elastic Cloud
24+
25+
If you are using https://www.elastic.co/cloud[Elastic Cloud], the client offers
26+
an easy way to connect to it. You must pass the Cloud ID that you can find in
27+
the cloud console, then your username and password.
28+
29+
30+
[source,ruby]
31+
------------------------------------
32+
require 'elasticsearch'
33+
34+
client = Elasticsearch::Client.new(
35+
cloud_id: '<CloudID>'
36+
user: '<Username>',
37+
password: '<Password>',
38+
)
39+
------------------------------------
40+
41+
You can also connect to the Cloud by using API Key authentication:
42+
43+
[source,ruby]
44+
------------------------------------
45+
client = Elasticsearch::Client.new(
46+
cloud_id: '<CloudID>',
47+
api_key: {id: '<Id>', api_key: '<APIKey>'}
48+
)
49+
------------------------------------
50+
51+
52+
[discrete]
53+
[[auth-api-key]]
54+
==== API Key authentication
55+
56+
You can also use the
57+
https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-api-create-api-key.html[ApiKey]
58+
authentication.
59+
60+
NOTE: If you provide both basic authentication credentials and the ApiKey
61+
configuration, the ApiKey takes precedence.
62+
You can also use API Key authentication:
63+
64+
[source,ruby]
65+
------------------------------------
66+
Elasticsearch::Client.new(
67+
host: host,
68+
transport_options: transport_options,
69+
api_key: credentials
70+
)
71+
------------------------------------
72+
73+
Where credentials is either the base64 encoding of `id` and `api_key` joined by
74+
a colon or a hash with the `id` and `api_key`:
75+
76+
[source,ruby]
77+
------------------------------------
78+
Elasticsearch::Client.new(
79+
host: host,
80+
transport_options: transport_options,
81+
api_key: {id: 'my_id', api_key: 'my_api_key'}
82+
)
83+
------------------------------------
84+
85+
86+
[discrete]
87+
[[auth-basic]]
88+
==== Basic authentication
89+
90+
You can pass the authentication credentials, scheme and port in the host
91+
configuration hash:
92+
93+
[source,ruby]
94+
------------------------------------
95+
client = Elasticsearch::Client.new(
96+
hosts:
97+
[
98+
{
99+
host: 'my-protected-host',
100+
port: '443',
101+
user: 'USERNAME',
102+
password: 'PASSWORD',
103+
scheme: 'https'
104+
}
105+
]
106+
)
107+
------------------------------------
108+
109+
Or use the common URL format:
110+
111+
client = Elasticsearch::Client.new(url: 'https://username:password@localhost:9200')
112+
113+
To pass a custom certificate for SSL peer verification to Faraday-based clients,
114+
use the `transport_options` option:
115+
116+
[source,ruby]
117+
------------------------------------
118+
Elasticsearch::Client.new(
119+
url: 'https://username:password@localhost:9200',
120+
transport_options: {
121+
ssl: { ca_file: '/path/to/cacert.pem' }
122+
}
123+
)
124+
------------------------------------
125+
126+
127+
[discrete]
128+
[[client-usage]]
129+
=== Usage
130+
131+
The following snippet shows an example of using the Ruby client:
132+
133+
[source,ruby]
134+
------------------------------------
135+
require 'elasticsearch'
136+
137+
client = Elasticsearch::Client.new log: true
138+
139+
client.cluster.health
140+
141+
client.index(index: 'my-index', type: 'my-document', id: 1, body: { title: 'Test' })
142+
143+
client.indices.refresh(index: 'my-index')
144+
145+
client.search(index: 'my-index', body: { query: { match: { title: 'test' } } })
146+
------------------------------------

‎docs/index.asciidoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ include::overview.asciidoc[]
88

99
include::installation.asciidoc[]
1010

11+
include::connecting.asciidoc[]
12+
1113
include::model.asciidoc[]
1214

1315
include::rails.asciidoc[]

‎docs/installation.asciidoc

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,4 +32,25 @@ Or you can add a specific version of {es} to your Gemfile:
3232
[source,ruby]
3333
------------------------------------
3434
gem 'elasticsearch', '~> 7.0'
35-
------------------------------------
35+
------------------------------------
36+
37+
38+
[discrete]
39+
=== {es} and Ruby Version Compatibility
40+
41+
The {es} client is compatible with Ruby 1.9 and higher.
42+
43+
The client's API is compatible with {es} API versions from 0.90 till current,
44+
just use a release matching major version of {es}.
45+
46+
|===
47+
| Gem Version | | {es} Version
48+
49+
| 0.90 | → | 0.90
50+
| 1.x | → | 1.x
51+
| 2.x | → | 2.x
52+
| 5.x | → | 5.x
53+
| 6.x | → | 6.x
54+
| 7.x | → | 7.x
55+
| master | → | master
56+
|===

‎docs/overview.asciidoc

Lines changed: 0 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -11,41 +11,6 @@ http://rubydoc.info/gems/elasticsearch[RubyDoc]. This documentation provides
1111
only an overview of features.
1212

1313

14-
[discrete]
15-
=== {es} and Ruby Version Compatibility
16-
17-
The {es} client is compatible with Ruby 1.9 and higher.
18-
19-
The client's API is compatible with {es} API versions from 0.90 till current,
20-
just use a release matching major version of {es}.
21-
22-
|===
23-
| Gem Version | | {es} Version
24-
25-
| 0.90 | → | 0.90
26-
| 1.x | → | 1.x
27-
| 2.x | → | 2.x
28-
| 5.x | → | 5.x
29-
| 6.x | → | 6.x
30-
| 7.x | → | 7.x
31-
| master | → | master
32-
|===
33-
34-
35-
[discrete]
36-
=== Example Usage
37-
38-
[source,ruby]
39-
------------------------------------
40-
require 'elasticsearch'
41-
client = Elasticsearch::Client.new log: true
42-
client.cluster.health
43-
client.index index: 'my-index', type: 'my-document', id: 1, body: { title: 'Test' }
44-
client.indices.refresh index: 'my-index'
45-
client.search index: 'my-index', body: { query: { match: { title: 'test' } } }
46-
------------------------------------
47-
48-
4914
[discrete]
5015
=== Features
5116

0 commit comments

Comments
 (0)