Конвенции API

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

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

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

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

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

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

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

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

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

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

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

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

Выражение cron — это строка следующего формата:

    <seconds> <minutes> <hours> <day_of_month> <month> <day_of_week> [year]

Elasticsearch использует парсер cron из Quartz Job Scheduler. Дополнительную информацию о написании выражений cron Quartz см. в руководстве Quartz CronTrigger.

Все временные интервалы расписания заданы в координированном универсальном времени (UTC); другие часовые пояса не поддерживаются.

Все элементы обязательны, за исключением year. См. специальные символы cron для получения информации о разрешенных специальных символах.

Разрешение имён математики дат позволяет вам искать диапазон временных рядов индексов или алиасов индексов, а не искать все ваши индексы и фильтровать результаты. Ограничение числа ищущих индексов уменьшает нагрузку на кластер и улучшает производительность поиска. Например, если вы ищете ошибки в ваших ежедневных журналах, вы можете использовать шаблон имени математики дат, чтобы ограничить поиск двумя предыдущими днями.

Большинство API, принимающих аргумент индекса или алиаса индекса, поддерживают математику дат. Имя математики дат имеет следующий вид:

<static_name{date_math_expr{date_format|time_zone}}>

Где:

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

Вы должны заключить имена математики дат в угловые скобки. Если вы используете имя в пути запроса, специальные символы должны быть закодированы в URI. Например:

resp = client.indices.create(
    index="<my-index-{now/d}>",
)
print(resp)

response = client.indices.create(
  index: '<my-index-{now/d}>'
)
puts response

const response = await client.indices.create({
  index: "<my-index-{now/d}>",
});
console.log(response);

# PUT /<my-index-{now/d}>
PUT /%3Cmy-index-%7Bnow%2Fd%7D%3E

Следующий пример демонстрирует различные формы имён математики дат и итоговые имена, к которым они приводят, если текущее время — полдень UTC 22 марта 2024 года.

Для использования символов { и } в статической части шаблона имени, экранируйте их обратной косой чертой \, например:

Следующий пример демонстрирует запрос поиска в индексах Logstash за последние три дня, предполагая, что индексы используют стандартный формат имени индекса Logstash, logstash-YYYY.MM.dd.

$params = [
    'index' => '%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E',
    'body' => [
        'query' => [
            'match' => [
                'test' => 'data',
            ],
        ],
    ],
];
$response = $client->search($params);

resp = client.search(
    index="<logstash-{now/d-2d}>,<logstash-{now/d-1d}>,<logstash-{now/d}>",
    query={
        "match": {
            "test": "data"
        }
    },
)
print(resp)

response = client.search(
  index: '<logstash-{now/d-2d}>,<logstash-{now/d-1d}>,<logstash-{now/d}>',
  body: {
    query: {
      match: {
        test: 'data'
      }
    }
  }
)
puts response

res, err := es.Search(
	es.Search.WithIndex("%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E"),
	es.Search.WithBody(strings.NewReader(`{
	  "query": {
	    "match": {
	      "test": "data"
	    }
	  }
	}`)),
	es.Search.WithPretty(),
)
fmt.Println(res, err)

const response = await client.search({
  index: "<logstash-{now/d-2d}>,<logstash-{now/d-1d}>,<logstash-{now/d}>",
  query: {
    match: {
      test: "data",
    },
  },
});
console.log(response);

# GET /<logstash-{now/d-2d}>,<logstash-{now/d-1d}>,<logstash-{now/d}>/_search
GET /%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E/_search
{
  "query" : {
    "match": {
      "test": "data"
    }
  }
}

Большинство API, которые принимают параметр пути запроса <data-stream>, <index> или <target>, также поддерживают синтаксис для нескольких целей.

В синтаксисе для нескольких целей вы можете использовать список, разделенный запятыми, для выполнения запроса на нескольких ресурсах, таких как потоки данных, индексы или псевдонимы: test1,test2,test3. Вы также можете использовать шаблоны, похожие на glob (*), чтобы нацеливаться на ресурсы, которые соответствуют шаблону: test* или *test или te*t или *test*.

Вы можете исключить цели, используя символ -: test*,-test3.

Вы также можете исключить кластеры из списка кластеров для поиска, используя символ -: remote*:*,-remote1:*,-remote4:* будет искать все кластеры с псевдонимом, начинающимся с "remote", за исключением "remote1" и "remote4". Обратите внимание, что для исключения кластера с помощью этой нотации необходимо исключить все его индексы. Исключение подмножества индексов в удалённом кластере в настоящее время не поддерживается. Например, это вызовет исключение: remote*:*,-remote1:logs*.

Многоцелевые API, которые могут нацеливаться на индексы, поддерживают следующие параметры запроса:

Значения параметров по умолчанию зависят от используемого API.

Некоторые многоцелевые API, которые могут нацеливаться на индексы, также поддерживают следующий параметр запроса:

Для большинства API шаблоны, похожие на glob, по умолчанию не соответствуют скрытым потокам данных и индексам. Чтобы шаблоны, похожие на glob, соответствовали скрытым потокам данных и индексам, необходимо указать параметр запроса expand_wildcards.

В качестве альтернативы, поиск шаблона индекса, начинающегося с точки, например, .watcher_hist*, по умолчанию будет соответствовать скрытым индексам. Это призвано отражать поведение Unix file-globbing и обеспечить более плавный переход к скрытым индексам.

Вы можете создать скрытые потоки данных, установив data_stream.hidden в значение true в соответствующем шаблоне индекса index.hidden. Вы можете скрыть индексы, используя настройку индекса index.hidden.

Поддерживающие индексы потоков данных скрываются автоматически. Некоторые функции, такие как машинное обучение, хранят информацию в скрытых индексах.

Глобальные шаблоны индексов, соответствующие всем индексам, не применяются к скрытым индексам.

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

Для просмотра системных индексов в кластере:

resp = client.cluster.state(
    metric="metadata",
    filter_path="metadata.indices.*.system",
)
print(resp)

const response = await client.cluster.state({
  metric: "metadata",
  filter_path: "metadata.indices.*.system",
});
console.log(response);

GET _cluster/state/metadata?filter_path=metadata.indices.*.system

Параметры REST (при использовании HTTP, сопоставляются с параметрами HTTP URL) следуют соглашению об использовании нижнего подчеркивания.

Для библиотек, которые не принимают тело запроса для запросов, отличных от POST, вы можете передать тело запроса как параметр строки запроса source вместо этого. При использовании этого метода параметр source_content_type также должен быть передан со значением типа носителя, которое указывает формат источника, например application/json.

Обновления основных версий часто включают ряд несовместимых изменений, которые влияют на то, как вы взаимодействуете с 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

API Elasticsearch могут отвечать кодом состояния HTTP 429 Too Many Requests, указывая, что кластер слишком занят, чтобы обработать запрос. В этом случае попробуйте повторить запрос через небольшую задержку. Если повторный запрос также получает ответ 429 Too Many Requests, увеличьте задержку, применяя экспоненциальное увеличение задержки перед каждым последующим повторением.

Многие пользователи используют прокси с управлением доступом на основе URL для защиты доступа к потокам данных и индексам Elasticsearch. Для запросов многократного поиска, многократного получения и bulk запросов пользователь может указать поток данных или индекс как в URL, так и в теле каждого запроса. Это может затруднить управление доступом на основе URL.

Чтобы предотвратить переопределение потока данных или индекса, указанного в URL, установите значение rest.action.multi.allow_explicit_index на false в elasticsearch.yml.

Это заставит Elasticsearch отклонять запросы, которые явно указывают поток данных или индекс в теле запроса.

Все параметры REST API (как параметры запроса, так и тело JSON) поддерживают предоставление булевого значения «false» в качестве значения false и булевого значения «true» в качестве значения true. Все остальные значения приведут к ошибке.

При передаче числового параметра в теле запроса вы можете использовать строку string, содержащую число, вместо числового типа данных. Например:

resp = client.search(
    size="1000",
)
print(resp)

response = client.search(
  body: {
    size: '1000'
  }
)
puts response

const response = await client.search({
  size: 1000,
});
console.log(response);

POST /_search
{
  "size": "1000"
}

Целочисленные поля в теле ответа описаны как integer (или иногда как long) в этом руководстве, но в целом нет явных ограничений на такие значения. JSON, SMILE, CBOR и YAML допускают произвольно большие целочисленные значения. Не предполагайте, что поля integer в теле ответа всегда будут помещаться в 32-битное знаковое целое число.

Всякий раз, когда необходимо указать размер данных в байтах, например, при установке параметра размера буфера, значение должно указывать единицу измерения, например, 10kb для 10 килобайт. Обратите внимание, что эти единицы используют степени числа 1024, поэтому 1kb означает 1024 байта. Поддерживаемые единицы:

В тех случаях, когда необходимо указать расстояния, например, параметр distance в запросе на расстояние по геоданным, по умолчанию используется метры, если единица не указана. Расстояния можно указывать в других единицах, таких как "1km" или "2mi" (2 мили).

Полный список единиц приведен ниже:

Всякий раз, когда необходимо указывать продолжительность, например, для параметра timeout, продолжительность должна указывать единицу измерения, например, 2d для 2 дней. Поддерживаемые единицы:

Безразмерные величины означают, что у них нет «единиц» типа «байты» или «Герц» или «метр» или «тонна».

Если одна из этих величин велика, мы выведем её как 10m для 10 000 000 или 7k для 7 000. Но мы все равно выведем 87, когда имеем в виду 87. Вот поддерживаемые множители: