Структура запроса к API
Структура запроса
Запрос к API состоит из блоков, передаваемых в URL:
-
обращение к хосту API с указанием версии;
-
авторизация;
-
навигационный блок;
-
параметры.
В качестве разделителя параметров используется символ & (амперсанд).
Параметр и значение разделяются символом = (равно).
Внимание
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
Чтобы получить токен:
-
Перейдите на страницу Создание приложения.
-
Заполните поля:
- Название вашего сервиса;
- Иконка сервиса — опционально;
- Платформы приложения — добавьте одну или несколько платформ;
- Redirect URL — укажите
https://oauth.yandex.ru/verification_code
; - Доступ к данным — укажите
adfox:api
; - Почта для связи — опционально.
-
Нажмите Создать приложение и скопируйте его ClientID ().
-
Добавьте скопированный ClientID в ссылку вида https://oauth.yandex.ru/authorize?response_type=token&client_id=<идентификатор приложения>.
-
Перейдите по ссылке и на открывшейся странице скопируйте ваш авторизационный токен.
Если метод API вызван без токена или в запросе передан недействительный токен, сервер возвращает HTTP-статус 401 Unauthorized
.
3. Навигационный блок
Один запрос к API позволяет выполнить одно действие.
В запросе необходимо передать информацию о том, в каком контексте какое действие необходимо произвести с объектом.
За эту информацию отвечает навигационный блок с параметрами:
-
object
— контекст, в котором производится действие. -
action
— действие, производимое над объектом. Для каждого контекста определен набор возможных действий. Примеры действий:- add — добавление объекта (доступно только в контексте account);
- list — получение списка;
- modify — редактирование объекта;
- update — изменение параметров объекта;
- delete — удаление объекта (доступно только в контексте account).
-
actionObject
— имя объекта, над которым производится действие. В некоторых методах actionObject может отсутствовать (например, в методах: account-auth, advertiser-modify, assistant-modify).
4. Параметры
Последний блок в запросе 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 запроса к 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
В таком варианте запрос собирается из обращения к хосту:
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 запросов одновременно для одного владельца аккаунта.