- HTTP-запрос
- Тело запроса
- Тело ответа
- Области авторизации
- Параметры интерпретации запроса
- Интерпретация запроса
- QueryInterpretation.InterpretationType
- QueryInterpretation.Причина
- Результат поиска
- Фрагмент
- Диапазон совпадений
- Метаданные
- Результатдисплейметаданные
- ResultDisplayMetadata.ResultDisplayLine
- ResultDisplayMetadata.ResultDisplayField
- Результатдебагинформо
- Структурированный результат
- Результат заклинания
- Фасетрезультат
- FacetBucket
- Ответдебугинформо
- Информация об ошибке
- Сообщение об ошибке
- ResultCounts
- Саурсерсулткунт
- Попробуйте!
Cloud Search Query API предоставляет метод поиска, который возвращает наиболее релевантные результаты по пользовательскому запросу. Результаты могут быть получены из приложений Google Workspace, таких как Gmail или Google Drive, или из данных, проиндексированных вами от третьих лиц.
Примечание. Для выполнения этого API требуется стандартная учетная запись конечного пользователя. Учетная запись службы не может напрямую выполнять запросы API запросов; Чтобы использовать сервисный аккаунт для выполнения запросов, настройте делегирование полномочий Google Workspace на уровне всего домена .
HTTP-запрос
POST https://cloudsearch.googleapis.com/v1/query/search
URL-адрес использует синтаксис транскодирования gRPC .
Тело запроса
Тело запроса содержит данные следующей структуры:
JSON-представление |
---|
{ "requestOptions": { object ( |
Поля | |
---|---|
requestOptions | Параметры запроса, такие как приложение поиска и часовой пояс пользователя. |
query | Необработанная строка запроса. См. поддерживаемые операторы поиска в разделе «Сузьте поиск с помощью операторов». |
pageSize | Максимальное количество результатов поиска, возвращаемых на одной странице. Допустимые значения: от 1 до 100 включительно. Значение по умолчанию — 10. Минимальное значение — 50, если запрашиваются результаты за пределами 2000. |
start | Начальный индекс результатов. |
dataSourceRestrictions[] | Источники, используемые для запросов. Если не указано, используются все источники данных из текущего приложения поиска. |
facetOptions[] | |
sortOptions | Варианты сортировки результатов поиска |
queryInterpretationOptions | варианты интерпретации запроса пользователя. |
contextAttributes[] | Атрибуты контекста запроса, которые будут использоваться для корректировки ранжирования результатов поиска. Максимальное количество элементов — 10. |
Тело ответа
В случае успеха тело ответа содержит данные следующей структуры:
Ответ API поиска.
JSON-представление |
---|
{ "queryInterpretation": { object ( |
Поля | |
---|---|
queryInterpretation | Результат интерпретации запроса пользователя. Пусто, если интерпретация запроса отключена. |
results[] | Результаты поискового запроса. |
structuredResults[] | Структурированные результаты по запросу пользователя. Эти результаты не учитываются в параметре pageSize. |
spellResults[] | Рекомендуемое написание запроса. |
facetResults[] | Повторяющиеся побочные результаты. |
hasMoreResults | Есть ли еще результаты поиска, соответствующие запросу. |
debugInfo | Отладочная информация об ответе. |
errorInfo | Информация об ошибке в ответе. |
resultCounts | Расширенная информация о подсчете результатов. |
Поле объединения
В том редком случае, когда система не может выполнить поиск по всем документам, повторите запрос. | |
resultCountEstimate | Предполагаемое количество результатов для этого запроса. |
resultCountExact | Точное количество результатов для этого запроса. |
Области авторизации
Требуется одна из следующих областей OAuth:
-
https://www.googleapis.com/auth/cloud_search.query
-
https://www.googleapis.com/auth/cloud_search
Дополнительную информацию см. в руководстве по авторизации .
Параметры интерпретации запроса
варианты интерпретации запроса пользователя.
JSON-представление |
---|
{ "disableNlInterpretation": boolean, "enableVerbatimMode": boolean, "disableSupplementalResults": boolean } |
Поля | |
---|---|
disableNlInterpretation | Флаг, отключающий интерпретацию запросов на естественном языке (NL). По умолчанию установлено значение false. Установите значение true, чтобы отключить интерпретацию естественного языка. Интерпретация NL применяется только к предопределенным источникам данных. |
enableVerbatimMode | Включите этот флаг, чтобы отключить все внутренние оптимизации, такие как интерпретация запросов на естественном языке (NL), дополнительный поиск результатов и использование синонимов, включая пользовательские. Интерпретация Nl будет отключена, если хотя бы один из двух флагов истинен. |
disableSupplementalResults | Используйте этот флаг, чтобы отключить дополнительные результаты для запроса. Настройка дополнительных результатов, выбранная на уровне SearchApplication, будет иметь приоритет, если для нее установлено значение True. |
Интерпретация запроса
JSON-представление |
---|
{ "interpretedQuery": string, "interpretationType": enum ( |
Поля | |
---|---|
interpretedQuery | Интерпретация запроса, используемого при поиске. Например, запросы на естественном языке, такие как «электронное письмо от Джона», будут интерпретироваться как «от: источник Джона: почта». Это поле не будет заполнено, если причина — NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY. |
interpretationType | |
reason | Причина интерпретации запроса. Это поле не будет UNSPECIFIED, если тип интерпретации не NONE. |
QueryInterpretation.InterpretationType
Перечисления | |
---|---|
NONE | Ни интерпретация естественного языка, ни более широкая версия запроса не используются для получения результатов поиска. |
BLEND | Результаты исходного запроса смешиваются с другими результатами. Причина объединения этих других результатов с результатами исходного запроса указывается в поле «Причина» ниже. |
REPLACE | Результаты исходного запроса заменяются. Причина замены результатов исходного запроса указывается в поле «Причина» ниже. |
QueryInterpretation.Причина
Перечисления | |
---|---|
UNSPECIFIED | |
QUERY_HAS_NATURAL_LANGUAGE_INTENT | Для получения результатов поиска используется интерпретация запроса на естественном языке. |
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY | Сходство терминов запроса и документа используется для выборочного расширения запроса для получения дополнительных результатов поиска, поскольку для пользовательского запроса не найдено достаточного количества результатов. Интерпретируемый запрос в этом случае будет пустым. |
Результат поиска
Результаты, содержащие индексированную информацию для документа.
JSON-представление |
---|
{ "title": string, "url": string, "snippet": { object ( |
Поля | |
---|---|
title | Название результата поиска. |
url | URL-адрес результата поиска. URL-адрес содержит перенаправление Google на реальный элемент. Этот URL-адрес подписан и не подлежит изменению. |
snippet | Объединение всех фрагментов (сводок), доступных для этого результата. |
metadata | метаданные результата поиска. |
clusteredResults[] | Если источник кластеризован, предоставьте список кластеризованных результатов. Будет только один уровень кластеризованных результатов. Если текущий источник не поддерживает кластеризацию, это поле будет пустым. |
debugInfo | Отладочная информация об этом результате поиска. |
Фрагмент
Фрагмент результата поиска, который обобщает содержимое полученной страницы.
JSON-представление |
---|
{
"snippet": string,
"matchRanges": [
{
object ( |
Поля | |
---|---|
snippet | Фрагмент документа. Фрагмент документа. Может содержать экранированный HTML-символ, который не следует экранировать перед рендерингом. |
matchRanges[] | Соответствующие диапазоны во фрагменте. |
Диапазон совпадений
Соответствующий диапазон фрагмента [начало, конец).
JSON-представление |
---|
{ "start": integer, "end": integer } |
Поля | |
---|---|
start | Начальная позиция матча во фрагменте. |
end | Конец матча в фрагменте. |
Метаданные
метаданные совпавшего результата поиска.
JSON-представление |
---|
{ "source": { object ( |
Поля | |
---|---|
source | Именованный источник результата, например Gmail. |
mimeType | MIME-тип результата поиска. |
thumbnailUrl | URL-адрес миниатюры результата. |
owner | владелец (обычно создатель) документа или объекта результата поиска. |
createTime | Время создания этого документа или объекта в результатах поиска. Временная метка в формате RFC3339 UTC «Зулу» с наносекундным разрешением и до девяти дробных цифр. Примеры: |
updateTime | Дата последнего изменения объекта в результатах поиска. Если он не установлен в элементе, возвращаемое здесь значение пустое. Если Временная метка в формате RFC3339 UTC «Зулу» с наносекундным разрешением и до девяти дробных цифр. Примеры: |
fields[] | Индексированные поля в структурированных данных, возвращаемые как общее именованное свойство. |
displayOptions | параметры, определяющие способ отображения результатов поиска по структурированным данным. |
objectType | Тип объекта результата поиска. |
Результатдисплейметаданные
JSON-представление |
---|
{
"objectTypeLabel": string,
"metalines": [
{
object ( |
Поля | |
---|---|
objectTypeLabel | Отображаемая метка объекта. |
metalines[] | Содержание металинов, которое будет отображаться вместе с результатом. |
ResultDisplayMetadata.ResultDisplayLine
Коллекция полей, составляющих отображаемую строку.
JSON-представление |
---|
{
"fields": [
{
object ( |
Поля | |
---|---|
fields[] | |
ResultDisplayMetadata.ResultDisplayField
Отображение полей для результатов запроса.поиска
JSON-представление |
---|
{
"label": string,
"operatorName": string,
"property": {
object ( |
Поля | |
---|---|
label | Отображаемая метка свойства. |
operatorName | Имя оператора свойства. |
property | Пара имя-значение для свойства. |
Результатдебагинформо
Отладочная информация о результате.
JSON-представление |
---|
{ "formattedDebugInfo": string } |
Поля | |
---|---|
formattedDebugInfo | Общая информация отладки, отформатированная для отображения. |
Структурированный результат
Структурированные результаты, возвращаемые как часть поискового запроса.
JSON-представление |
---|
{
"person": {
object ( |
Поля | |
---|---|
person | Представление человека |
Результат заклинания
JSON-представление |
---|
{ "suggestedQuery": string } |
Поля | |
---|---|
suggestedQuery | Предлагаемое написание запроса. |
Фасетрезультат
Ответ на конкретный аспект источника
JSON-представление |
---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
Поля | |
---|---|
sourceName | Имя источника, для которого возвращаются результаты фасета. Не будет пустовать. |
objectType | Тип объекта, для которого возвращаются результаты фасета. Может быть пустым. |
operatorName | Имя оператора, выбранного для фасетирования. @see Cloudsearch.SchemaPropertyOptions |
buckets[] | FacetBuckets для значений в ответе, содержащих хотя бы один результат с соответствующим фильтром. |
FacetBucket
Ковш в фаце является основной рабочей единицей. Сегмент может содержать либо одно значение, либо непрерывный диапазон значений, в зависимости от типа поля, включаемого в сегмент. FacetBucket в настоящее время используется только для возврата объекта ответа.
JSON-представление |
---|
{ "count": integer, "percentage": integer, "filter": { object ( |
Поля | |
---|---|
count | Количество результатов, соответствующих значению сегмента. Числа возвращаются для поиска только в том случае, если гарантируется точность подсчета. Cloud Search не гарантирует подсчет фасетов для любого запроса, а счетчик фасетов может присутствовать только время от времени, даже для идентичных запросов. Не создавайте зависимости от существования количества фасетов; вместо этого используйте проценты подсчета фасетов, которые всегда возвращаются. |
percentage | Процент результатов, соответствующих значению сегмента. Возвращаемое значение находится в диапазоне (0–100) и округляется до целого числа, если оно дробное. Если значение не возвращается явно, оно представляет собой процентное значение, которое округляется до 0. Проценты возвращаются для всех поисков, но являются приблизительными. . Поскольку проценты всегда возвращаются, вам следует отображать проценты, а не числа. |
filter | Фильтр, который будет передан в поисковом запросе, если выбран соответствующий сегмент. |
value | |
Ответдебугинформо
Отладочная информация об ответе.
JSON-представление |
---|
{ "formattedDebugInfo": string } |
Поля | |
---|---|
formattedDebugInfo | Общая информация об отладке, отформатированная для отображения. |
Информация об ошибке
Информация об ошибке в ответе.
JSON-представление |
---|
{
"errorMessages": [
{
object ( |
Поля | |
---|---|
errorMessages[] | |
Сообщение об ошибке
Сообщение об ошибке для каждого ответа источника.
JSON-представление |
---|
{
"source": {
object ( |
Поля | |
---|---|
source | |
errorMessage | |
ResultCounts
Информация о подсчете результатов
JSON-представление |
---|
{
"sourceResultCounts": [
{
object ( |
Поля | |
---|---|
sourceResultCounts[] | Информация о количестве результатов для каждого источника с результатами. |
Саурсерсулткаунт
Информация о подсчете результатов для каждого источника.
JSON-представление |
---|
{ "source": { object ( |
Поля | |
---|---|
source | Источник, с которым связана информация о подсчете результатов. |
hasMoreResults | Есть ли еще результаты поиска для этого источника. |
Поле объединения | |
resultCountEstimate | Предполагаемое количество результатов для этого источника. |
resultCountExact | Точное количество результатов для этого источника. |