Выполнение поисковых запросов с помощью API v2

1. Создайте файл с телом запроса (например, body.json):

   body.json

   {
       "query": {
         "search_type": "<тип_поиска>",
         "query_text": "<текст_поискового_запроса>",
         "family_mode": "<значение_настройки_фильтрации_результатов>",
         "page": "<номер_страницы>"
       },
       "sort_spec": {
         "sort_mode": "<правило_сортировки_результатов>",
         "sort_order": "<порядок_сортировки_результатов>"
       },
       "group_spec": {
         "group_mode": "<метод_группировки_результатов>",
         "groups_on_page": "<количество_групп_на_странице>",
         "docs_in_group": "<количество_документов_в_группе>"
       },
       "max_passages": "<максимальное_количество_пассажей>",
       "region": "<идентификатор_региона>",
       "l10n": "<язык_уведомлений>",
       "folder_id": "<идентификатор_каталога>"
   }
   

   Описание полей

   • search_type — тип поиска. Возможные значения:

     • SEARCH_TYPE_RU — для типа поиска Русский.
     • SEARCH_TYPE_TR — для типа поиска Турецкий.
     • SEARCH_TYPE_COM — для типа поиска Международный.

   • query_text — текст поискового запроса. Максимальная длина запроса — 400 символов.

   • family_mode — фильтрация результатов. Необязательный параметр. Возможные значения:

     • FAMILY_MODE_MODERATE — умеренный фильтр (значение по умолчанию). Из выдачи исключаются документы, относящиеся к категории "для взрослых", если запрос явно не направлен на поиск подобных ресурсов.
     • FAMILY_MODE_NONE — фильтрация отключена. В выдачу включаются любые документы вне зависимости от содержимого.
     • FAMILY_MODE_STRICT — семейный фильтр. Вне зависимости от поискового запроса из выдачи исключаются документы, относящиеся к категории "для взрослых", а также содержащие ненормативную лексику.

   • page — номер запрашиваемой страницы. Необязательный параметр. По умолчанию возвращается первая страница поисковой выдачи. Нумерация страниц начинается с нуля (первой странице соответствует значение 0).

   • sort_mode — правило сортировки результатов поиска, которое определяет порядок выдачи результатов поиска. Необязательный параметр. Возможные значения:

     • SORT_MODE_BY_RELEVANCE — сортировка по релевантности (значение по умолчанию).
     • SORT_MODE_BY_TIME — сортировка по времени изменения документа.

   • sort_order — порядок сортировки результатов поиска. Необязательный параметр. Возможные значения:

     • SORT_ORDER_DESC — прямой порядок сортировки — от наиболее свежего к наиболее старому (значение по умолчанию).
     • SORT_ORDER_ASC — обратный порядок сортировки — от наиболее старого к наиболее свежему.

   • group_mode — метод группировки результатов. Необязательный параметр. Возможные значения:

     • GROUP_MODE_DEEP — группировка по доменам. Каждая группа содержит документы одного домена (значение по умолчанию).
     • GROUP_MODE_FLAT — плоская группировка. Каждая группа содержит один документ.

   • groups_on_page — максимальное количество групп, которые могут быть возвращены на одной странице результатов поиска. Необязательный параметр. Допустимые значения — от 1 до 100. Значение по умолчанию — 20.

   • docs_in_group — максимальное количество документов, которые могут быть возвращены в одной группе. Необязательный параметр. Допустимые значения — от 1 до 3. Значение по умолчанию — 1.

   • max_passages — максимальное количество пассажей, которое может быть использовано при формировании сниппета к документу. Необязательный параметр. Допустимые значения — от 1 до 5. По умолчанию для каждого документа возвращается не более четырех пассажей с текстом запроса.

   • region — идентификатор страны или региона поиска, который влияет на правила ранжирования документов. Поддерживается только для типов поиска Русский и Турецкий.

     Список идентификаторов часто используемых стран и регионов см. в разделе Регионы поиска.

   • l10n — язык уведомлений поискового ответа. Влияет на текст, передаваемый в теге found-docs-human и в сообщениях об ошибках. Необязательный параметр. Возможные значения зависят от выбранного типа поиска:

     • Тип поиска Русский:

       • LOCALIZATION_RU — русский язык (значение по умолчанию).
       • LOCALIZATION_BE — белорусский язык.
       • LOCALIZATION_KK — казахский язык.
       • LOCALIZATION_UK — украинский язык.

     • Тип поиска Турецкий:

       • LOCALIZATION_TR — турецкий язык.

     • Тип поиска Международный:

       • LOCALIZATION_EN — английский язык.

   • folder_id — идентификатор каталога пользователя или сервисного аккаунта, от имени которого вы будете выполнять запросы.

2. Выполните gRPC-вызов, указав полученный ранее IAM-токен:

   grpcurl \
     -rpc-header "Authorization: Bearer <IAM-токен>" \
     -d @ < body.json \
     searchapi.api.cloud.yandex.net:443 yandex.cloud.searchapi.v2.WebSearchAsyncService/Search
   

   Результат:

   {
     "id": "spp3gp3vhna6********",
     "description": "WEB search async",
     "createdAt": "2024-10-02T19:14:41Z",
     "createdBy": "bfbud0oddqp4********",
     "modifiedAt": "2024-10-02T19:14:42Z"
   }
   

Выполните gRPC-вызов:

grpcurl \
  -rpc-header "Authorization: Bearer <IAM-токен>" \
  -d '{"operation_id": "<идентификатор_запроса>"}' \
  operation.api.cloud.yandex.net:443 yandex.cloud.operation.OperationService/Get

Где:

• <IAM-токен> — полученный ранее IAM-токен.
• <идентификатор_запроса> — сохраненный на предыдущем шаге идентификатор объекта Operation.

Результат:

{
  "id": "spp82pc07ebl********",
  "description": "WEB search async",
  "createdAt": "2024-10-03T08:07:07Z",
  "createdBy": "bfbud0oddqp4********",
  "modifiedAt": "2024-10-03T08:12:09Z",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/yandex.cloud.searchapi.v2.WebSearchResponse",
    "rawData": "<тело_XML_ответа_в_кодировке_Base64>"
  }
}