Введение
API сервиса Яндекс.Аудитории позволяет:
- Управлять сегментами.
- Управлять представителями.
- Управлять аккаунтами и доступами.
Для использования API Яндекс.Аудиторий необходима авторизация с помощью OAuth-токена. Необходимо отправлять авторизационный токен в каждом запросе к API.
Для иллюстрации возможностей API в справочнике приведены примеры обращения к сервису. Методы в примерах возвращают демонстрационные данные, доступные для просмотра всем пользователям.
Структура API
API включает в себя следующие разделы:
- Управление сегментами — позволяет получать, создавать и удалять сегменты. Для создания сегментов можно использовать: собственные данные, сегменты из Метрики, данные на основе геолокации, а также существующие сегменты (lookalike).
- Управление разрешениями — позволяет получать информацию о текущих разрешениях, а также создавать и удалять разрешения на работу с сегментами.
- Управление аккаунтами — позволяет получать список аккаунтов, представителем которых является пользователь.
- Управление представителями — позволяет создавать, изменять и удалять представителей аккаунтов.
- Управление пикселями — позволяет создавать, изменять и удалять пиксели.
Версионирование
Все разделы API Яндекс.Аудиторий поддерживают версионирование. У каждой версии есть определенный идентификатор (v1, v2 и т. п.). При выходе новой версии API предыдущая версия продолжает работать для поддержания обратной совместимости.
Если вы начинаете работу с API, используйте самую последнюю версию. Если вы уже используете предыдущие версии API, рекомендуем постепенно переходить на последнюю, т. к. поддержка старых версий ограничена во времени.
При формировании запроса к API всегда указывайте версию, с которой вы хотите работать.
https://api-audience.yandex.ru/v1/management/...
https://api-audience.yandex.ru/v2/management/...
Ресурсы
API Яндекс.Аудиторий построен по REST-принципам.
Все, чем можно управлять через API, представлено в виде ресурсов: сегмент, список сегментов, доступы к сегменту и т. д.
- читать содержимое и текущее состояние ресурса (GET);
- изменять содержимое и состояние и записывать его в ресурс (PUT);
- удалять ресурс (DELETE);
- выполнять специальные действия ― например, добавлять новые сегменты (POST).
У каждого ресурса есть свой уникальный URL. Все действия выполняются соответствующими методами протокола HTTP на URL'ы ресурсов.
Например, чтобы получить список сегментов, необходимо сделать GET-запрос на URL списка сегментов. А чтобы создать новый сегмент, необходимо сделать POST-запрос с телом сегмента на URL сегмента.