Документация
Справочник разработчика
Управление аккаунтами
Следующая Ctrl 

Введение

API сервиса Яндекс.Аудитории позволяет:

  • Управлять сегментами.
  • Управлять представителями.
  • Управлять аккаунтами и доступами.

Для использования API Яндекс.Аудиторий необходима авторизация с помощью OAuth-токена. Необходимо отправлять авторизационный токен в каждом запросе к API.

Для иллюстрации возможностей API в справочнике приведены примеры обращения к сервису. Методы в примерах возвращают демонстрационные данные, доступные для просмотра всем пользователям.

Структура API

API включает в себя следующие разделы:

  • Управление сегментами — позволяет получать, создавать и удалять сегменты. Для создания сегментов можно использовать: собственные данные, сегменты из Метрики, пересечение/объединение/вычитание существующих сегментов.
  • Управление разрешениями — позволяет получать информацию о текущих разрешениях, а также создавать и удалять разрешения на работу с сегментами.
  • Управление аккаунтами — позволяет получать список аккаунтов, представителем которых является пользователь.
  • Управление представителями — позволяет создавать, изменять и удалять представителей аккаунтов.
  • Управление пикселями — позволяет создавать, изменять и удалять пиксели.

Версионирование

Все разделы 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 сегмента.