From e6ea4dfaeea0825423fa6e60da481b1ef6ea2a38 Mon Sep 17 00:00:00 2001 From: neo <397763@gmail.com> Date: Sun, 5 Jul 2026 14:47:01 +0500 Subject: [PATCH] Initial commit: add README with API usage instructions --- README.md | 180 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 178 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d64bb90..8917720 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,179 @@ -# yandex-api +# Yandex API — локальные прокси-сервисы -Yandex Direct API + Wordstat API — локальный прокси-сервис \ No newline at end of file +Два сервиса для работы с Яндекс.Директ API v5 и Яндекс.Вордстат (Yandex Cloud Search API v2), запущенные на `192.168.1.152` (nik). + +## Сервисы + +| Сервис | Порт | Назначение | +|--------|------|-----------| +| **Yandex Direct API** | 8456 | Управление кампаниями, группами, объявлениями, ключевыми словами | +| **Wordstat API** | 8457 | Сбор частотности, топ-запросы, динамика, география | + +## Быстрый старт + +### Подключение с другого компьютера в сети + +С других машин локальной сети (192.168.1.x) сервисы доступны напрямую по HTTP: + +```bash +# Проверка доступности +curl http://192.168.1.152:8456/ +curl http://192.168.1.152:8457/health + +# Простой запрос — без ключей (статус) +curl http://192.168.1.152:8456/ +curl http://192.168.1.152:8457/health +``` + +> **Примечание:** для запросов к реальному API (не /health) сервисы используют токены, захардкоженные в `config.py` на сервере. Ключи не нужно передавать в запросах. + +### Создание кампаний (Direct API) + +```bash +# Получить статус сервера +curl http://192.168.1.152:8456/ + +# Список кампаний +curl http://192.168.1.152:8456/campaigns + +# Создать кампанию +curl -X POST http://192.168.1.152:8456/campaigns \ + -H "Content-Type: application/json" \ + -d '{"name":"Моя кампания","daily_budget_rub":500,"strategy":"HIGHEST_POSITION"}' + +# Создать группу объявлений +curl -X POST http://192.168.1.152:8456/adgroups \ + -H "Content-Type: application/json" \ + -d '{"name":"Группа 1","campaign_id":709606618,"region_ids":[225]}' + +# Создать объявление +curl -X POST http://192.168.1.152:8456/ads \ + -H "Content-Type: application/json" \ + -d '{"adgroup_id":5747798281,"title":"Заголовок до 56 символов","text":"Текст объявления","href":"https://example.com"}' + +# Добавить ключевые фразы +curl -X POST http://192.168.1.152:8456/keywords \ + -H "Content-Type: application/json" \ + -d '{"adgroup_id":5747798281,"keywords":[{"keyword":"купить слона","bid_rub":50}]}' + +# Управляемые аккаунты (client_login) +curl http://192.168.1.152:8456/campaigns?client_login=casamebelads + +# Регионы (с кириллицей — URL-кодировать!) +curl -s -G 'http://192.168.1.152:8456/dictionaries/regions' --data-urlencode 'search=Иглино' +``` + +### Сбор частотности (Wordstat API) + +```bash +# Получить частотность запроса +curl -X POST http://192.168.1.152:8457/top \ + -H "Content-Type: application/json" \ + -d '{"phrase":"деревянные дома"}' + +# Получить динамику по времени +curl -X POST http://192.168.1.152:8457/dynamics \ + -H "Content-Type: application/json" \ + -d '{"phrase":"купить деревянный дом"}' + +# Распределение по регионам +curl -X POST http://192.168.1.152:8457/regions \ + -H "Content-Type: application/json" \ + -d '{"phrase":"деревянные дома"}' + +# Справочник регионов (бесплатно, без квоты) +curl http://192.168.1.152:8457/regions/tree + +# Статус API-ключа +curl http://192.168.1.152:8457/oauth/status + +# Сохранённые ключевые слова +curl http://192.168.1.152:8457/keywords +``` + +## API-ключи и авторизация + +Сервисы работают как локальный прокси — ключи хранятся на сервере `192.168.1.152`: + +### Яндекс.Директ API (порт 8456) +- **OAuth-токен:** захардкожен в `config.py` на сервере +- **Режим:** production +- Для переключения на управляемые аккаунты — параметр `client_login` + +### Wordstat API (порт 8457) +- **Yandex Cloud API Key:** хранится в `/home/neo/workspace/wordstat-api/.env` +- **Folder ID:** `b1g666nmgcdb1j6e551t` +- Получить ключ: https://aistudio.yandex.ru/ + +## Изменение API-ключей + +Если нужно сменить ключи, подключись к `nik@192.168.1.152` по SSH и отредактируй конфиги: + +```bash +# SSH на сервер +ssh nik@192.168.1.152 + +# Яндекс.Директ API — токен в config.py +nano /home/neo/workspace/yandex-direct-api/config.py + +# Wordstat API — ключ в .env +nano /home/neo/workspace/wordstat-api/.env + +# Перезапуск сервисов +systemctl --user restart yandex-direct-api +systemctl --user restart wordstat-api +``` + +## Удалённое подключение + +С любого компьютера в сети `192.168.1.x`: + +```python +import requests + +# Яндекс.Директ +resp = requests.get("http://192.168.1.152:8456/") +print(resp.json()) # {"ok": true, "mode": "production", ...} + +# Wordstat +resp = requests.get("http://192.168.1.152:8457/health") +print(resp.json()) # {"status": "ok", "api_key_set": true, ...} +``` + +## Порты и фаервол + +Порты 8456 и 8457 должны быть доступны в локальной сети. Проверить: + +```bash +# На сервере nik +ss -tlnp | grep -E '845[67]' + +# Если порты не слушаются — проверить systemd сервисы +systemctl --user status yandex-direct-api wordstat-api +``` + +Если фаервол (UFW/firewalld) блокирует — разрешить: + +```bash +sudo ufw allow from 192.168.1.0/24 to any port 8456 +sudo ufw allow from 192.168.1.0/24 to any port 8457 +``` + +## Ограничения и известное + +- **Wordstat квота:** 100 запросов/час, 10/сек. Легко сжечь за минуту. +- **Wordstat status: Preview** — API может измениться. +- **Директ:** бюджет кампании минимум 300₽. +- **Директ API:** стратегия сетей `MAXIMUM_COVERAGE` не работает, использовать `SERVING_OFF`. +- **Директ API:** поле `DailyBudget: null` после создания — кампания может работать без лимита. +- **Директ API:** `ads/get` — допустимы ТОЛЬКО: AdCategories, AgeLabel, AdGroupId, CampaignId, Id, State, Status, StatusClarification, Type, Subtype. TextAd, MobileAppAd и т.д. НЕЛЬЗЯ. +- **Директ API:** GeoRegion children часто пустые. Использовать `client.get_regions(search=...)` вместо `get_dictionaries`. +- **Директ API:** активация кампании из DRAFT → ENABLED может требовать `update_campaigns` (множественное число) или веб-интерфейс. + +## Ссылки + +- Сервис Direct API: `/home/neo/workspace/yandex-direct-api/` +- Сервис Wordstat API: `/home/neo/workspace/wordstat-api/` +- Документация Директ API: https://yandex.ru/dev/direct/doc/ru/ +- Документация Wordstat API: https://yandex.cloud/ru/docs/search-api/api-ref/wordstat +- AI Studio (API ключи): https://aistudio.yandex.ru/