Method: query.search

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": string,
  "pageSize": integer,
  "start": integer,
  "dataSourceRestrictions": [
    {
      object (DataSourceRestriction)
    }
  ],
  "facetOptions": [
    {
      object (FacetOptions)
    }
  ],
  "sortOptions": {
    object (SortOptions)
  },
  "queryInterpretationOptions": {
    object (QueryInterpretationOptions)
  },
  "contextAttributes": [
    {
      object (ContextAttribute)
    }
  ]
}
Поля
requestOptions

object ( RequestOptions )

Параметры запроса, такие как приложение поиска и часовой пояс пользователя.

query

string

Необработанная строка запроса. См. поддерживаемые операторы поиска в разделе «Сузьте поиск с помощью операторов».

pageSize

integer

Максимальное количество результатов поиска, возвращаемых на одной странице. Допустимые значения: от 1 до 100 включительно. Значение по умолчанию — 10. Минимальное значение — 50, если запрашиваются результаты за пределами 2000.

start

integer

Начальный индекс результатов.

dataSourceRestrictions[]

object ( DataSourceRestriction )

Источники, используемые для запросов. Если не указано, используются все источники данных из текущего приложения поиска.

facetOptions[]

object ( FacetOptions )

sortOptions

object ( SortOptions )

Варианты сортировки результатов поиска

queryInterpretationOptions

object ( QueryInterpretationOptions )

варианты интерпретации запроса пользователя.

contextAttributes[]

object ( ContextAttribute )

Атрибуты контекста запроса, которые будут использоваться для корректировки ранжирования результатов поиска. Максимальное количество элементов — 10.

Тело ответа

В случае успеха тело ответа содержит данные следующей структуры:

Ответ API поиска.

JSON-представление 
{
  "queryInterpretation": {
    object (QueryInterpretation)
  },
  "results": [
    {
      object (SearchResult)
    }
  ],
  "structuredResults": [
    {
      object (StructuredResult)
    }
  ],
  "spellResults": [
    {
      object (SpellResult)
    }
  ],
  "facetResults": [
    {
      object (FacetResult)
    }
  ],
  "hasMoreResults": boolean,
  "debugInfo": {
    object (ResponseDebugInfo)
  },
  "errorInfo": {
    object (ErrorInfo)
  },
  "resultCounts": {
    object (ResultCounts)
  },

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
Поля
queryInterpretation

object ( QueryInterpretation )

Результат интерпретации запроса пользователя. Пусто, если интерпретация запроса отключена.

results[]

object ( SearchResult )

Результаты поискового запроса.

structuredResults[]

object ( StructuredResult )

Структурированные результаты по запросу пользователя. Эти результаты не учитываются в параметре pageSize.

spellResults[]

object ( SpellResult )

Рекомендуемое написание запроса.

facetResults[]

object ( FacetResult )

Повторяющиеся побочные результаты.

hasMoreResults

boolean

Есть ли еще результаты поиска, соответствующие запросу.

debugInfo

object ( ResponseDebugInfo )

Отладочная информация об ответе.

errorInfo

object ( ErrorInfo )

Информация об ошибке в ответе.

resultCounts

object ( ResultCounts )

Расширенная информация о подсчете результатов.

Поле объединения result_count . Общее количество результатов по всем запрошенным источникам данных. Опускается, если в набор запрашиваемых источников данных включены предопределенные источники. Количество результатов может быть возвращено в виде оценки, а не точного значения, в следующих случаях:

  • Когда запрос содержит более двух терминов во фразе, например «точное количество результатов» в кавычках.

  • Когда количество уникальных списков ACL результатов поиска, которые необходимо оценить, слишком велико для вычисления с разумной задержкой.

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

resultCountEstimate

string ( int64 format)

Предполагаемое количество результатов для этого запроса.

resultCountExact

string ( int64 format)

Точное количество результатов для этого запроса.

Области авторизации

Требуется одна из следующих областей OAuth:

  • https://www.googleapis.com/auth/cloud_search.query
  • https://www.googleapis.com/auth/cloud_search

Дополнительную информацию см. в руководстве по авторизации .

Параметры интерпретации запроса

варианты интерпретации запроса пользователя.

JSON-представление 
{
  "disableNlInterpretation": boolean,
  "enableVerbatimMode": boolean,
  "disableSupplementalResults": boolean
}
Поля
disableNlInterpretation

boolean

Флаг, отключающий интерпретацию запросов на естественном языке (NL). По умолчанию установлено значение false. Установите значение true, чтобы отключить интерпретацию естественного языка. Интерпретация NL применяется только к предопределенным источникам данных.

enableVerbatimMode

boolean

Включите этот флаг, чтобы отключить все внутренние оптимизации, такие как интерпретация запросов на естественном языке (NL), дополнительный поиск результатов и использование синонимов, включая пользовательские. Интерпретация Nl будет отключена, если хотя бы один из двух флагов истинен.

disableSupplementalResults

boolean

Используйте этот флаг, чтобы отключить дополнительные результаты для запроса. Настройка дополнительных результатов, выбранная на уровне SearchApplication, будет иметь приоритет, если для нее установлено значение True.

Интерпретация запроса

JSON-представление 
{
  "interpretedQuery": string,
  "interpretationType": enum (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason)
}
Поля
interpretedQuery

string

Интерпретация запроса, используемого при поиске. Например, запросы на естественном языке, такие как «электронное письмо от Джона», будут интерпретироваться как «от: источник Джона: почта». Это поле не будет заполнено, если причина — NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.

interpretationType

enum ( QueryInterpretation.InterpretationType )

reason

enum ( QueryInterpretation.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 (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
Поля
title

string

Название результата поиска.

url

string

URL-адрес результата поиска. URL-адрес содержит перенаправление Google на реальный элемент. Этот URL-адрес подписан и не подлежит изменению.

snippet

object ( Snippet )

Объединение всех фрагментов (сводок), доступных для этого результата.

metadata

object ( Metadata )

метаданные результата поиска.

clusteredResults[]

object ( SearchResult )

Если источник кластеризован, предоставьте список кластеризованных результатов. Будет только один уровень кластеризованных результатов. Если текущий источник не поддерживает кластеризацию, это поле будет пустым.

debugInfo

object ( ResultDebugInfo )

Отладочная информация об этом результате поиска.

Фрагмент

Фрагмент результата поиска, который обобщает содержимое полученной страницы.

JSON-представление 
{
  "snippet": string,
  "matchRanges": [
    {
      object (MatchRange)
    }
  ]
}
Поля
snippet

string

Фрагмент документа. Фрагмент документа. Может содержать экранированный HTML-символ, который не следует экранировать перед рендерингом.

matchRanges[]

object ( MatchRange )

Соответствующие диапазоны во фрагменте.

Диапазон совпадений

Соответствующий диапазон фрагмента [начало, конец).

JSON-представление 
{
  "start": integer,
  "end": integer
}
Поля
start

integer

Начальная позиция матча во фрагменте.

end

integer

Конец матча в фрагменте.

Метаданные

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

JSON-представление 
{
  "source": {
    object (Source)
  },
  "mimeType": string,
  "thumbnailUrl": string,
  "owner": {
    object (Person)
  },
  "createTime": string,
  "updateTime": string,
  "fields": [
    {
      object (NamedProperty)
    }
  ],
  "displayOptions": {
    object (ResultDisplayMetadata)
  },
  "objectType": string
}
Поля
source

object ( Source )

Именованный источник результата, например Gmail.

mimeType

string

MIME-тип результата поиска.

thumbnailUrl

string

URL-адрес миниатюры результата.

owner

object ( Person )

владелец (обычно создатель) документа или объекта результата поиска.

createTime

string ( Timestamp format)

Время создания этого документа или объекта в результатах поиска.

Временная метка в формате RFC3339 UTC «Зулу» с наносекундным разрешением и до девяти дробных цифр. Примеры: "2014-10-02T15:01:23Z" и "2014-10-02T15:01:23.045123456Z" .

updateTime

string ( Timestamp format)

Дата последнего изменения объекта в результатах поиска. Если он не установлен в элементе, возвращаемое здесь значение пустое. Если updateTime используется для расчета актуальности и не установлен, это значение по умолчанию равно 2 годам от текущего времени.

Временная метка в формате RFC3339 UTC «Зулу» с наносекундным разрешением и до девяти дробных цифр. Примеры: "2014-10-02T15:01:23Z" и "2014-10-02T15:01:23.045123456Z" .

fields[]

object ( NamedProperty )

Индексированные поля в структурированных данных, возвращаемые как общее именованное свойство.

displayOptions

object ( ResultDisplayMetadata )

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

objectType

string

Тип объекта результата поиска.

Результатдисплейметаданные

JSON-представление 
{
  "objectTypeLabel": string,
  "metalines": [
    {
      object (ResultDisplayMetadata.ResultDisplayLine)
    }
  ]
}
Поля
objectTypeLabel

string

Отображаемая метка объекта.

metalines[]

object ( ResultDisplayMetadata.ResultDisplayLine )

Содержание металинов, которое будет отображаться вместе с результатом.

ResultDisplayMetadata.ResultDisplayLine

Коллекция полей, составляющих отображаемую строку.

JSON-представление 
{
  "fields": [
    {
      object (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
Поля
fields[]

object ( ResultDisplayMetadata.ResultDisplayField )

ResultDisplayMetadata.ResultDisplayField

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

JSON-представление 
{
  "label": string,
  "operatorName": string,
  "property": {
    object (NamedProperty)
  }
}
Поля
label

string

Отображаемая метка свойства.

operatorName

string

Имя оператора свойства.

property

object ( NamedProperty )

Пара имя-значение для свойства.

Результатдебагинформо

Отладочная информация о результате.

JSON-представление 
{
  "formattedDebugInfo": string
}
Поля
formattedDebugInfo

string

Общая информация отладки, отформатированная для отображения.

Структурированный результат

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

JSON-представление 
{
  "person": {
    object (Person)
  }
}
Поля
person

object ( Person )

Представление человека

Результат заклинания

JSON-представление 
{
  "suggestedQuery": string
}
Поля
suggestedQuery

string

Предлагаемое написание запроса.

Фасетрезультат

Ответ на конкретный аспект источника

JSON-представление 
{
  "sourceName": string,
  "objectType": string,
  "operatorName": string,
  "buckets": [
    {
      object (FacetBucket)
    }
  ]
}
Поля
sourceName

string

Имя источника, для которого возвращаются результаты фасета. Не будет пустовать.

objectType

string

Тип объекта, для которого возвращаются результаты фасета. Может быть пустым.

operatorName

string

Имя оператора, выбранного для фасетирования. @see Cloudsearch.SchemaPropertyOptions

buckets[]

object ( FacetBucket )

FacetBuckets для значений в ответе, содержащих хотя бы один результат с соответствующим фильтром.

FacetBucket

Ковш в фаце является основной рабочей единицей. Сегмент может содержать либо одно значение, либо непрерывный диапазон значений, в зависимости от типа поля, включаемого в сегмент. FacetBucket в настоящее время используется только для возврата объекта ответа.

JSON-представление 
{
  "count": integer,
  "percentage": integer,
  "filter": {
    object (Filter)
  },
  "value": {
    object (Value)
  }
}
Поля
count

integer

Количество результатов, соответствующих значению сегмента. Числа возвращаются для поиска только в том случае, если гарантируется точность подсчета. Cloud Search не гарантирует подсчет фасетов для любого запроса, а счетчик фасетов может присутствовать только время от времени, даже для идентичных запросов. Не создавайте зависимости от существования количества фасетов; вместо этого используйте проценты подсчета фасетов, которые всегда возвращаются.

percentage

integer

Процент результатов, соответствующих значению сегмента. Возвращаемое значение находится в диапазоне (0–100) и округляется до целого числа, если оно дробное. Если значение не возвращается явно, оно представляет собой процентное значение, которое округляется до 0. Проценты возвращаются для всех поисков, но являются приблизительными. . Поскольку проценты всегда возвращаются, вам следует отображать проценты, а не числа.

filter

object ( Filter )

Фильтр, который будет передан в поисковом запросе, если выбран соответствующий сегмент.

value

object ( Value )

Ответдебугинформо

Отладочная информация об ответе.

JSON-представление 
{
  "formattedDebugInfo": string
}
Поля
formattedDebugInfo

string

Общая информация отладки, отформатированная для отображения.

Информация об ошибке

Информация об ошибке в ответе.

JSON-представление 
{
  "errorMessages": [
    {
      object (ErrorMessage)
    }
  ]
}
Поля
errorMessages[]

object ( ErrorMessage )

Сообщение об ошибке

Сообщение об ошибке для каждого ответа источника.

JSON-представление 
{
  "source": {
    object (Source)
  },
  "errorMessage": string
}
Поля
source

object ( Source )

errorMessage

string

ResultCounts

Информация о подсчете результатов

JSON-представление 
{
  "sourceResultCounts": [
    {
      object (SourceResultCount)
    }
  ]
}
Поля
sourceResultCounts[]

object ( SourceResultCount )

Информация о количестве результатов для каждого источника с результатами.

Саурсерсулткунт

Информация о подсчете результатов для каждого источника.

JSON-представление 
{
  "source": {
    object (Source)
  },
  "hasMoreResults": boolean,

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
Поля
source

object ( Source )

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

hasMoreResults

boolean

Есть ли еще результаты поиска для этого источника.

Поле объединения result_count .

result_count может быть только одним из следующих:

resultCountEstimate

string ( int64 format)

Предполагаемое количество результатов для этого источника.

resultCountExact

string ( int64 format)

Точное количество результатов для этого источника.