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

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

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

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

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

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

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

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

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

Внимание

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

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

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

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

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

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

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

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

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

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

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

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

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

    • add — добавление объекта (доступно только в контексте account);

    • list — получение списка;

    • modify — редактирование объекта;

    • update — изменение параметров объекта;

    • delete — удаление объекта (доступно только в контексте account).

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

Параметры

Последний блок в запросе 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 запросов одновременно для одного владельца аккаунта.

Предыдущая
Следующая