Выполнение текстовых поисковых запросов в синхронном режиме

1. Создайте сервисный аккаунт, от имени которого будут выполняться запросы. Вы также можете использовать аккаунт на Яндексе или федеративный аккаунт, но для автоматизации предпочтительнее использовать сервисный аккаунт.

2. Назначьте аккаунту, от имени которого будут выполняться запросы, роль search-api.webSearch.user.

3. Получите IAM-токен, необходимый для аутентификации.

   В приведенных примерах используется аутентификация с помощью IAM-токена. Чтобы использовать для аутентификации API-ключ сервисного аккаунта, измените в примерах запросов заголовок Authorization. Подробнее см. в разделе Аутентификация в API.

Чтобы воспользоваться примерами, также установите утилиты cURL и jq.

1. Создайте сервисный аккаунт, от имени которого будут выполняться запросы. Вы также можете использовать аккаунт на Яндексе или федеративный аккаунт, но для автоматизации предпочтительнее использовать сервисный аккаунт.

2. Назначьте аккаунту, от имени которого будут выполняться запросы, роль search-api.webSearch.user.

3. Получите IAM-токен, необходимый для аутентификации.

   В приведенных примерах используется аутентификация с помощью IAM-токена. Чтобы использовать для аутентификации API-ключ сервисного аккаунта, измените в примерах запросов заголовок Authorization. Подробнее см. в разделе Аутентификация в API.

Чтобы воспользоваться примерами, также установите утилиты gRPCurl и jq.

1. Отправьте запрос и получите результат в кодировке Base64:

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

      body.json

      {
          "query": {
            "searchType": "<тип_поиска>",
            "queryText": "<текст_поискового_запроса>",
            "familyMode": "<значение_настройки_фильтрации_результатов>",
            "page": "<номер_страницы>",
            "fixTypoMode": "<значение_настройки_режима_исправления_опечаток>"
          },
          "sortSpec": {
            "sortMode": "<правило_сортировки_результатов>",
            "sortOrder": "<порядок_сортировки_результатов>"
          },
          "groupSpec": {
            "groupMode": "<метод_группировки_результатов>",
            "groupsOnPage": "<количество_групп_на_странице>",
            "docsInGroup": "<количество_документов_в_группе>"
          },
          "maxPassages": "<максимальное_количество_пассажей>",
          "region": "<идентификатор_региона>",
          "l10N": "<язык_уведомлений>",
          "folderId": "<идентификатор_каталога>",
          "responseFormat": "<формат_результата>",
          "userAgent": "<заголовок_User-Agent>"
      }
      

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

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

        • SEARCH_TYPE_RU — для типа поиска Русский.
        • SEARCH_TYPE_TR — для типа поиска Турецкий.
        • SEARCH_TYPE_COM — для типа поиска Международный.
        • SEARCH_TYPE_KK — для типа поиска Казахский.
        • SEARCH_TYPE_BE – для типа поиска Белорусский.
        • SEARCH_TYPE_UZ — для типа поиска Узбекский.

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

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

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

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

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

        • FIX_TYPO_MODE_ON — исправление опечаток включено (значение по умолчанию). Опечатки в тексте поискового запроса автоматически исправляются.
        • FIX_TYPO_MODE_OFF — исправление опечаток отключено. Опечатки в тексте поискового запроса не исправляются, поиск выполняется в полном соответствии с переданным запросом.

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

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

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

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

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

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

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

        При получении результата в формате XML допустимые значения — от 1 до 100, при получении результата в формате HTML — от 5 до 50.

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

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

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

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

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

        • Тип поиска Русский:
          • LOCALIZATION_RU — русский язык (значение по умолчанию).
          • LOCALIZATION_BE — белорусский язык.
          • LOCALIZATION_KK — казахский язык.
          • LOCALIZATION_UK — украинский язык.
        • Тип поиска Турецкий:
          • LOCALIZATION_TR — турецкий язык.
        • Тип поиска Международный:
          • LOCALIZATION_EN — английский язык.

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

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

        • FORMAT_XML — результат запроса будет передан в формате XML (значение по умолчанию).
        • FORMAT_HTML — результат запроса будет передан в формате HTML.

      • userAgent — строка, содержащая заголовок User-Agent. Параметр позволяет получить поисковую выдачу, ориентированную на конкретные устройство и браузер, в том числе мобильную выдачу. Необязательный параметр. Если параметр не задан, сервис возвращает стандартную выдачу по умолчанию.

      Список поддерживаемых параметров:

      Примечание

      Список поддерживаемых в запросе параметров зависит от того, в каком формате требуется получить результат: XML или HTML.

      Параметр	Поддерживается при XML-ответе	Поддерживается при HTML-ответе
      searchType
      queryText
      familyMode
      page
      fixTypoMode
      sortMode
      sortOrder
      groupMode
      groupsOnPage
      docsInGroup
      maxPassages
      region
      l10N
      folderId
      responseFormat
      userAgent

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

      curl \
        --request POST \
        --header "Authorization: Bearer <IAM-токен>" \
        --data "@body.json" \
        "https://searchapi.api.cloud.yandex.net/v2/web/search" \
        > result.json
      

   В результате в файл result.json будет сохранен результат выполнения поискового запроса, содержащий в поле rawData XML или HTML ответ в кодировке Base64.

2. В зависимости от запрошенного формата ответа декодируйте результат из формата Base64:

   XML

   HTML

   echo "$(< result.json)" | \
     jq -r .rawData | \
     base64 --decode > result.xml
   

   В результате в файл result.xml будет сохранен XML-ответ по запросу.

   echo "$(< result.json)" | \
     jq -r .rawData | \
     base64 --decode > result.html
   

   В результате в файл result.html будет сохранен HTML-ответ по запросу.

1. Отправьте запрос и получите результат в кодировке Base64:

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

      body.json

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

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

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

        • SEARCH_TYPE_RU — для типа поиска Русский.
        • SEARCH_TYPE_TR — для типа поиска Турецкий.
        • SEARCH_TYPE_COM — для типа поиска Международный.
        • SEARCH_TYPE_KK — для типа поиска Казахский.
        • SEARCH_TYPE_BE – для типа поиска Белорусский.
        • SEARCH_TYPE_UZ — для типа поиска Узбекский.

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

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

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

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

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

        • FIX_TYPO_MODE_ON — исправление опечаток включено (значение по умолчанию). Опечатки в тексте поискового запроса автоматически исправляются.
        • FIX_TYPO_MODE_OFF — исправление опечаток отключено. Опечатки в тексте поискового запроса не исправляются, поиск выполняется в полном соответствии с переданным запросом.

      • 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 — максимальное количество групп, которые могут быть возвращены на одной странице результатов поиска. Необязательный параметр. Значение по умолчанию — 20.

        При получении результата в формате XML допустимые значения — от 1 до 100, при получении результата в формате HTML — от 5 до 50.

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

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

        • FORMAT_XML — результат запроса будет передан в формате XML (значение по умолчанию).
        • FORMAT_HTML — результат запроса будет передан в формате HTML.

      • user_agent — строка, содержащая заголовок User-Agent. Параметр позволяет получить поисковую выдачу, ориентированную на конкретные устройство и браузер, в том числе мобильную выдачу. Необязательный параметр. Если параметр не задан, сервис возвращает стандартную выдачу по умолчанию.

      Список поддерживаемых параметров:

      Примечание

      Список поддерживаемых в запросе параметров зависит от того, в каком формате требуется получить результат: XML или HTML.

      Параметр	Поддерживается при XML-ответе	Поддерживается при HTML-ответе
      search_type
      query_text
      family_mode
      page
      fix_typo_mode
      sort_mode
      sort_order
      group_mode
      groups_on_page
      docs_in_group
      max_passages
      region
      l10n
      folder_id
      response_format
      user_agent

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

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

   В результате в файл result.json будет сохранен результат выполнения поискового запроса, содержащий в поле rawData XML или HTML ответ в кодировке Base64.

2. В зависимости от запрошенного формата ответа декодируйте результат из формата Base64:

   XML

   HTML

   echo "$(< result.json)" | \
     jq -r .rawData | \
     base64 --decode > result.xml
   

   В результате в файл result.xml будет сохранен XML-ответ по запросу.

   echo "$(< result.json)" | \
     jq -r .rawData | \
     base64 --decode > result.html
   

   В результате в файл result.html будет сохранен HTML-ответ по запросу.