Структура запроса к API

Структура запроса

Запрос к API состоит из блоков, передаваемых в URL:

  1. обращение к хосту API с указанием версии;

  2. авторизация;

  3. навигационный блок;

  4. параметры.

В качестве разделителя параметров используется символ & (амперсанд).

Параметр и значение разделяются символом = (равно).

Внимание

API Adfox является регистрозависимым — все имена объектов нужно передавать с применением заглавных и строчных букв, как указано в документе.

1. Обращение к хосту API с указанием версии

Хост для всех запросов к API:

https://adfox.yandex.ru/api/vX

где X — номер версии, начиная с 1 (версия v0 не поддерживается).

Например, запрос к API версии 1 будет такой:

https://adfox.yandex.ru/api/v1

2. Авторизация

Авторизоваться в API Adfox можно с помощью OAuth-токена Яндекса. Токен необходимо передавать для каждого метода в HTTP-заголовке Authorization.

GET api/v1 HTTP/1.1
Host: adfox.yandex.ru
Authorization: OAuth 05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

Чтобы получить токен:

  1. Перейдите на страницу Создание приложения.

  2. Заполните поля:

    • Название вашего сервиса;
    • Иконка сервиса — опционально;
    • Платформы приложения — добавьте одну или несколько платформ;
    • Redirect URL — укажите https://oauth.yandex.ru/verification_code;
    • Доступ к данным — укажите adfox:api;
    • Почта для связи — опционально.
  3. Нажмите Создать приложение и скопируйте его ClientID ().

  4. Добавьте скопированный ClientID в ссылку вида https://oauth.yandex.ru/authorize?response_type=token&client_id=<идентификатор приложения>.

  5. Перейдите по ссылке и на открывшейся странице скопируйте ваш авторизационный токен.

Если метод API вызван без токена или в запросе передан недействительный токен, сервер возвращает HTTP-статус 401 Unauthorized.

3. Навигационный блок

Один запрос к API позволяет выполнить одно действие.

В запросе необходимо передать информацию о том, в каком контексте какое действие необходимо произвести с объектом.

За эту информацию отвечает навигационный блок с параметрами:

  1. object — контекст, в котором производится действие.

  2. action — действие, производимое над объектом. Для каждого контекста определен набор возможных действий. Примеры действий:

    • add — добавление объекта (доступно только в контексте account);
    • list — получение списка;
    • modify — редактирование объекта;
    • update — изменение параметров объекта;
    • delete — удаление объекта (доступно только в контексте account).
  3. actionObject — имя объекта, над которым производится действие. В некоторых методах actionObject может отсутствовать (например, в методах: account-auth, advertiser-modify, assistant-modify).

4. Параметры

Последний блок в запросе API составляют параметры вызываемого метода:

  1. обязательные — например:

  2. необязательные — параметры указываются в квадратных скобках, например:

    Если параметр не будет передан в запросе, то API будет использовать для этого параметра значение по умолчанию. Значения по умолчанию смотрите на странице у конкретного actionObject.


Поиск нужного метода в документации

Описания методов API в документе сгруппированы по контекстам, в которых они производятся, а внутри контекста — по типам действий. Поэтому чтобы найти нужный метод в документе, нужно построить цепочку контекст—действие—объект, аналогичную навигационному блоку запроса. Ниже приведено несколько примеров.

Добавить рекламную кампанию

Все новые объекты добавляются в контексте account.

Открываем в меню документации раздел account.

Далее выбираем раздел с действием, которое необходимо совершить — в нашем случае — добавление (add).

И выбираем из списка тот объект, который необходимо добавить — campaign.

Навигационный блок будет таким:

object=account&action=add&actionObject=campaign
Добавить баннер

Все новые объекты добавляются в контексте account.

Открываем в меню документации раздел account.

Далее выбираем раздел с действием, которое необходимо совершить, в нашем случае — добавление (add).

И выбираем из списка тот объект, который необходимо добавить — banner.

Навигационный блок будет таким:

object=account&action=add&actionObject=banner
Редактировать параметры баннера

Открываем в меню документации раздел banner, так как действие нужно произвести с уже существующим объектом.

Далее выбираем раздел с действием, которое необходимо совершить, в нашем случае — редактирование (modify).

И выбираем из списка тот объект, который необходимо редактировать — banner.

Навигационный блок будет таким:

object=banner&action=modify&actionObject=banner
Таргетировать баннер по частоте

Открываем в меню документации раздел banner, так как действие нужно произвести с уже существующим объектом.

Далее выбираем раздел с действием, которое необходимо совершить, в нашем случае — таргетирование (target).

И выбираем из списка тот объект, который необходимо редактировать — targetingFrequency.

Навигационный блок будет таким:

object=banner&action=target&actionObject=targetingFrequency

Варианты передачи параметров в запросе к API

Существует два варианта передачи блока навигации и блока с параметрами запроса:

Параметры запроса передаются в URL (GET)

В таком варианте все параметры передаются непосредственно в URL запроса к API. Параметры разделяются с помощью & (амперсанд), а пара «параметр-значение» записывается через знак = (равно).

Порядок действий:

1. Составьте запрос к API, состоящий из:

  • обращения к хосту;
https://adfox.yandex.ru/api/v1?
  • блока навигации:
object=account&action=add&actionObject=campaign&
  • параметров запроса (обязательных и, при необходимости, необязательных):
name=Adfox_company&advertiser=427&status=1&level=5

2. В результате получим:

https://adfox.yandex.ru/api/v1?object=account&action=add&actionObject=campaign&name=Adfox_company&advertiser=427&status=1&level=5
Параметры запроса передаются в тело (POST)

В таком варианте запрос собирается из обращения к хосту:

https://adfox.yandex.ru/api/v1

И параметров запроса в Body:

--form 'object=account' \
--form 'action=list' \
--form 'actionObject=website' \

Пример POST запроса:

curl -k --location --request POST 'https://adfox.yandex.ru/api/v1' \
--header 'Authorization: OAuth 05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037' \
--form 'object=account' \
--form 'action=list' \
--form 'actionObject=website' \

Формат передачи значений «Дата и время»

Формат передачи даты: YYYY-MM-DD.

Формат передачи времени: HH:mm.

Формат передачи времени с секундами: HH:mm:ss.

Формат передачи даты и времени: YYYY-MM-DD HH:mm, где

  • YYYY — год;
  • MM — месяц;
  • DD — день;
  • HH — час;
  • mm — минута.

Примечание

Значения даты и времени записываются через пробел.

Например:

dateStart=2022-04-25 11:00&action=…

Примечание

Для параметров дата/время — время является необязательным значением. По умолчанию выставляется в 00:00.

Кодировка входных параметров

Если в запросе к API передаются кириллические символы, то необходимо указывать кодировку входных параметров в параметре encoding.

Возможные значения:

  • UTF-8 (рекомендуется);
  • CP-1251.

Например:

encoding=UTF-8

Лимиты количества запросов

Для запросов действуют ограничения по количеству — не более:

  • 100 запросов в минуту;
  • 3 запросов одновременно для одного владельца аккаунта.
Предыдущая
Следующая