Предложения (REST API поиска Azure ИИ)
Запрос предложений — это запрос типа поиска, который ищет совпадающие значения в полях с поддержкой средства подбора и возвращает документы, содержащие совпадение. Например, если вы включите предложения в поле города , при вводе "sea" будут создаваться документы, содержащие "Сиэтл", "Sea Tac" и "Приморский" (все фактические названия городов) для этого поля.
Ответ — это содержимое из соответствующего документа и ключа документа. В отличие от автозаполнения, которая возвращает завершенный термин или фразу, используемую во вторичном запросе, этот запрос возвращает сведения, которые разрешаются в фактические документы. Если совпадающие термины или фразы идентичны в документах, совпадающее содержимое повторяется. Чтобы улучшить структуру результатов, рассмотрите $select возможность использования фильтра для возврата дополнительных полей, которые обеспечивают большую дифференциацию и контекст.
Запросы к службе отправляются по протоколу HTTPS. Запрос Suggest можно создать с помощью методов GET или POST.
GET https://[service name].search.windows.net/indexes/[index name]/docs/suggest?[query parameters]
Content-Type: application/json
api-key: [admin or query key]
POST https://[service name].search.windows.net/indexes/[index name]/docs/suggest?api-version=[api-version]
Content-Type: application/json
api-key: [admin or query key]
В отличие от запроса "Поиск документов" , вы можете привязать вызов Предложения к вводу с клавиатуры, тогда как вызов Поиска может быть привязан к событию щелчка.
При вызове с помощью GET длина URL-адреса запроса не может превышать 8 КБ. Обычно такой длины достаточно для большинства приложений. Однако некоторые приложения создают очень большие запросы, особенно при использовании выражений фильтра OData. Для этих приложений http POST является лучшим выбором, так как он позволяет использовать фильтры большего размера, чем GET.
При использовании запроса POST ограничивающим фактором является количество предложений в запросе, а не необработанная строка фильтра, так как предельный размер запроса для POST ограничен примерно 16 МБ. Даже несмотря на то, что размер запроса POST очень большой, выражения фильтров не могут иметь произвольную сложность. Дополнительные сведения об ограничениях сложности фильтра см. в статье Синтаксис выражений OData для поиска ИИ Azure.
Параметры URI
| Параметр | Описание |
|---|---|
| [имя службы] | Обязательный. Задайте уникальное, определяемое пользователем имя службы поиска. |
| [имя индекса]/docs | Обязательный. Указывает коллекцию документов именованного индекса. |
| api-version | Обязательный. Текущая стабильная версия — api-version=2020-06-30. Дополнительные версии см. в разделе Версии API . Для запросов версия API всегда указывается в качестве параметра URI для GET и POST. |
Рекомендации по кодированию URL-адресов
Не забудьте закодировать определенные параметры запроса по URL-адресу при непосредственном вызове REST API GET. Для операций вызова предложений эти параметры указаны ниже.
- search
- $filter
- highlightPreTag
- highlightPostTag
Кодировка URL-адреса рекомендуется только для отдельных параметров. Если вы случайно URL-кодировали всю строку запроса (все после ?), запросы будут нарушены.
Кроме того, преобразование в кодировку URL необходимо только при непосредственном обращении к API REST с помощью запроса GET. Кодирование URL-адресов не требуется при вызове предложений с помощью POST или при использовании клиентской библиотеки .NET для поиска ИИ Azure , обрабатывающего кодирование URL-адресов.
Заголовки запросов
Таблица ниже содержит обязательные и необязательные заголовки запроса.
| Поля | Описание |
|---|---|
| Content-Type | Обязательный. Для этого заголовка необходимо задать значение application/json |
| api-key | Необязательно, если вы используете роли Azure и в запросе предоставляется маркер носителя, в противном случае требуется ключ. Ключ API — это уникальная, созданная системой строка, которая проверяет подлинность запроса к службе поиска. Запросы к коллекции документов могут указывать ключ администратора или ключ запроса в качестве ключа API. Ключ запроса используется для операций только для чтения в коллекции документов. Дополнительные сведения см. в статье Подключение к поиску ИИ Azure с помощью проверки подлинности по ключу . |
Текст запроса
Для запроса GET: нет.
Для запроса POST:
{
"filter": "odata_filter_expression",
"fuzzy": true | false (default),
"highlightPreTag": "pre_tag",
"highlightPostTag": "post_tag",
"minimumCoverage": # (% of index that must be covered to declare query successful; default 80),
"orderby": "orderby_expression",
"search": "partial_search_input",
"searchFields": "field_name_1, field_name_2, ...",
"select": "field_name_1, field_name_2, ...",
"suggesterName": "suggester_name",
"top": # (default 5)
}
Параметры запроса
Запрос принимает несколько параметров в URL-адресе при вызове с помощью GET и в качестве свойств JSON в тексте запроса при вызове с помощью POST. Синтаксис некоторых параметров зависит от выбора запроса GET и POST. Эти различия приведены ниже.
| Имя | Тип | Описание |
|---|---|---|
| api-version | строка | Обязательный. Версия REST API, используемая для запроса. Список поддерживаемых версий см. в разделе Версии API. Для этой операции версия api указывается в качестве параметра запроса в URL-адресе независимо от того, вызывается ли API с помощью GET или POST. |
| $filter | строка | Необязательный параметр. Выражение, фильтрующее документы, рассматриваемые для предложений. В фильтре можно использовать только фильтруемые поля. Выражения фильтра "search.ismatch" и "search.ismatchscoring*" не поддерживаются в API автозаполнения. При вызове с помощью POST этот параметр называется filter вместо $filter. Дополнительные сведения о подмножестве грамматики выражений OData, поддерживаемых поиском ИИ Azure, см. в статье Синтаксис выражений OData для поиска ИИ Azure . |
| Нечеткой | Логическое | Необязательный элемент. Значение по умолчанию — false. Если задано значение true, этот API находит предложения, даже если в тексте поиска есть заменяющий или отсутствующий символ. Расстояние редактирования равно 1 для каждой строки запроса. Если строка запроса состоит из нескольких терминов, во всей строке может быть только один отсутствующий, дополнительный, замененный или транспонированный символ. Включение нечеткого соответствия может быть более подходящим в некоторых сценариях. Это стоить за производительность, так как поиск нечетких предложений выполняется медленнее и потребляет больше ресурсов. |
| highlightPostTag | строка | Необязательный параметр. По умолчанию используется пустая строка. Строковый тег, добавляющий к выделенному термину. Необходимо задать параметр highlightPreTag. Зарезервированные символы в составе URL должно быть экранированы знаком процента (например, %23 вместо #). При вызове с помощью GET зарезервированные символы в URL-адресе должны быть закодированы в процентах (например, %23 вместо #). |
| highlightPreTag | строка | Необязательный параметр. По умолчанию используется пустая строка. Строковый тег, который добавляется к выделенному термину. Должен быть задан с параметром highlightPostTag. При вызове с помощью GET зарезервированные символы в URL-адресе должны быть закодированы в процентах (например, %23 вместо #). |
| $orderby | строка | Необязательный параметр. Список выражений, разделенных запятыми, для сортировки результатов по ним. Выражение может быть именем поля или вызовом функции geo.distance() . За каждым выражением может следовать "asc" (по возрастанию) или "desc" (по убыванию). По умолчанию результаты сортируются по возрастанию. Существует ограничение в 32 предложения для $orderby. При вызове с помощью POST этот параметр называется order вместо $orderby. |
| minimumCoverage | Целое число | Необязательный элемент. Значение по умолчанию — 80. Число от 0 до 100, указывающее процент индекса, который должен быть доступен для обслуживания запроса, прежде чем его можно будет сообщить об успешном выполнении. Значение по умолчанию отражает смещение в сторону скорости и эффективности по сравнению с полным охватом. Сокращение охвата ограничивает расширение запросов, позволяя быстрее возвращать результаты. Это также позволяет выполнить запрос при частичной доступности индекса, даже если один сегмент медленно отвечает или недоступен из-за проблем с работоспособностью службы или обслуживания индекса. Независимо от значения minimumCoverage, этот процент индекса должен быть доступен, или предложения возвращают код состояния HTTP 503. Если предложения завершатся успешно на минимальном уровнеCoverage, он возвращает HTTP 200 и включает @search.coverage в ответ значение, указывающее процент индекса, который был доступен при обслуживании запроса. Уменьшение этого значения может быть полезным, если возникают ошибки 503. В противном случае можно рассмотреть возможность повышения значения, если в ответе недостаточно совпадений. |
| search | строка | Обязательный. Текст для поиска, используемый для предложения запросов. Минимальная длина — 1 символ, максимальная — 100 символов. Он не может содержать операторы, синтаксис запросов или фразы, заключенные в кавычки. |
| searchFields | строка | Необязательный параметр. Список имен полей, разделенных запятой, для поиска указанного текста. Целевые поля должны быть указаны в определении средства подбора в индексе. |
| $select | строка | Необязательный параметр. Список полей для получения, разделенных запятыми. Если это не указано, возвращаются только ключ документа и текст предложения. Чтобы явным образом запросить все поля, задайте для этого параметра значение *. При вызове с помощью POST этот параметр называется select вместо $select. |
| suggesterName | строка | Обязательный. Имя средства подбора, указанное в коллекции Средств подбора , которая является частью определения индекса. Средство подбора определяет, какие поля проверяются на наличие предлагаемых терминов запроса. |
| $top | Целое число | Необязательный элемент. Значение по умолчанию — 5). Количество автозавершенных предложений, которые требуется извлечь. Значение должно быть числом от 1 до 100. При вызове с помощью POST этот параметр называется top, а не $top. |
Ответ
Код состояния: "200 OK" возвращается для успешного ответа.
{
"@search.coverage": # (if minimumCoverage was provided in the query),
"value": [
{
"@search.text": "...",
"<key field>": "..."
},
...
]
}
Если для извлечения полей используется параметр проекции, поля включаются в каждый элемент массива:
{
"value": [
{
"@search.text": "...",
"<key field>": "..."
<other projected data fields>
},
...
]
}
Примеры
Получение 5 предложений при вводе частичного условия поиска lux.
GET /indexes/hotels/docs/suggest?search=lux&$top=5&suggesterName=sg&api-version=2020-06-30
POST /indexes/hotels/docs/suggest?api-version=2020-06-30
{
"search": "lux",
"top": 5,
"suggesterName": "sg"
}
Обратите внимание, что в операции Suggestions требуется suggesterName .