Структура запроса к API
Структура запроса
Запрос к API состоит из блоков, передаваемых в URL:
-
обращение к хосту API с указанием версии;
-
авторизация;
-
навигационный блок;
-
параметры.
В качестве разделителя параметров используется символ & (амперсанд).
Параметр и значение разделяются символом = (равно).
Внимание
API Adfox является регистрозависимым — все имена объектов нужно передавать с применением заглавных и строчных букв, как указано в документе.
Обращение к хосту API с указанием версии
Хост для всех запросов к API:
https://adfox.yandex.ru/api/vX
где X — номер версии, начиная с 1 (версия v0 не поддерживается).
Например, запрос к API версии 1 будет такой:
https://adfox.yandex.ru/api/v1
Навигационный блок
Один запрос к API позволяет выполнить одно действие.
В запросе необходимо передать информацию о том, в каком контексте какое действие необходимо произвести с объектом.
За эту информацию отвечает навигационный блок с параметрами:
-
object
— контекст, в котором производится действие. -
action
— действие, производимое над объектом. Для каждого контекста определен набор возможных действий. Примеры действий:-
add — добавление объекта (доступно только в контексте account);
-
list — получение списка;
-
modify — редактирование объекта;
-
update — изменение параметров объекта;
-
delete — удаление объекта (доступно только в контексте account).
-
-
actionObject
— имя объекта, над которым производится действие. В некоторых методах actionObject может отсутствовать (например, в методах: account-auth, advertiser-modify, assistant-modify).
Параметры
Последний блок в запросе API составляют параметры вызываемого метода:
-
обязательные
— например: -
необязательные
— параметры указываются в квадратных скобках, например:Если параметр не будет передан в запросе, то 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 запросов одновременно для одного владельца аккаунта.