Method: query.search

API запросов Cloud Search предоставляет метод поиска, который возвращает наиболее релевантные результаты по запросу пользователя. Результаты могут поступать из приложений 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 поиска. Идентификатор NEXT: 19

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

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 )

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

spellResults[]

object ( SpellResult )

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

facetResults[]

object ( FacetResult )

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

hasMoreResults

boolean

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

debugInfo

object ( ResponseDebugInfo )

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

errorInfo

object ( ErrorInfo )

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

resultCounts

object ( ResultCounts )

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

Union field result_count . The total result count across all requested data sources. Omitted if predefined sources are included in the set of data sources queried. Result counts might be returned as an estimate, instead of exact, under the following circumstances:

  • Когда в запросе содержится более двух терминов в одной фразе, например, "result count exact" в кавычках.

  • Когда количество уникальных списков контроля доступа (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

Для получения более подробной информации см. руководство по авторизации .

QueryInterpretationOptions

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

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

boolean

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

enableVerbatimMode

boolean

Enable this flag to turn off all internal optimizations like natural language (NL) interpretation of queries, supplemental result retrieval, and usage of synonyms including custom ones. Nl interpretation will be disabled if either one of the two flags is true.

disableSupplementalResults

boolean

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

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

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

string

Интерпретация запроса, используемого в поиске. Например, запросы с намерением, выраженным на естественном языке, такие как "email from john", будут интерпретироваться как "from:john source:mail". Это поле не будет заполнено, если причина — NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.

interpretationType

enum ( QueryInterpretation.InterpretationType )

reason

enum ( QueryInterpretation.Reason )

Причина интерпретации запроса. Это поле не будет иметь значение UNSPECIFIED, если тип интерпретации не равен NONE.

interpretedQueryActualResultCount

integer

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

interpretedQueryEstimatedResultCount

string ( int64 format)

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

QueryInterpretation.InterpretationType

Перечисления
NONE Для получения результатов поиска не используется ни интерпретация на естественном языке, ни более расширенная версия запроса.
BLEND Результаты исходного запроса объединяются с другими результатами. Причина объединения этих других результатов с результатами исходного запроса указывается в поле «Причина» ниже.
REPLACE Результаты исходного запроса заменены. Причина замены результатов исходного запроса указана в поле «Причина» ниже.

QueryInterpretation.Reason

Перечисления
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT Для получения результатов поиска используется интерпретация запроса на естественном языке.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY Сходство терминов запроса и документа используется для выборочного расширения запроса с целью получения дополнительных результатов поиска, поскольку для запроса пользователя не было найдено достаточно результатов. В этом случае интерпретированный запрос будет пустым.

Результаты поиска

Результаты, содержащие индексированную информацию для документа. Идентификатор следующего документа: 16

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 )

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

Snippet

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

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)

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

Используется RFC 3339, согласно которому генерируемый вывод всегда будет Z-нормализован и будет содержать 0, 3, 6 или 9 дробных знаков. Допускаются также смещения, отличные от "Z". Примеры: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30" .

updateTime

string ( Timestamp format)

The last modified date for the object in the search result. If not set in the item, the value returned here is empty. When updateTime is used for calculating freshness and is not set, this value defaults to 2 years from the current time.

Используется RFC 3339, согласно которому генерируемый вывод всегда будет Z-нормализован и будет содержать 0, 3, 6 или 9 дробных знаков. Допускаются также смещения, отличные от "Z". Примеры: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30" .

fields[]

object ( NamedProperty )

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

displayOptions

object ( ResultDisplayMetadata )

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

objectType

string

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

ResultDisplayMetadata

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 )

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

ResultDebugInfo

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

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

string

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

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

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

JSON-представление 
{

  // Union field structured_result can be only one of the following:
  "person": {
    object (Person)
  }
  // End of list of possible types for union field structured_result.
}
Поля

Объединенное поле structured_result .

structured_result может принимать только одно из следующих значений:

person

object ( Person )

Изображение человека

SpellResult

JSON-представление 
{
  "suggestedQuery": string,
  "suggestionType": enum (SpellResult.SuggestionType),
  "suggestedQueryHtml": {
    object (SafeHtmlProto)
  }
}
Поля
suggestedQuery

string

Предлагаемый вариант написания запроса.

suggestionType

enum ( SpellResult.SuggestionType )

Для текущего запроса сработало предложение.

suggestedQueryHtml

object ( SafeHtmlProto )

Очищенный HTML-код, представляющий собой запрос с исправлениями орфографии, который можно использовать в пользовательском интерфейсе. Обычно он содержит теги, специфичные для конкретного языка, для разметки частей запроса, прошедших проверку орфографии.

SpellResult.SuggestionType

Тип подсказки, срабатывающей для запроса.

Перечисления
SUGGESTION_TYPE_UNSPECIFIED Тип проверки орфографии по умолчанию
NON_EMPTY_RESULTS_SPELL_SUGGESTION Предложенные варианты написания без каких-либо результатов изменились. Результаты по-прежнему отображаются для исходного запроса (который имеет ненулевое количество результатов) с предложением варианта написания, который должен был бы иметь результаты.
ZERO_RESULTS_FULL_PAGE_REPLACEMENT Функция подсказок орфографии срабатывает, когда исходный запрос не дает результатов. Если исходный запрос не дает результатов, а функция подсказок орфографии дает результаты, мы запускаем подсказки для запроса с исправленной орфографией.

SafeHtmlProto

ВАЖНО: Небезопасно принимать это сообщение из ненадежного источника, поскольку злоумышленнику легко подделать сериализованные сообщения, не соответствующие контракту безопасности типа — например, они могут содержать скрипт, управляемый злоумышленником. Система, получающая SafeHtmlProto, неявно доверяет создателю SafeHtmlProto. Поэтому, как правило, безопасно возвращать это сообщение в ответах RPC, но небезопасно принимать его в запросах RPC.

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

string

ВАЖНО: Никогда не устанавливайте и не считывайте это поле, даже в тестах, оно является приватным. См. документацию в верхней части файла .proto для получения информации о пакетах языков программирования, с помощью которых можно создать или прочитать это сообщение.

FacetResult

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

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

string

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

objectType

string

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

operatorName

string

Название оператора, выбранного для фасетного поиска. @see cloudsearch.SchemaPropertyOptions

buckets[]

object ( FacetBucket )

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

FacetBucket

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

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

  // Union field bucket_value can be only one of the following:
  "value": {
    object (Value)
  }
  // End of list of possible types for union field bucket_value.
}
Поля
count

integer

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

percentage

integer

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

filter

object ( Filter )

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

Поле объединения bucket_value . Диапазон или значение сегмента, к которому применяется фасетный метод bucket_value может принимать только одно из следующих значений:
value

object ( Value )

ResponseDebugInfo

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

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

string

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

ErrorInfo

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

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 )

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

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)

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