Как начать работать с Search API через интерфейс API v2
API v2 является более современным и рекомендованным интерфейсом для работы с Search API. API v2 полностью интегрирован в экосистему Yandex Cloud и одновременно с аутентификацией по API-ключу поддерживает более безопасную аутентификацию с помощью короткоживущих IAM-токенов.
Перед началом работы
Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:
- Перейдите в консоль управления
, затем войдите в Yandex Cloud или зарегистрируйтесь. - На странице Yandex Cloud Billing
убедитесь, что у вас подключен платежный аккаунт, и он находится в статусеACTIVE
илиTRIAL_ACTIVE
. Если платежного аккаунта нет, создайте его и привяжите к нему облако.
Если у вас есть активный платежный аккаунт, вы можете создать или выбрать каталог, в котором будет работать ваша инфраструктура, на странице облака
Подробнее об облаках и каталогах.
Чтобы воспользоваться примерами, установите утилиты cURL
Подготовьте облако к работе
-
Для аутентификации в API v2 от имени сервисного аккаунта создайте сервисный аккаунт.
-
Назначьте пользователю или сервисному аккаунту, от имени которого будут выполняться запросы, роль
search-api.webSearch.user
. -
Получите IAM-токен, необходимый для аутентификации.
В приведенных примерах используется аутентификация с помощью IAM-токена. Чтобы использовать для аутентификации API-ключ сервисного аккаунта, измените в примерах запросов заголовок
Authorization
. Подробнее см. в разделе Аутентификация в API v2.
Сформируйте поисковый запрос
Приведенный в примере запрос возвращает пятую страницу результатов поиска по запросу Яндекс
. Тип поиска — Русский
. Регион поиска — Новосибирская область. Язык уведомлений — русский. К результатам поиска будет применен семейный фильтр. Количество пассажей — три. Результаты группируются по домену и сортируются по релевантности. Каждая группа содержит три документа, а количество групп, возвращаемых на одной странице, равно пяти.
Подробнее о параметрах тела запроса см. в разделе Формат тела запроса.
-
Создайте файл с телом запроса (например,
body.json
), в полеfolderId
указав идентификатор каталога, в котором вы будете работать с 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": "<идентификатор_каталога>" }
-
Выполните 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" }
-
Создайте файл с телом запроса (например,
body.json
), в полеfolder_id
указав идентификатор каталога, в котором вы будете работать с 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": "<идентификатор_каталога>" }
-
Выполните 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
) — он понадобится позднее.
Убедитесь в успешном выполнении запроса
Дождитесь, пока 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
, значит, запрос выполнен, и вы можете переходить к следующему шагу. В противном случае, повторите проверку через некоторое время.
Получите ответ
После того как сервис Search API успешно обработал запрос:
-
Получите результат:
REST APIgRPC APIcurl \ --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 . -
Декодируйте результат из формата
Base64
:echo "$(< result.json)" | \ jq -r .response.rawData | \ base64 --decode > result.xml
В результате в файл
result.xml
будет сохранен XML-ответ по запросу.