Схемы API

REST API Elasticsearch реализованы через HTTP. За исключением случаев, когда указано иное, следующие соглашения применяются ко всем API.

Тип содержимого, отправляемого в теле запроса, должен быть указан с помощью заголовка Content-Type. Значение этого заголовка должно соответствовать одному из поддерживаемых форматов, которые поддерживает API. Большинство API поддерживают JSON, YAML, CBOR и SMILE. API bulk и multi-search поддерживают NDJSON, JSON и SMILE; другие типы приведут к ошибочному ответу.

При использовании параметра строки запроса source тип содержимого должен быть указан с помощью параметра строки запроса source_content_type.

Elasticsearch поддерживает только UTF-8 кодировку JSON. Elasticsearch игнорирует любые другие кодировки, отправленные с запросом. Ответы также кодируются в UTF-8.

Вы можете передать заголовок X-Opaque-Id HTTP для отслеживания источника запроса в журналах и задачах Elasticsearch. Если он предоставлен, Elasticsearch отобразит значение X-Opaque-Id в:

Для журналов устаревания Elasticsearch также использует значение X-Opaque-Id для ограничения и удаления дубликатов предупреждений об устаревании. См. Ограничение журналов устаревания.

Заголовок X-Opaque-Id принимает любое произвольное значение. Однако рекомендуется ограничить эти значения конечным набором, например, ID на клиент. Не генерируйте уникальный заголовок X-Opaque-Id для каждого запроса. Слишком много уникальных значений заголовка X-Opaque-Id может помешать Elasticsearch удалять дублирующие предупреждения в журналах устаревания.

Elasticsearch также поддерживает заголовок traceparent HTTP, используя официальную спецификацию контекста трассировки W3C. Вы можете использовать заголовок traceparent для отслеживания запросов через продукты Elastic и другие сервисы. Поскольку он используется только для отслеживания, вы можете безопасно генерировать уникальный заголовок traceparent для каждого запроса.

Если предоставлен, Elasticsearch отображает значение заголовка trace-id как trace.id в:

Например, следующее значение traceparent приведет к следующему значению trade.id в приведенных выше журналах.

`traceparent`: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
`trace.id`: 0af7651916cd43dd8448eb211c80319c

Ряд API Elasticsearch GET — в частности, API поиска — поддерживает тело запроса. Хотя действие GET имеет смысл в контексте получения информации, GET-запросы с телом не поддерживаются всеми библиотеками HTTP. Все API Elasticsearch GET, которые требуют тела, также могут быть отправлены как POST-запросы. Кроме того, вы можете передать тело запроса как source параметр строки запроса при использовании GET.

Основные обновления версий часто включают ряд несовместимых изменений, которые влияют на взаимодействие с Elasticsearch. Хотя мы рекомендуем следить за журналами устаревания и обновлять приложения перед обновлением Elasticsearch, координация необходимых изменений может быть препятствием для обновления.

Вы можете настроить существующее приложение для работы без изменений после обновления, включив заголовки совместимости API, которые сообщают Elasticsearch, что вы все еще используете предыдущую версию REST API. Использование этих заголовков позволяет структуре запросов и ответов остаться прежней; это не гарантирует одинакового поведения.

Вы устанавливаете совместимость версий на основе каждого запроса в заголовках Content-Type и Accept. Установка compatible-with на ту же основную версию, что и у вашей текущей версии, не повлияет на работу, но гарантирует, что запрос по-прежнему будет работать после обновления Elasticsearch.

Чтобы сообщить Elasticsearch 8.0, что вы используете формат запросов и ответов 7.x, установите compatible-with=7:

Content-Type: application/vnd.elasticsearch+json; compatible-with=7
Accept: application/vnd.elasticsearch+json; compatible-with=7