Эта страница переведена с помощью Cloud Translation API.

Создайте интерфейс поиска с помощью API запросов.

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

Для веб-приложений с минимальными требованиями рассмотрите возможность использования поискового виджета. Подробнее см. в статье Создание поискового интерфейса с помощью поискового виджета.

Создайте поисковый интерфейс

Создание минимального интерфейса поиска требует нескольких шагов:

Настроить поисковое приложение
Сгенерировать учетные данные OAuth для приложения
Запрос индекса
Отобразить результаты запроса

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

Настроить поисковое приложение

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

Дополнительную информацию о поисковых приложениях см. в разделе Настройка поиска в Cloud Search .

Сгенерировать учетные данные OAuth для приложения

Помимо действий, описанных в разделе «Настройка доступа к API Google Cloud Search» , необходимо также сгенерировать учётные данные OAuth для веб-приложения. Тип создаваемых учётных данных зависит от контекста использования API.

Используйте учётные данные для запроса авторизации от имени пользователя. При запросе авторизации используйте область действия https://www.googleapis.com/auth/cloud_search.query .

Дополнительную информацию о параметрах OAuth и клиентских библиотеках см. на странице [Платформа Google Identity](https://developers.google.com/identity/choose-auth{: .external target="_blank"}).

Запрос индекса

Используйте метод search для выполнения поиска по индексу.

Каждый запрос должен включать два фрагмента информации: текстовый query для сопоставления элементов и searchApplicationId , определяющий идентификатор поискового приложения , которое будет использоваться.

В следующем фрагменте показан запрос к источнику данных о фильме «Титаник»:

{
  "query": "titanic",
  "requestOptions": {
    "searchApplicationId": "searchapplications/<search_app_id>"
  },
}

Показать результаты запроса

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

Обработка дополнительных результатов

По умолчанию Cloud Search возвращает дополнительные результаты, если результатов по запросу пользователя недостаточно. Поле queryInterpretation в ответе указывает, когда возвращаются дополнительные результаты. Если возвращаются только дополнительные результаты, InterpretationType устанавливается в значение REPLACE . Если вместе с дополнительными результатами возвращается несколько результатов по исходному запросу, InterpretationType устанавливается в BLEND . В любом случае QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY .

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

В случае BLEND вы можете отобразить строку «Поиск по вашему исходному запросу не дал достаточного количества результатов. Включая результаты по похожим запросам».

Результаты обработки людей

Cloud Search возвращает два типа результатов поиска людей: документы, относящиеся к человеку, имя которого используется в запросе, и информацию о сотруднике человека, имя которого используется в запросе. Последний тип результатов является функцией поиска людей в Cloud Search, и результаты такого запроса можно найти в поле structuredResults ответа API запроса:

{
  "results": [...],
  "structuredResults": [{
    "person": {...}
  }]
}

Сопоставление прямых отчетов

Direct Reports Matching — это функция поиска людей в Cloud Search, которая позволяет пользователям просматривать список непосредственных подчиненных сотрудника в своей организации. Результат отображается в поле structuredResults .

Для запросов о руководителе или непосредственных подчиненных пользователя ответ содержит assistCardProtoHolder в structuredResults . У assistCardProtoHolder есть поле cardType , которое будет равно RELATED_PEOPLE_ANSWER_CARD . assistCardProtoHolder содержит карточку relatedPeopleAnswerCard , содержащую сам ответ. Она содержит subject (лицо, включенное в запрос) и relatedPeople , которые представляют собой набор людей, связанных с субъектом. Поле relationType возвращает значение MANAGER или DIRECT_REPORTS .

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

{
  "results": [],
  "structuredResults": [{
    "assistCardProtoHolder": {
      "extensions": {
        "@type": "type.googleapis.com/enterprise.topaz.sidekick.AssistCardProto",
        "cardMetadata": {
          "cardCategory": "ANSWER"
        },
        "cardType": "RELATED_PEOPLE_ANSWER_CARD",
        "relatedPeopleAnswerCard": {
          "subject": {
            "email": "AdamStanford@psincs-test01.newjnj.com",
            "displayName": "Adam Stanford"
            "manager": {
              "email": "simonsais@psincs-test01.newjnj.com"
            }
          },
          "relatedPeople": [{
            "email": "EdgarMountainRamirez@psincs-test01.newjnj.com",
            "displayName": "Edgar Mountain Ramirez"
          }, {
            "email": "FranciscoJoseMartinez@psincs-test01.newjnj.com",
            "displayName": "Francisco Jose Martinez"
          }],
          "relationType": "DIRECT_REPORTS",
        }
      }
    }
  }]
}

Отключить оптимизацию, включая дополнительные результаты

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

Чтобы отключить все оптимизации на уровне поискового приложения, включая включение дополнительных результатов, синонимов и исправлений орфографии, установите для QueryInterpretationConfig.force_verbatim_mode значение true в поисковых приложениях.
Чтобы отключить все оптимизации на уровне поискового запроса, включая дополнительные результаты, синонимы и исправления орфографии, установите для QueryInterpretationOptions.enableVerbatimMode значение true в поисковом запросе.
Чтобы отключить дополнительные результаты на уровне поискового приложения, установите для параметра QueryInterpretationOptions.forceDisableSupplementalResults значение true в поисковом запросе.
Чтобы отключить дополнительные результаты на уровне поискового запроса, установите для QueryInterpretationOptions.disableSupplementalResults значение true в поисковом запросе.

Выделение фрагментов

Для возвращаемых элементов, содержащих индексированный текст или HTML-контент, возвращается фрагмент этого контента. Этот контент помогает пользователям определить релевантность возвращаемого элемента.

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

Используйте matchRanges для выделения совпадающего текста при отображении результатов. Следующий пример JavaScript преобразует фрагмент в HTML-разметку, при этом каждый совпадающий диапазон заключен в тег <span> .

function highlightSnippet(snippet) {
  let text = snippet.snippet;
  let formattedText = text;
  if (snippet.matchRanges) {
    let parts = [];
    let index = 0;
    for (let match of snippet.matchRanges) {
      let start = match.start || 0; // Default to 0 if omitted
      let end = match.end;
      if (index < start) { // Include any leading text before/between ranges
        parts.push(text.slice(index, start));
      }
      parts.push('<span class="highlight">');
      parts.push(text.slice(start, end));
      parts.push('</span>');
      index = end;
    }
    parts.push(text.slice(index)); // Include any trailing text after last range
    formattedText = parts.join('');
  }
  return formattedText;
}

Приведенный фрагмент:

{
  "snippet": "This is an example snippet...",
  "matchRanges": [
    {
      "start": 11,
      "end": 18
    }
  ]
}

Полученная HTML-строка:

This is an <span class="highlight">example</span> snippet...

Отображение метаданных

Используйте поле metadata для отображения дополнительной информации о возвращаемом элементе, которая может быть интересна пользователям. Поле metadata включает в себя createTime и updateTime элемента, а также любые возвращаемые структурированные данные, связанные с элементом.

Для отображения структурированных данных используйте поле displayOptions . Поле displayOptions содержит отображаемую метку для типа объекта и набор metalines . Каждая металиния представляет собой массив отображаемых меток и пар значений, настроенных в схеме .

Получить дополнительные результаты

Чтобы получить дополнительные результаты, установите нужное смещение в поле start запроса. Размер каждой страницы можно настроить с помощью поля pageSize .

Для отображения количества возвращённых элементов или отображения элементов управления постраничной навигацией используйте поле resultCount . В зависимости от размера результирующего набора отображается фактическое или приблизительное значение.

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

Используйте поле sortOptions для указания порядка возвращаемых элементов. Значение sortOptions представляет собой объект с двумя полями:

operatorName — оператор для сортировки по свойству структурированных данных. Для свойств с несколькими операторами сортировка возможна только с использованием основного оператора равенства.
sortOrder — направление сортировки: ПО ASCENDING или DESCENDING .

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

"sortOptions": {
  "operatorName": "priority",
  "sortOrder": "DESCENDING"
}

Добавить фильтры

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

Чтобы добавить фильтры в запрос или поисковое приложение, добавьте фильтр в поле dataSourceRestrictions.filterOptions[] .

Существует два основных способа дальнейшей фильтрации источника данных:

Фильтры объектов через свойство filterOptions[].objectType — ограничивают соответствующие элементы указанным типом, как определено в пользовательской схеме.
Фильтры значений — ограничивают соответствующие элементы на основе оператора запроса и предоставленного значения.

Составные фильтры позволяют объединять несколько фильтров значений в логические выражения для более сложных запросов.

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

{
  "query": "adventure",
  "requestOptions": {
    "searchApplicationId": "<search_app_id>"
  },
  "dataSourceRestrictions": [
    {
      "source": {
        "name": "datasources/<data_source_id>"
      },
      "filterOptions": [
        {
          "objectType": "movie",
          "filter": {
            "compositeFilter": {
              "logicOperator": "AND"
              "subFilters": [
                {
                  "compositeFilter": {
                  "logicOperator": "OR"
                  "subFilters": [
                    {
                      "valueFilter": {
                        "operatorName": "rated",
                        "value": {
                          "stringValue": "G"
                        }
                      }
                    },
                    {
                      "valueFilter": {
                        "operatorName": "rated",
                        "value": {
                          "stringValue": "PG"
                        }
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

Уточните результаты с помощью аспектов

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

Фасеты можно определить в вашем поисковом приложении и переопределить настройками в вашем запросе.

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

Типичная схема взаимодействия с гранями:

Создайте начальный запрос, указав, какие свойства следует включить в результаты фасета.
Отобразить результаты поиска и фасетирования.
Пользователь выбирает одно или несколько значений фасетов для уточнения результатов.
Повторите запрос с фильтром на основе выбранных значений.

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

"facetOptions": [
  {
    "sourceName": "datasources/<data_source_id>",
    "operatorName": "year"
  },
  {
    "sourceName": "datasources/<data_source_id>",
    "operatorName": "rated"
  }
]

Вы также можете фасетировать результаты запроса с помощью целочисленных полей. Например, можно отметить целочисленное свойство book_pages как фасетное, чтобы уточнить результаты поиска книг со страницами «100–200».

При настройке схемы поля целочисленного свойства установите для isFacetable значение true и добавьте соответствующие параметры сегментирования в integerPropertyOptions . Это гарантирует, что для каждого целочисленного свойства будут определены параметры сегментирования по умолчанию.

При определении логики параметров сегментирования предоставьте массив инкрементных значений, обозначающих диапазоны. Например, если конечный пользователь указывает диапазоны 2, 5, 10, 100 , то будут рассчитаны фасеты для <2 , [2-5) , [5-10) , [10-100) , >=100 .

Вы можете переопределить целочисленные фасеты, указав те же параметры сегментирования в параметре facetOptions в запросе. При необходимости Cloud Search использует параметры сегментирования, заданные в схеме, если ни в поисковом приложении, ни в запросе не заданы параметры фасетов. Фасеты, заданные в запросе, имеют приоритет над фасетами, заданными в поисковом приложении, а фасеты, заданные в поисковом приложении, имеют приоритет над фасетами, заданными в схеме.

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

Для фасетирования по размеру документа используйте itemsize и определите параметры группировки.
Для фасетирования по дате создания документа используйте createddatetimestamp .
Для фасетирования по дате изменения документа используйте lastmodified .

Интерпретация сегментов

Свойство facetResults в ответе поискового запроса включает точный запрос фильтра пользователя в поле filter для каждого bucket .

Для фасетов, не основанных на целых числах, facetResults включает запись для каждого запрошенного свойства. Для каждого свойства предоставляется список значений или диапазонов, называемых buckets ). Наиболее часто встречающиеся значения отображаются первыми.

Когда пользователь выбирает одно или несколько значений для фильтрации, создайте новый запрос с выбранными фильтрами и снова обратитесь к API.

Добавить предложения

Используйте API Suggest , чтобы обеспечить автоматическое завершение запросов на основе личной истории запросов пользователя, а также контактов и корпуса документов.

Например, следующий вызов дает предложения для частичной фразы jo .

{
  "query": "jo",
  "requestOptions": {
    "searchApplicationId": "<search_app_id>",
    "peoplePhotoOptions": {
      "peoplePhotoUrlSizeInPx": 32
    },
    "timeZone": "America/Denver"
  }
}

Затем вы можете отобразить полученные предложения в соответствии с вашим приложением.

Создайте интерфейс поиска с помощью API запросов.

Создайте поисковый интерфейс

Настроить поисковое приложение

Сгенерировать учетные данные OAuth для приложения

Запрос индекса

Показать результаты запроса

Обработка дополнительных результатов

Результаты обработки людей

Сопоставление прямых отчетов

Отключить оптимизацию, включая дополнительные результаты

Выделение фрагментов

Отображение метаданных

Получить дополнительные результаты

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

Добавить фильтры

Уточните результаты с помощью аспектов

Результаты фасетов с целочисленными полями

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

Интерпретация сегментов

Добавить предложения

Создайте интерфейс поиска с помощью API запросов. Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Создайте поисковый интерфейс

Настроить поисковое приложение

Сгенерировать учетные данные OAuth для приложения

Запрос индекса

Показать результаты запроса

Обработка дополнительных результатов

Результаты обработки людей

Сопоставление прямых отчетов

Отключить оптимизацию, включая дополнительные результаты

Выделение фрагментов

Отображение метаданных

Получить дополнительные результаты

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

Добавить фильтры

Уточните результаты с помощью аспектов

Результаты фасетов с целочисленными полями

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

Интерпретация сегментов

Добавить предложения

Создайте интерфейс поиска с помощью API запросов.