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

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

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

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

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

  1. Настройка приложения поиска
  2. Создайте учетные данные OAuth для приложения.
  3. Запросить индекс
  4. Отображение результатов запроса

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

Настройка приложения поиска

Вы должны создать по крайней мере одно приложение поиска , которое будет связано с каждым создаваемым вами поисковым интерфейсом. Приложение поиска предоставляет параметры по умолчанию для запроса, такие как используемые источники данных, порядок сортировки, фильтры и запрашиваемые фасеты. При необходимости вы можете переопределить эти параметры с помощью 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": {...}
  }]
}

Прямое сопоставление отчетов

Сопоставление прямых отчетов — это функция поиска людей 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": "[email protected]",
            "displayName": "Adam Stanford"
            "manager": {
              "email": "[email protected]"
            }
          },
          "relatedPeople": [{
            "email": "[email protected]",
            "displayName": "Edgar Mountain Ramirez"
          }, {
            "email": "[email protected]",
            "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 вычисляет наиболее часто встречающиеся значения запрошенных свойств среди совпадающих элементов. Эти значения возвращаются в ответе. Используйте эти значения для создания фильтров, которые сужают результаты последующих запросов.

Типичный шаблон взаимодействия с фасетами:

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

Например, чтобы включить уточнение запросов фильмов по году и рейтингу 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-интерфейс предложения , чтобы обеспечить автозаполнение запросов на основе личной истории запросов пользователя, а также контактов и их корпуса документов.

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

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

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