База знаний
Войти

Взаимодействие с Подсистемой

С Подсистемой можно взаимодействовать с помощью REST API или одного из языковых клиентов Подсистемы. В этом разделе представлен REST API Подсистемы. Если нужно взаимодействовать с Подсистемой на требуемом языке программирования, используются библиотеки на JavaScript, Python, Ruby, Java, PHP, .NET, Go, Hadoop и Rust.

REST API

При взаимодействии с кластерами Подсистемы с помощью REST API можно изменять большинство настроек, модифицировать индексы, проверять работоспособность кластера, получать статистику и т.д. Возможно использование таких клиентов, как cURL, или любого языка программирования, который может отправлять HTTP-запросы.

Отправка HTTP-запросов возможна через терминал (п. Отправка запросов в терминале) или в консоли инструментов разработчика в "Панелях мониторинга" Подсистемы (п. Отправка запросов в инструментах разработки).

Отправка запросов в терминале

При отправке запросов cURL в терминале формат запроса зависит от того, используется ли плагин Security.

В качестве примера можно рассмотреть запрос к API состояния кластера без использования плагина Security:

curl -X GET "http://localhost:9200/_cluster/health"

Если используется плагин Security, следует указать имя пользователя и пароль в запросе:

curl -X GET "http://localhost:9200/_cluster/health" -ku admin:<custom-admin-password>

где:

  • admin – имя пользователя по умолчанию;
  • custom-admin-password – пароль, указанный в файле docker-compose.yml в настройке:
OPENSEACH_INITIAL_ADMIN_PASSWORD=<custom-admin-password>

Подсистема обычно возвращает ответы в плоском формате JSON по умолчанию. Для получения ответа в удобочитаемом для человека формате следует указать параметр запроса pretty:

curl -X GET "https://localhost:9200/_cluster/health?pretty"

Для запросов, содержащих тело, нужно указать заголовок Content-Type и предоставить полезную нагрузку запроса в параметре -d (данные):

curl -X GET "https://localhost:9200/employees/_search?pretty" -H 'Content-Type: application/json' -d'
{
"query": {
"match_all": {}
}
}'

Отправка запросов в инструментах разработки

В консоли "Инструменты разработки" в "Панелях мониторинга" Подсистемы используется более простой синтаксис для форматирования REST-запросов по сравнению с командой cURL. Чтобы отправлять запросы в "Инструменты разработки", нужно выполнить следующие действия:

  1. чтобы получить доступ к "Панелям мониторинга" Подсистемы, открыть адрес https://localhost:5601/ в веб-браузере на том же хосте, на котором работает кластер Подсистемы. Имя пользователя по умолчанию — admin, а пароль указан в файле docker-compose.yml в разделе настроек:
  2. в верхней строке меню перейти в "*";
  3. в левой панели консоли ввести следующий запрос:
  4. чтобы отправить запрос, нажать значок запуска в правом верхнем углу запроса. Также можно отправить запрос, нажав клавиши Ctrl+Enter.
OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password>;

GET _cluster/health

Индексирование документов

Чтобы добавить документ JSON в индекс Подсистемы (то есть индексировать документ), нужно отправить HTTP-запрос со следующим заголовком:

PUT https://<host>:<port>/<index-name>/_doc/<document-id>

После отправки запроса Подсистема создает индекс под названием <index-name> и сохраняет загруженный документ в этом индексе. Если не указать идентификатор документа <document-id>, Подсистема сгенерирует его.

Динамическое сопоставление

При индексировании документа Подсистема определяет типы полей на основе типов JSON, указанных в документе. Этот процесс называется динамическим сопоставлением.

Чтобы просмотреть предполагаемые типы полей, нужно отправить запрос в endpoint _mapping:

GET /<index-name>/_mapping

Подсистема выдает ответ полем type для каждого поля:

{
"<index-name>": {
"mappings": {
"properties": {
"gpa": {
"type": "float"
},
{
"grad_year": {
"type": "long"
},
{
"name": {
"type": "text",
"fields": {
"keyword": {
"type": "keyword",
"ignore_above": 256
}

Подсистемой сопоставлены числовые поля с типами float и long. Следует обратить внимание, что Подсистемой сопоставлено текстовое поле name с типом text и добавлено подполе name.keyword с типом keyword. Поля, сопоставленные с типом text, анализируются (преобразуются в нижний регистр и разделяются на термины) и могут использоваться для полнотекстового поиска. Поля, сопоставленные с типом keyword, используются для поиска по точному соответствию.

Подсистемой сопоставлено поле grad_year с long. Если требуется сопоставить его с типом date вместо этого, нужно удалить индекс, а затем создать его заново, явно указав сопоставления.

Поиск документов

Чтобы выполнить поиск документа, нужно указать индекс, по которому выполняется поиск, и запрос, который будет использоваться для сопоставления документов. Самый простой запрос — это запрос match_all, который сопоставляет все документы в индексе:

GET //<index-name>/_search
{
"query": {
"match_all": {}
}

В результате Подсистема возвращает проиндексированный документ.

Обновление документов

В Подсистеме документы являются неизменяемыми, но можно обновить документ, получив его, обновив его информацию и повторно проиндексировав. Возможно обновить весь документ с помощью API-индексирования документов, указав значения для всех существующих и добавленных полей в документе.

Удаление документа

Чтобы удалить документ, нужно отправить запрос на удаление и указать идентификатор документа:

DELETE <index-name>/_doc/<document-id>

Удаление индекса

Чтобы удалить индекс, нужно отправить следующий запрос:

DELETE <index-name>

Сопоставления индексов и настройки

Индексы Подсистемы настраиваются с помощью сопоставлений и настроек:

  • Сопоставление — это набор полей и типов этих полей;
  • Настройки включают такие данные об индексе, как имя индекса, дата создания и количество сегментов.

Возможно указать сопоставления и настройки в одном запросе.

Следует обратить внимание, что после создания поля нельзя изменить его тип. Для изменения типа поля необходимо удалить индекс и создать его заново с новыми сопоставлениями.