Documents - Suggest Post

Служба:: Search Service

Версия API:: 2025-11-01-preview

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

POST {endpoint}/indexes('{indexName}')/docs/search.post.suggest?api-version=2025-11-01-preview

Параметры URI

Имя	В	Обязательно	Тип	Описание
endpoint	path	True	string (uri)	URL-адрес конечной точки службы поиска.
indexName	path	True	string	Имя индекса.
api-version	query	True	string minLength: 1	Версия API, используемая для данной операции.

Заголовок запроса

Имя	Обязательно	Тип	Описание
Accept		Accept	Заголовок Accept.
x-ms-client-request-id		string (uuid)	Непрозрачный, глобально уникальный, созданный клиентом идентификатор строки для запроса.

Текст запроса

Имя	Обязательно	Тип	Описание
search	True	string	Текст поиска, используемый для предложения документов. Должно быть не менее 1 символов и не более 100 символов.
suggesterName	True	string	Имя средства предложения, указанное в коллекции предлагаемых элементов, которые входят в определение индекса.
filter		string	Выражение OData, которое фильтрует рассмотренные документы на предмет предложений.
fuzzy		boolean	Значение, указывающее, следует ли использовать нечеткое сопоставление для запроса предложений. По умолчанию — false. Если задано значение true, запрос будет находить подсказки, даже если в тексте поиска есть замененный или отсутствующий символ. Хотя в некоторых сценариях это обеспечивает более эффективное взаимодействие, это приводит к снижению производительности, так как поиск нечетких предложений выполняется медленнее и потребляет больше ресурсов.
highlightPostTag		string	Тег строки, который добавляется к выделениям попадания. Должен быть установлен с помощью highlightPreTag. Если опущено, подсветка предложений будет отключена.
highlightPreTag		string	Тег string, который добавляется в начало для выделения попадания. Должен быть установлен с помощью highlightPostTag. Если опущено, подсветка предложений будет отключена.
minimumCoverage		number (double)	Число от 0 до 100, указывающее процент индекса, который должен быть покрыт запросом предложений, чтобы запрос был отмечен как успешный. Этот параметр может быть полезен для обеспечения доступности поиска даже для сервисов с одной репликой. Значение по умолчанию — 80.
orderby		string	Разделенный запятыми список OData $orderby выражения, по которым сортируются результаты. Каждое выражение может быть либо именем поля, либо вызовом функций geo.distance() или search.score(). За каждым выражением может следовать asc для обозначения возрастания, или desc для обозначения убывания. По умолчанию используется порядок возрастания. Ничьи будут разбиты по счету матчей документов. Если $orderby не указан, порядок сортировки по умолчанию — по убыванию по счету совпадения документа. Их может быть не более 32 $orderby пунктов.
searchFields		string	Разделенный запятыми список имен полей для поиска указанного искомого текста. Целевые поля должны быть включены в указанный подборщик.
select		string	Список полей, разделенных запятыми, для извлечения. Если не указано, в результаты будет включено только ключевое поле.
top		integer (int32)	Количество предложений для извлечения. Это значение должно быть в диапазоне от 1 до 100. Значение по умолчанию равно 5.

Ответы

Имя	Тип	Описание
200 OK	SuggestDocumentsResult	Запрос выполнен успешно.
Other Status Codes	ErrorResponse	Непредвиденное сообщение об ошибке.

Безопасность

api-key

Тип: apiKey
В: header

OAuth2Auth

Тип: oauth2
Flow: implicit
URL-адрес авторизации: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Области

Имя	Описание
https://search.azure.com/.default

Примеры

SearchIndexSuggestDocumentsPost

Образец запроса

HTTP

POST https://previewexampleservice.search.windows.net/indexes('preview-test')/docs/search.post.suggest?api-version=2025-11-01-preview


{
  "filter": "ownerId eq 'sam' and id lt '15'",
  "fuzzy": true,
  "highlightPostTag": "</em>",
  "highlightPreTag": "<em>",
  "minimumCoverage": 80,
  "orderby": "id desc",
  "search": "p",
  "searchFields": "category",
  "select": "id,name,category,ownerId",
  "suggesterName": "sg",
  "top": 10
}

Пример ответа

Код состояния:: 200

{
  "@search.coverage": 100,
  "value": [
    {
      "@search.text": "<em>pu</em>rple",
      "id": "14",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    },
    {
      "@search.text": "<em>pu</em>rple",
      "id": "13",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    },
    {
      "@search.text": "<em>pu</em>rple",
      "id": "11",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    },
    {
      "@search.text": "<em>pu</em>rple",
      "id": "1",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    }
  ]
}

Определения

Имя	Описание
Accept	Заголовок Accept.
ErrorAdditionalInfo	Дополнительные сведения об ошибке управления ресурсами.
ErrorDetail	Сведения об ошибке.
ErrorResponse	Распространенный ответ об ошибке для всех API Azure Resource Manager для возврата сведений об ошибке для неудачных операций. (Это также следует формату ответа об ошибках OData.).
SuggestDocumentsResult	Ответ, содержащий результаты запроса предложения из индекса.
SuggestRequest	Параметры для фильтрации, сортировки, нечеткого сопоставления и других вариантов поведения запросов.
SuggestResult	Результат, содержащий документ, найденный запросом предложения, а также связанные метаданные.

Accept

Перечисление

Заголовок Accept.

Значение	Описание
application/json;odata.metadata=none

ErrorAdditionalInfo

Объект

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

Имя	Тип	Описание
info		Дополнительная информация.
type	string	Тип дополнительной информации.

ErrorDetail

Объект

Сведения об ошибке.

Имя	Тип	Описание
additionalInfo	ErrorAdditionalInfo[]	Ошибка дополнительная информация.
code	string	Код ошибки.
details	ErrorDetail[]	Сведения об ошибке.
message	string	Сообщение об ошибке.
target	string	Цель ошибки.

ErrorResponse

Объект

Распространенный ответ об ошибке для всех API Azure Resource Manager для возврата сведений об ошибке для неудачных операций. (Это также следует формату ответа об ошибках OData.).

Имя	Тип	Описание
error	ErrorDetail	Объект ошибки.

SuggestDocumentsResult

Объект

Ответ, содержащий результаты запроса предложения из индекса.

Имя	Тип	Описание
@search.coverage	number (double)	Значение, указывающее процент от индекса, который был включен в запрос, или null, если minimumCoverage не был задан в запросе.
value	SuggestResult[]	Последовательность результатов, возвращаемая запросом.

SuggestRequest

Объект

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

Имя	Тип	Описание
filter	string	Выражение OData, которое фильтрует рассмотренные документы на предмет предложений.
fuzzy	boolean	Значение, указывающее, следует ли использовать нечеткое сопоставление для запроса предложений. По умолчанию — false. Если задано значение true, запрос будет находить подсказки, даже если в тексте поиска есть замененный или отсутствующий символ. Хотя в некоторых сценариях это обеспечивает более эффективное взаимодействие, это приводит к снижению производительности, так как поиск нечетких предложений выполняется медленнее и потребляет больше ресурсов.
highlightPostTag	string	Тег строки, который добавляется к выделениям попадания. Должен быть установлен с помощью highlightPreTag. Если опущено, подсветка предложений будет отключена.
highlightPreTag	string	Тег string, который добавляется в начало для выделения попадания. Должен быть установлен с помощью highlightPostTag. Если опущено, подсветка предложений будет отключена.
minimumCoverage	number (double)	Число от 0 до 100, указывающее процент индекса, который должен быть покрыт запросом предложений, чтобы запрос был отмечен как успешный. Этот параметр может быть полезен для обеспечения доступности поиска даже для сервисов с одной репликой. Значение по умолчанию — 80.
orderby	string	Разделенный запятыми список OData $orderby выражения, по которым сортируются результаты. Каждое выражение может быть либо именем поля, либо вызовом функций geo.distance() или search.score(). За каждым выражением может следовать asc для обозначения возрастания, или desc для обозначения убывания. По умолчанию используется порядок возрастания. Ничьи будут разбиты по счету матчей документов. Если $orderby не указан, порядок сортировки по умолчанию — по убыванию по счету совпадения документа. Их может быть не более 32 $orderby пунктов.
search	string	Текст поиска, используемый для предложения документов. Должно быть не менее 1 символов и не более 100 символов.
searchFields	string	Разделенный запятыми список имен полей для поиска указанного искомого текста. Целевые поля должны быть включены в указанный подборщик.
select	string	Список полей, разделенных запятыми, для извлечения. Если не указано, в результаты будет включено только ключевое поле.
suggesterName	string	Имя средства предложения, указанное в коллекции предлагаемых элементов, которые входят в определение индекса.
top	integer (int32)	Количество предложений для извлечения. Это значение должно быть в диапазоне от 1 до 100. Значение по умолчанию равно 5.

SuggestResult

Объект

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

Имя	Тип	Описание
@search.text	string	Текст результата предложения.