Связаться с намиПодключиться

Как начать работать с Yandex Search API через интерфейс API v2

Статья создана
Обновлена 7 марта 2025 г.

API v2 является более современным и рекомендованным интерфейсом для работы с Yandex Search API. API v2 полностью интегрирован в экосистему Yandex Cloud и одновременно с аутентификацией по API-ключу поддерживает более безопасную аутентификацию с помощью короткоживущих IAM-токенов.

Перед началом работы

Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:

  1. Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь.
  2. На странице Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его и привяжите к нему облако.

Если у вас есть активный платежный аккаунт, вы можете создать или выбрать каталог, в котором будет работать ваша инфраструктура, на странице облака.

Подробнее об облаках и каталогах.

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

Подготовьте облако к работе

  1. Для аутентификации в API v2 от имени сервисного аккаунта создайте сервисный аккаунт.

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

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

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

Сформируйте поисковый запрос

Приведенный в примере запрос возвращает пятую страницу результатов поиска по запросу Яндекс. Тип поиска — Русский. Регион поиска — Новосибирская область. Язык уведомлений — русский. К результатам поиска будет применен семейный фильтр. Количество пассажей — три. Результаты группируются по домену и сортируются по релевантности. Каждая группа содержит три документа, а количество групп, возвращаемых на одной странице, равно пяти.

Подробнее о параметрах тела запроса см. в разделе Формат тела запроса.

  1. Создайте файл с телом запроса (например, body.json), в поле folderId указав идентификатор каталога, в котором вы будете работать с Yandex Search API:

    body.json

    {
    "query": {
      "searchType": "SEARCH_TYPE_RU",
      "queryText": "Яндекс",
      "familyMode": "FAMILY_MODE_STRICT",
      "page": "4"
    },
    "sortSpec": {
      "sortMode": "SORT_MODE_BY_RELEVANCE",
      "sortOrder": "SORT_ORDER_DESC"
    },
    "groupSpec": {
      "groupMode": "GROUP_MODE_DEEP",
      "groupsOnPage": "5",
      "docsInGroup": "3"
    },
    "maxPassages": "3",
    "region": "65",
    "l10N": "LOCALIZATION_RU",
    "folderId": "<идентификатор_каталога>"
}

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

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

    Результат:

    {
 "done": false,
 "id": "sppger465oq1********",
 "description": "WEB search async",
 "createdAt": "2024-10-02T19:51:02Z",
 "createdBy": "bfbud0oddqp4********",
 "modifiedAt": "2024-10-02T19:51:03Z"
}

  1. Создайте файл с телом запроса (например, body.json), в поле folder_id указав идентификатор каталога, в котором вы будете работать с Yandex Search API:

    body.json

    {
    "query": {
      "search_type": "SEARCH_TYPE_RU",
      "query_text": "Яндекс",
      "family_mode": "FAMILY_MODE_STRICT",
      "page": "4"
    },
    "sort_spec": {
      "sort_mode": "SORT_MODE_BY_RELEVANCE",
      "sort_order": "SORT_ORDER_DESC"
    },
    "group_spec": {
      "group_mode": "GROUP_MODE_DEEP",
      "groups_on_page": "5",
      "docs_in_group": "3"
    },
    "max_passages": "3",
    "region": "65",
    "l10n": "LOCALIZATION_RU",
    "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"
}

Сохраните идентификатор полученного объекта Operation (значение id) — он понадобится позднее.

Убедитесь в успешном выполнении запроса

Дождитесь, пока Yandex Search API выполнит запрос и сформирует ответ. На это может потребоваться от пяти минут до нескольких часов.

Чтобы убедиться в успешном выполнении запроса:

Выполните HTTP-запрос:

curl \
  --request GET \
  --header "Authorization: Bearer <IAM-токен>" \
  https://operation.api.cloud.yandex.net/operations/<идентификатор_запроса>

Где:

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

Результат:

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

Выполните 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>"
  }
}

Если поле done имеет значение true, и в выводе присутствует объект response, значит, запрос выполнен, и вы можете переходить к следующему шагу. В противном случае, повторите проверку через некоторое время.

Получите ответ

После того как сервис Yandex Search API успешно обработал запрос:

  1. Получите результат:

    curl \
  --request GET \
  --header "Authorization: Bearer <IAM-токен>" \
  https://operation.api.cloud.yandex.net/operations/<идентификатор_запроса> \
  > result.json

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

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

  2. Декодируйте результат из формата Base64:

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

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

См. также

Предыдущая
Начало работы с API v1
Следующая
Все инструкции