Учебники

Elasticsearch — API документов

Октябрь 3, 2018

Elasticsearch предоставляет API для одного документа и API для нескольких документов, где вызов API нацелен на один документ и несколько документов соответственно.

Индекс API

Это помогает добавлять или обновлять документ JSON в индексе, когда делается запрос к этому соответствующему индексу с определенным отображением. Например, приведенный ниже запрос добавит объект JSON в индекс школ и при отображении школ. 

POST http://localhost:9200/schools/school/4

Тело запроса 

{
   "name":"City School", "description":"ICSE", "street":"West End", "city":"Meerut", 
   "state":"UP", "zip":"250002", "location":[28.9926174, 77.692485], "fees":3500, 
   "tags":["fully computerized"], "rating":"4.5"
}

отклик 

{
   "_index":"schools", "_type":"school", "_id":"4", "_version":1,
   "_shards":{"total":2, "successful":1,"failed":0}, "created":true
}

Автоматическое создание индекса

Когда делается запрос на добавление объекта JSON к определенному индексу, и если этот индекс не существует, этот API автоматически создает этот индекс, а также базовое отображение для этого конкретного объекта JSON. Эту функциональность можно отключить, изменив значения следующих параметров на false, которые присутствуют в файлеasticsearch.yml. 

action.auto_create_index:false
index.mapper.dynamic:false

Вы также можете ограничить автоматическое создание индекса, когда разрешено только имя индекса с конкретными шаблонами, изменив значение следующего параметра — 

action.auto_create_index:+acc*,-bank*

(где + означает, что разрешено, а — означает, что не разрешено )

Versioning

Elasticsearch также предоставляет средства контроля версий. Мы можем использовать параметр запроса версии, чтобы указать версию конкретного документа. Например, 

POST http://localhost:9200/schools/school/1?version = 1

Тело запроса 

{
   "name":"Central School", "description":"CBSE Affiliation", "street":"Nagan",
   "city":"paprola", "state":"HP", "zip":"176115", "location":[31.8955385, 76.8380405],
   "fees":2200, "tags":["Senior Secondary", "beautiful campus"], "rating":"3.3"
}

отклик 

{
   "_index":"schools", "_type":"school", "_id":"1", "_version":2,
   "_shards":{"total":2, "successful":1,"failed":0}, "created":false
}

Есть два наиболее важных типа управления версиями; внутренняя версия — это версия по умолчанию, которая начинается с 1 и увеличивается с каждым обновлением, включая удаление. Номер версии может быть установлен снаружи. Чтобы включить эту функцию, нам нужно установить для version_type значение external.

Управление версиями происходит в режиме реального времени, и на него не влияют операции поиска в реальном времени.

Тип операции

Тип операции используется для форсирования операции создания, это помогает избежать перезаписи существующего документа. 

POST http://localhost:9200/tutorials/chapter/1?op_type = create

Тело запроса 

{
   "Text":"this is chapter one"
}

отклик 

{
   "_index":"tutorials", "_type":"chapter", "_id":"1", "_version":1,
   "_shards":{"total":2, "successful":1, "failed":0}, "created":true
}

Автоматическая генерация ID

Если идентификатор не указан в операции индексации, то Elasticsearch автоматически генерирует идентификатор для этого документа.

Родители и дети

Вы можете определить родителя любого документа, передав идентификатор родительского документа в параметре запроса родительского URL. 

POST http://localhost:9200/tutorials/article/1?parent = 1

Тело запроса 

{
   "Text":"This is article 1 of chapter 1"
}

Примечание. Если при выполнении этого примера вы получили исключение, заново создайте индекс, добавив в него следующий текст. 

{
   "mappings": {
      "chapter": {},
      "article": {
         "_parent": {
            "type": "chapter"
         }
      }
   }
}

Тайм-аут

По умолчанию операция индексации будет ждать, пока основной сегмент не станет доступным в течение 1 минуты, прежде чем произойдет сбой и ответит с ошибкой. Это значение времени ожидания можно изменить явно, передав значение в параметр времени ожидания. 

POST http://localhost:9200/tutorials/chapter/2?timeout = 3m

Тело запроса 

{
   "Text":"This is chapter 2 waiting for primary shard for 3 minutes"
}

Получить API

API помогает извлечь объект типа JSON, выполнив запрос get для определенного документа. Например, 

GET http://localhost:9200/schools/school/1

отклик 

{
   "_index":"schools", "_type":"school", "_id":"1", "_version":2,
   "found":true, "_source":{
      "name":"Central School", "description":"CBSE Affiliation", 
      "street":"Nagan", "city":"paprola", "state":"HP", "zip":"176115",
      "location":[31.8955385,76.8380405], "fees":2200, 
      "tags":["Senior Secondary", "beautiful campus"], "rating":"3.3"
   }
}

  • Эта операция выполняется в режиме реального времени и не зависит от частоты обновления индекса.

  • Вы также можете указать версию, тогда Elasticsearch будет извлекать только эту версию документа.

  • Вы также можете указать _all в запросе, чтобы Elasticsearch мог искать этот идентификатор документа в каждом типе, и он будет возвращать первый соответствующий документ.

  • Вы также можете указать поля, которые вы хотите в своем результате из этого конкретного документа.

Эта операция выполняется в режиме реального времени и не зависит от частоты обновления индекса.

Вы также можете указать версию, тогда Elasticsearch будет извлекать только эту версию документа.

Вы также можете указать _all в запросе, чтобы Elasticsearch мог искать этот идентификатор документа в каждом типе, и он будет возвращать первый соответствующий документ.

Вы также можете указать поля, которые вы хотите в своем результате из этого конкретного документа. 

GET http://localhost:9200/schools/school/1?fields = name,fees

отклик 

……………………..
"fields":{
   "name":["Central School"], "fees":[2200]
}
……………………..
  • Вы также можете получить исходную часть в своем результате, просто добавив _source часть в свой запрос get. 
GET http://localhost:9200/schools/school/1/_source

отклик 

{
   "name":"Central School", "description":"CBSE Afiliation", "street":"Nagan",
   "city":"paprola", "state":"HP", "zip":"176115", "location":[31.8955385, 76.8380405],
   "fees":2200, "tags":["Senior Secondary", "beatiful campus"], "rating":"3.3"
}

Вы также можете обновить осколок перед выполнением операции get, установив для параметра refresh значение true.

Удалить API

Вы можете удалить определенный индекс, сопоставление или документ, отправив запрос HTTP DELETE в Elasticsearch. Например, 

DELETE http://localhost:9200/schools/school/4

отклик 

{
   "found":true, "_index":"schools", "_type":"school", "_id":"4", "_version":2,
   "_shards":{"total":2, "successful":1, "failed":0}
}

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

  • Параметр маршрутизации может быть указан для удаления документа от конкретного пользователя, и операция завершается ошибкой, если документ не принадлежит этому конкретному пользователю.

  • В этой операции вы можете указать параметры обновления и тайм-аута, аналогичные GET API.

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

Параметр маршрутизации может быть указан для удаления документа от конкретного пользователя, и операция завершается ошибкой, если документ не принадлежит этому конкретному пользователю.

В этой операции вы можете указать параметры обновления и тайм-аута, аналогичные GET API.

Обновить API

Сценарий используется для выполнения этой операции, а управление версиями используется для того, чтобы убедиться, что во время получения и повторного индексирования не было обновлений. Например, обновите плату за обучение, используя скрипт — 

POST http://localhost:9200/schools_gov/school/1/_update

Тело запроса 

{
   "script":{
      "inline": "ctx._source.fees+ = inc", "params":{
         "inc": 500
      }
   }
}

отклик 

{
   "_index":"schools_gov", "_type":"school", "_id":"1", "_version":2,
   "_shards":{"total":2, "successful":1, "failed":0}
}

Примечание. Если вы получаете исключение сценария, рекомендуется добавить следующие строки в elastcisearch.yml 

script.inline: on
script.indexed: on

Вы можете проверить обновление, отправив запрос на получение обновленного документа. 

GET http://localhost:9200/schools_gov/school/1

Multi Get API

Он обладает той же функциональностью, что и GET API, но этот запрос get может возвращать более одного документа. Мы используем массив doc для указания индекса, типа и идентификатора всех документов, которые необходимо извлечь. 

POST http://localhost:9200/_mget

Тело запроса 

{
   "docs":[
      {
         "_index": "schools", "_type": "school", "_id": "1"
      },
		
      {
         "_index":"schools_gev", "_type":"school", "_id": "2"
      }
   ]
}

отклик 

{
   "docs":[
      {
         "_index":"schools", "_type":"school", "_id":"1",
         "_version":1, "found":true, "_source":{
            "name":"Central School", "description":"CBSE Afiliation",
            "street":"Nagan", "city":"paprola", "state":"HP", "zip":"176115",
            "location":[31.8955385,76.8380405], "fees":2000, 
            "tags":["Senior Secondary", "beatiful campus"], "rating":"3.5"
         }
      },
		
      {
         "_index":"schools_gev", "_type":"school", "_id":"2", "error":{
			
            "root_cause":[{
               "type":"index_not_found_exception", "reason":"no such index", 
               "index":"schools_gev"
            }],
				
            "type":"index_not_found_exception", "reason":"no such index", 
            "index":"schools_gev"
         }
      }
   ]
}

Массовое API

Этот API-интерфейс используется для массовой загрузки или удаления объектов JSON путем выполнения нескольких операций индексации / удаления в одном запросе. Нам нужно добавить ключевое слово «_bulk» для вызова этого API. Пример этого API уже выполнен в заполненной статье Elasticsearch. Все остальные функции аналогичны GET API.

59
Share: