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

  1. Структура запроса
  2. 1. Обращение к хосту API с указанием версии
  3. 2. Авторизация
  4. 3. Навигационный блок
  5. 4. Параметры
  6. Формат передачи значений «Дата и время»
  7. Кодировка входных параметров

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

Запрос к 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
Примечание. Старый домен api.adfox.ru/v1/API.php поддерживается до 1 марта 2020 года. На новом домене авторизация осуществляется только через OAuth-токен.

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

Авторизация осуществляется через OAuth-токен. Авторизация с помощью логина и пароля поддерживается до 1 марта 2020 года.

Для генерации токена потребуется кабинет разработчика:

  1. Авторизуйтесь в кабинете разработчика, используя аккаунт на Яндексе, связанный с аккаунтом в ADFOX.
  2. Нажмите Подключить API и выберите сервис ADFOX.
  3. Ознакомьтесь с условиями использования API сервиса ADFOX.
  4. Укажите название ключа и нажмите Добавить ключ.

В HTTP-заголовке X-Yandex-API-Key укажите полученный OAuth-токен. Токен необходимо передавать в HTTP-заголовке при каждом запросе.

curl -H 'X-Yandex-API-Key: 2f3e783b...' https://adfox.yandex.ru/api/v1?object=account&action=list&actionObject=position

В случае неудачной авторизации API вернет XML-ответ с ошибкой « Authorization failed ».

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

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

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

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

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

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

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

    В некоторых методах actionObject может отсутствовать (например, в методах: account-changePassword, 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 'X-Yandex-API-Key: <YOUR-API-KEY>' \
--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=2015-04-25 11:00&action=…
Примечание. Для параметров дата/время — время является необязательным значением. По умолчанию выставляется в 00:00.

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

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

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

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

Например:

encoding=UTF-8