/yandex-wordstat

Настройка скилла Yandex Wordstat

Скилл поддерживает только Wordstat API в Yandex Cloud Search API v2: https://searchapi.api.cloud.yandex.net/v2/wordstat.

Доступны два способа авторизации сервисного аккаунта: IAM через авторизованный JSON-ключ или API-ключ (раздел «Альтернатива» ниже). В IAM-режиме скрипты сами получают, кешируют и обновляют токен. В режиме API-ключа JSON-ключ и получение IAM-токена не нужны.

Старый API api.wordstat.yandex.net/v1 не работает. Его OAuth-токен не подходит для Yandex Cloud Search API; инструкции получения и обновления старого токена больше не поддерживаются.

Переход со старого API

Удалите YANDEX_WORDSTAT_TOKEN и YANDEX_WORDSTAT_BACKEND из config/.env и настроек окружения. Для текущей оболочки выполните:

unset YANDEX_WORDSTAT_TOKEN YANDEX_WORDSTAT_BACKEND

Затем настройте доступ по инструкции ниже. Команды и аргументы скриптов анализа не меняются.

Настройка доступа через IAM

Все команды ниже выполняются из каталога скилла plugins/yandex-wordstat/skills/yandex-wordstat.

Шаг 1: Создайте каталог в Яндекс.Облаке

1. Откройте консоль Yandex Cloud
2. Зарегистрируйтесь (нужен Яндекс ID), если ещё нет аккаунта
3. Создайте каталог или используйте существующий
4. Скопируйте ID каталога (b1g...) — он понадобится дальше

Шаг 2: Создайте сервисный аккаунт

1. В консоли откройте ваш каталог
2. Слева выберите Сервисные аккаунты (раздел IAM)
3. Нажмите Создать сервисный аккаунт
4. Имя: wordstat-sa (или любое)
5. Нажмите Создать

Шаг 3: Назначьте роль

1. Откройте созданный сервисный аккаунт
2. Назначьте роль search-api.webSearch.user на созданный каталог

Шаг 4: Создайте ключ авторизации

1. В сервисном аккаунте → Авторизованные ключи → Создать
2. Скачайте JSON-файл
3. Переименуйте в service_account_key.json
4. Положите в config/ (рядом с этим README)

Файл секретный — он уже в .gitignore.

Шаг 5: Создайте config.json

cp config/config.example.json config/config.json

Откройте config.json и подставьте ваш yandex_cloud_folder_id:

{
  "yandex_cloud_folder_id": "b1g_ваш_id_каталога",
  "auth": {
    "service_account_key_file": "config/service_account_key.json",
    "openssl_bin": "openssl"
  }
}

auth.service_account_key_file — путь к ключу. Относительные пути отсчитываются от корня скилла, не от config/. Можно указать абсолютный путь.

Если доступ уже настроен для скилла yandex-search-api, можно использовать тот же ключ сервисного аккаунта и каталог: схема config.json одинакова. Скопируйте файлы в config/ этого скилла или укажите абсолютный путь к существующему ключу.

Шаг 6: Проверьте

sh scripts/quota.sh

При успешном запросе скрипт выведет Wordstat API: OK. Проверка обращается к API.

Dynamics: ограничения операторов

Метод dynamics (scripts/dynamics.sh) поддерживает все операторы поиска Wordstat только при детализации daily. При weekly и monthly доступен только оператор +.

Это ограничение на стороне Yandex Cloud Search API — задокументировано в официальной документации.

Скилл проверяет фразу перед отправкой: если вы запустите dynamics.sh --period weekly --phrase "юрист -бесплатно", скрипт завершится с понятной ошибкой до запроса.

Устранение ошибок

Wordstat API: Error / wordstat 401

• IAM: проверьте, что файл ключа содержит действующий авторизованный ключ сервисного аккаунта. Если ключ отозван или повреждён, создайте новый по основной инструкции.
• IAM: токен обновляется автоматически. Вручную получать OAuth-токен не нужно.
• API-ключ: проверьте значение YANDEX_AI_API_KEY, срок действия, отсутствие отзыва и область yc.search-api.execute. API-ключ не обновляется автоматически; при истечении или отзыве выпустите новый. Создавать JSON-ключ для этого режима не требуется.

Wordstat 403 Forbidden

• Роль search-api.webSearch.user не назначена сервисному аккаунту, либо вы пытаетесь обратиться не к тому каталогу.
• Проверьте yandex_cloud_folder_id в config.json.

LibreSSL detected (macOS)

macOS по умолчанию использует LibreSSL, который не поддерживает PS256 для подписи JWT.

brew install openssl@3

И в config.json:

{
  "auth": {
    "openssl_bin": "/opt/homebrew/bin/openssl"
  }
}

Узнать точный путь: brew --prefix openssl.

Неполная или неверная настройка config/config.json

• yandex_cloud_folder_id пустой → заполните
• Файл ключа не найден по пути из auth.service_account_key_file → проверьте, что файл есть и читается. Помните: относительные пути отсчитываются от корня скилла, а не от config/.

Дополнительно

• Документация Wordstat API
• Актуальные квоты и лимиты Wordstat
• Тарификация
• Операторы поиска

Альтернатива: API-ключ сервисного аккаунта

Сервисный аккаунт и роль search-api.webSearch.user нужны и в этом режиме. JSON с авторизованным ключом, подпись JWT и получение IAM-токена не требуются.

1. Откройте консоль Yandex Cloud, выберите каталог → Identity and Access Management → Сервисные аккаунты → нужный аккаунт → API-ключи.

2. Создайте API-ключ с областью действия yc.search-api.execute. Укажите её явно, не полагайтесь на значения по умолчанию. Эквивалент через CLI:

   yc iam api-key create --service-account-name <имя> --scopes yc.search-api.execute

3. Скопируйте config/.env.example в config/.env и впишите ключ в YANDEX_AI_API_KEY. Задайте права chmod 600 config/.env. Этот файл секретный; не добавляйте его в Git.

4. В config/config.json сохраните yandex_cloud_folder_id, а auth задайте как {"mode": "api_key"}.

5. Запустите sh scripts/quota.sh для проверки доступа.

auth.mode может быть iam или api_key. Поле можно не задавать: при наличии auth.service_account_key_file используется IAM, даже если задан YANDEX_AI_API_KEY. Без пути к авторизованному ключу, но с YANDEX_AI_API_KEY, выбирается API-ключ. Существующую IAM-конфигурацию менять не нужно. Старый OAuth API не поддерживается.