Действия пользователя при работе с программным интерфейсом AdRiver
- Аутентификация в системе
- Работа с сайтами
- Работа с зонами сайта
- Работа с рекламными кампаниями
- Работа со слайсами
- Работа с пулами
- Работа со сценариями
- Работа с баннерами
- Загрузка баннеров
Для работы с программным интерфейсом необходимо иметь зарегистрированный аккаунт в системе AdRiver. Если аккаунт ранее не создавался, следует зарегистрироваться в системе, поскольку параметры аккаунта (имя пользователя и пароль) будут использоваться для аутентификации в системе через программный интерфейс.
1. Аутентификация в системе
Аутентификация в системе осуществляется с использованием идентификатора (user_id) и ключа аутентификации (token) в системе AdRiver. Соответствующие параметры должны передаваться в качестве HTTP-заголовков каждого запроса к программному интерфейсу.
X-Auth-UserID:user_id X-Auth-Passwd:token
Для получения значений этих параметров необходимо однократно выполнить запрос, в котором в качестве заголовков передаются значения действующих наименования учетной записи и пароля пользователя в системе AdRiver.
В ответе на такой запрос пользователю передаются параметры user_id (идентификатор пользователя в системе) и token (ключ аутентификации) для дальнейшей работы в системе.
Content-Type:application/atom+xml X-Auth-Login:plain_login X-Auth-Passwd:plain_password
Запрос передается в формате Atom Syndication Format.
Пример запроса для аутентификации (формат atom+xml):
GET/login Content-Type: application/atom+xml X-Auth-Login:plain_login X-Auth-Passwd:plain_password
Вид ответа в случае подтверждения переданных в запросе параметров: наименования учетной записи и пароля пользователя (успешная аутентификация):
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<title>AdRiver login authentication parameters</title>
<updated>2011-06-27T13:04:33+04:00</updated>
<author>
<name>Adriver::RestAPI::Login</name>
</author>
<adriver:userId>12345</adriver:userId>
<adriver:token>%5DY%00%AA%00%0Fm%2F%03</adriver:token>
</entry>
Примечания к коду:
- 12345 — идентификатор пользователя.
- %5DY%00%AA%00%0Fm%2F%03 — ключ аутентификации.
Вид ответа в случае отсутствия подтверждения переданных в запросе параметров: наименования учетной записи и пароля пользователя (ошибка аутентификации):
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>AdRiver login authentication error</title>
<updated>2011-06-27T13:05:40+04:00</updated>
<author>
<name>Adriver::RestAPI::Login</name>
</author>
<content type="text">bad login or password</content>
</entry>
2. Работа с сайтами
Использование программного интерфейса позволяет осуществлять следующие операции с сайтами в системе AdRiver:
- добавление сайта;
- просмотр списка сайтов;
- изменение сайта;
- просмотр данных сайта.
Параметры, используемые при работе с сайтами в AdRiver через программный интерфейс, подразделяются на обязательные и необязательные. Обязательные параметры необходимо использовать при создании и редактировании сайта. Значения всех параметров, определенных для сайтов (как обязательных, так и необязательных) выдаются системой при ответе на запрос.
Обязательные параметры:
- userId – идентификатор учетной записи в системе (определяется при аутентификации);
- name – наименование сайта;
- url – адрес ресурса (сайта) в сети Интернет;
- checkSiteUrl – проверять ли (1) соответствие реферера URLу и алиасам сайта при показе (не проверять – 0);
- enable – разрешение на обработку запросов с этого сайта системой (корректное значение для нормальной работы добавляемого сайта – 1).
Необязательные параметры:
- shortname – краткое название сайта;
- alias.url – другие алиасы сайта;
- defaultBannerType – тип баннера по умолчанию;
- bannerSpecParams.item – служебные параметры настройки показов различных типов баннеров на сайте, используются только для аккаунтов с правами администратора, более подробная информация по настройке этих параметров находится в приложении.
Более подробную информацию о добавлении и настройке сайта можно получить из документации на сайте.
2.1. Добавление сайта
В теле запроса указываются значения всех обязательных параметров сайта. Пример запроса на добавление сайта.
POST/sites
Content-Type: application/atom+xml
X-Auth-UserID:179221
X-Auth-Passwd:token
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<title>Site Atom Entry</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2011-07-08T16:11:11+04:00</updated>
<author>
<name>1C Media Finance</name>
</author>
<content type="text/xml">
<site xmlns="http://adriver.ru/ns/restapi/atom">
<name>site-check</name>
<shortName>s-c</shortName>
<url>http://someurl.org</url>
<alias>
<url>http://nowhere.org</url>
</alias>
<checkSiteUrl>1</checkSiteUrl>
<enable>1</enable>
<defaultBannerType>1</defaultBannerType>
<bannerSpecParams>
<item>
<action>1</action>
<bannerSpec>31</bannerSpec>
<exposureInterval>1</exposureInterval>
</item>
<item>
<action>0</action>
<bannerSpec>0</bannerSpec>
<exposureInterval>0</exposureInterval>
</item>
<item>
<action>1073829856</action>
<bannerSpec>0</bannerSpec>
<exposureInterval>1073829856</exposureInterval>
</item>
</bannerSpecParams>
<trafficManager>
<name>dimas</name>
<email>dima@adriver.ru</email>
</trafficManager>
</site>
</content>
<adriver:userId>29440</adriver:userId>
</entry>
В случае успешного создания сайта будет возвращено его представление, в котором содержатся все параметры созданного сайта:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-02T19:24:33+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Site Atom Entry</title>
<id>urn:x-adriver:179042</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/sites/179042"/>
<content type="text/xml">
<site xmlns="http://adriver.ru/ns/restapi/atom">
<id>179042</id>
<name>Первый сайт</name>
<shortName/>
<url>http://adriver.ru</url>
<alias>
<url>http://www.adriver.ru </url>
</alias>
<checkSiteUrl>0</checkSiteUrl>
<enable>1</enable>
<defaultBannerType>0</defaultBannerType>
<bannerSpecParams>
<item>
<action>2</action>
<bannerSpec>0</bannerSpec>
<exposureInterval>0</exposureInterval>
</item>
<item>
<action>2</action>
<bannerSpec>0</bannerSpec>
<exposureInterval>0</exposureInterval>
</item>
<item>
...
</item>
<item>
<action>2</action> <bannerSpec>0</bannerSpec> <exposureInterval>0</exposureInterval>
</item>
</bannerSpecParams>
<trafficManager>
<name/>
<email/>
</trafficManager>
</site>
</content>
<adriver:revision>5915bf3725e3ae10cd62c164389ab2904a858f93</adriver:revision>
</entry>
Примечания к коду:
- 179042 — идентификатор добавленного сайта.
- Первый сайт — название добавленного сайта.
- http://adriver.ru — URL добавленного сайта.
- http://www.adriver.ru — алиас добавленного сайта.
- <checkSiteUrl>0</checkSiteUrl> — не проверять соответствие реферера url и алиасам сайта при показе.
- <enable>1</enable> — обработка запросов с добавленного сайта разрешена.
- <action>2</action>, <bannerSpec>0</bannerSpec>, <exposureInterval>0</exposureInterval> — служебные параметры.
- 5915bf3725e3ae10cd62c164389ab2904a858f93 — номер ревизии данных сайта.
Код ответа 201.
2.2. Получение списка сайтов пользователя
Нижеследующий запрос позволяет получить список всех сайтов данного аккаунта (в примере – аккаунта 179221).
GET/sites?user_id=179221 Content-Type:application/atom+xml X-Auth-UserID:179221 X-Auth-Passwd:token
В ответ система возвращает все текущие данные по всем сайтам запрошенного идентификатора аккаунта:
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-07T17:39:18+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Site Atom Feed</title>
<id>https://api.adriver.ru/sites?user_id=179221</id>
<link rel="self" type="application/atom+xml" href="https://api.adriver.ru/sites?user_id=179221"/>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-07T17:39:18+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Site Atom Entry</title>
<id>urn:x-adriver:179042</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/sites/179042"/>
<content type="text/xml">
<site xmlns="http://adriver.ru/ns/restapi/atom">
<id>179042</id>
<name> Первый сайт (adriver.ru)</name>
<shortName/>
<url>http://adriver.ru</url>
<alias>
<url>http://www.adriver.ru</url>
</alias>
<checkSiteUrl>0</checkSiteUrl>
<enable>0</enable>
<defaultBannerType>0</defaultBannerType>
<bannerSpecParams>
<item>
. . .
</item>
</bannerSpecParams>
</site>
</content>
<adriver:revision>960e4109e7680981563d67b106125e7a83bec2d0</adriver:revision>
</entry>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-07T17:39:18+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Site Atom Entry</title>
<id>urn:x-adriver:179172</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/sites/179172"/>
<content type="text/xml">
<site xmlns="http://adriver.ru/ns/restapi/atom">
<id>179172</id>
<name>Второй сайт</name>
<shortName/>
<url>http://adriver.ru</url>
<alias/>
<checkSiteUrl>0</checkSiteUrl>
<enable>1</enable>
<defaultBannerType>0</defaultBannerType>
<bannerSpecParams>
<item>
. . .
</item>
</bannerSpecParams>
</site>
</content>
<adriver:revision>84bedf69f551a98e0614fcbff573752a0246aa56</adriver:revision>
</entry>
</feed>
Код ответа 200.
2.3. Редактирование данных сайта
Если необходимо изменить данные ранее добавленного сайта в AdRiver, то это можно осуществить с помощью запроса на его изменение. Операция редактирования по своей сути аналогична операции добавления сайта, поскольку в соответствующем запросе содержится полный список обязательных параметров сайта.
В отличие от запроса, выполняемого при добавлении сайта, при редактировании данных сайта запрос содержит дополнительный тег <revision>, в который записывается номер ревизии обновляемого объекта. Номер ревизии представляет собой уникальное значение хэш-функции, вычисляемое для данного объекта. Номер ревизии передается сервером клиенту при создании объекта и просмотре его данных. Этот же номер ревизии необходимо передать серверу при модификации созданного ранее объекта. Перед выполнением операции модификации сервер вычисляет собственный номер ревизии объекта и сравнивает его с номером ревизии, переданным клиентом в запросе на модификацию. Только в случае точного совпадения номеров ревизий клиента и сервера операция модификации будет выполнена. Такая схема работы позволяет избежать коллизий при попытке двух или более пользователей системы одновременно изменить один и тот же объект (в данном случае в качестве объекта выступает сайт).
В теле запроса указываются значения всех обязательных параметров сайта. В приведенном примере запрос на редактирование содержит измененное значение наименования сайта (name).
Примечание: При редактировании все данные запроса переписываются заново для редактируемого сайта, независимо от того, изменились ли их значения или нет.
PUT/sites/179042
Content-Type:application/atom+xml
X-Auth-UserID:179221
X-Auth-Passwd:token
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-07T17:25:21+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Site Atom Entry</title>
<id>urn:x-adriver:179042</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/sites/179042"/>
<content type="text/xml">
<site xmlns="http://adriver.ru/ns/restapi/atom">
<id>179042</id>
<name>Первый сайт (adriver.ru)</name>
<shortName/>
<url>http://adriver.ru</url>
<alias>
<url>http://www.adriver.ru</url>
</alias>
<checkSiteUrl>0</checkSiteUrl>
<enable>0</enable>
<defaultBannerType>0</defaultBannerType>
<bannerSpecParams>
<item>
</site>
</content>
<adriver:revision>230c72a08450f9fa3ba792d180570ff246a45574</adriver:revision>
</entry>
Примечания к коду
- 230c72a08450f9fa3ba792d180570ff246a45574 — номер ревизии.
В случае успешного редактирования в ответе возвращаются все текущие данные сайта и обновленный номер ревизии, аналогично ответу системы при добавлении сайта.
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-07T18:04:55+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Site Atom Entry</title>
<id>urn:x-adriver:179042</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/sites/179042"/>
<content type="text/xml">
<site xmlns="http://adriver.ru/ns/restapi/atom">
<id>179042</id>
<name>Первый сайт (adriver.ru)</name>
<shortName/>
<url>http://adriver.ru</url>
<alias>
<url>http://www.adriver.ru</url>
</alias>
<checkSiteUrl>0</checkSiteUrl>
<enable>0</enable>
<defaultBannerType>0</defaultBannerType>
<bannerSpecParams>
<item>
. . .
</item>
</bannerSpecParams>
</site>
</content>
<adriver:revision>c67d1bbe001ce72f35b541c349f2ef473b765140</adriver:revision>
</entry>
Примечания к коду
- c67d1bbe001ce72f35b541c349f2ef473b765140 — новый номер ревизии.
Код ответа 200.
В случае ошибки, например, при несовпадении номеров ревизий клиента (в запросе) и сервера, выдается ответ следующего вида:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2011-12-08T17:25:24+04:00</updated>
<content type="text">revision collision for site (id=179042)</content>
<summary>Adriver::RestAPI::Core::Exception::RevisionCollision</summary>
</entry>
Код ответа 412.
2.4. Просмотр данных сайта
Имеется возможность также получить данные сайта по его уникальному идентификатору (id). Идентификатор сайта выдается в ответе системы при добавлении сайта, также можно получить идентификаторы всех сайтов данного аккаунта при просмотре списка сайтов пользователя (п.2.2).
Пример запроса на просмотр данных сайта:
GET/sites/179042
Content-Type:application/atom+xml
X-Auth-UserID:179221 X-Auth-Passwd:token
Примечания к коду
- 179042 — идентификатор сайта, данные которого просматриваются.
В ответ система возвращает все текущие данные по запрошенному идентификатору сайта:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-07T17:25:21+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Site Atom Entry</title>
<id>urn:x-adriver:179042</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/sites/179042"/>
<content type="text/xml">
<site xmlns="http://adriver.ru/ns/restapi/atom">
<id>179042</id>
<name>Первый сайт</name>
<shortName/>
<url>http://adriver.ru</url>
<alias>
<url>http://www.adriver.ru</url>
</alias>
<checkSiteUrl>0</checkSiteUrl>
<enable>0</enable>
<defaultBannerType>0</defaultBannerType>
<bannerSpecParams>
<item>
. . .
</item>
</bannerSpecParams>
</site>
</content>
<adriver:revision>960e4109e7680981563d67b106125e7a83bec2d0</adriver:revision>
</entry>
Код ответа 200.
Примечание: Ответ для удобства приводится без служебных параметров.
3. Работа с зонами сайта
Использование программного интерфейса позволяет осуществлять следующие операции с зонами сайта в AdRiver:
- добавление зоны сайта;
- просмотр списка зон сайта;
- изменение зоны сайта;
- просмотр зоны сайта;
- удаление зоны сайта;
- удаление всего списка зон сайта.
Параметры, используемые при работе с зонами сайтов в системе AdRiver через программный интерфейс, подразделяются на обязательные и необязательные. Обязательные параметры необходимо использовать при создании и редактировании зоны сайта. Значения всех параметров, определенных для зон сайтов (как обязательных, так и необязательных), выдаются системой при ответе на запрос.
Обязательные параметры:
- siteId – идентификатор сайта в системе (отображается при добавлении сайта и чтении списка сайтов);
- name – наименование зоны сайта;
- priority – приоритет зоны сайта.
Необязательные параметры:
- alias – обозначение зоны сайта;
- urls – шаблоны адресов страниц сайта, принадлежащих зоне сайта.
3.1. Добавление зоны сайта
В теле запроса указываются значения всех обязательных параметров зоны сайта. Пример запроса на добавление зоны сайта:
POST/sites/179042/sitezones
Content-Type: application/atom+xml
X-Auth-UserID:179221
X-Auth-Passwd:token
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<content type="text/xml">
<siteZone xmlns="http://adriver.ru/ns/restapi/atom">
<name>Главная</name>
<priority>0</priority>
<alias>main</alias>
<urls>
<url>
<pattern>/body/</pattern>
<operation>AND</operation>
<inverse>0</inverse>
</url>
</urls>
</siteZone>
</content>
<adriver:siteId>179042</adriver:siteId>
</entry>
Примечание: Если необходимо задать шаблоны для зоны сайта (urls), то в этом случае следует также задать и остальные параметры для шаблона – сам шаблон (pattern), логическую функцию для определения соответствия проверяемого системой реферера данному шаблону (operation), а также функцию инвертирования результата логической функции (inverse). Более подробную информацию об использовании шаблонов для создания зон сайта можно получить из документации.
В случае успешного создания зоны сайта будет возвращено ее представление:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-08T17:57:09+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>SiteZone Atom Entry</title>
<id>https://api.adriver.ru/sites/179042/sitezones/1</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/sites/179042/sitezones/1"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/sites/179042"/>
<adriver:siteId>179042</adriver:siteId>
<content type="text/xml">
<siteZone xmlns="http://adriver.ru/ns/restapi/atom">
<id>1</id>
<name>Главная</name>
<priority>0</priority>
<alias>main</alias>
<urls>
<url>
<pattern>/body/</pattern>
<operation>AND</operation>
<inverse>0</inverse>
</url>
</urls>
</siteZone>
</content>
<adriver:revision>92003781446124c3cde3aa65e515fc9fc2f2ca76</adriver:revision>
</entry>
Примечания к коду
- <id>1</id> — номер зоны сайта.
- 92003781446124c3cde3aa65e515fc9fc2f2ca7— номер ревизии.
Код ответа 201.
3.2. Получение списка зон сайта
Нижеследующий запрос позволяет получить список всех зон данного сайта (в примере – сайта 179042).
GET/sites/179042/sitezones Content-Type:application/atom+xml X-Auth-UserID:179221 X-Auth-Passwd:token
В ответ система возвращает все текущие данные по всем зонам запрошенного идентификатора сайта (в приведенном примере сайт разбит на три зоны):
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-15T11:23:43+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>SiteZone Atom Feed</title>
<id>https://api.adriver.ru/sites/179042/sitezones</id>
<link rel="self" type="application/atom+xml" href="https://api.adriver.ru/sites/179042/sitezones"/>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-15T11:23:43+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>SiteZone Atom Entry</title>
<id>https://api.adriver.ru/sites/179042/sitezones/4</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/sites/179042/sitezones/4"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/sites/179042"/>
<adriver:siteId>179042</adriver:siteId>
<content type="text/xml">
<siteZone xmlns="http://adriver.ru/ns/restapi/atom">
<id>4</id>
<name>Фотокарточки</name>
<priority>0</priority>
<alias>foto</alias>
<urls>
<url>
<pattern>/foto/</pattern>
<operation>AND</operation>
<inverse>0</inverse>
</url>
<url>
<pattern>/foto_old/</pattern>
<operation>OR</operation>
<inverse>0</inverse>
</url>
</urls>
</siteZone>
</content>
<adriver:revision>46c70d0ccf2600dbc31c37d0bd08dc7298d627e9</adriver:revision>
</entry>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-15T11:23:43+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>SiteZone Atom Entry</title>
<id>https://api.adriver.ru/sites/179042/sitezones/5</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/sites/179042/sitezones/5"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/sites/179042"/>
<adriver:siteId>179042</adriver:siteId>
<content type="text/xml">
<siteZone xmlns="http://adriver.ru/ns/restapi/atom">
<id>5</id>
<name>Новости</name>
<priority>1</priority>
<alias>news</alias>
<urls>
<url>
<pattern>/news/</pattern>
<operation>AND</operation>
<inverse>0</inverse>
</url>
<url>
<pattern>/news.php</pattern>
<operation>OR</operation>
<inverse>0</inverse>
</url>
</urls>
</siteZone>
</content>
<adriver:revision>2a86a5b018d7214c63dbdaab1d76c4b1f99e54e2</adriver:revision>
</entry>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-15T11:23:43+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>SiteZone Atom Entry</title>
<id>https://api.adriver.ru/sites/179042/sitezones/1</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/sites/179042/sitezones/1"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/sites/179042"/>
<adriver:siteId>179042</adriver:siteId>
<content type="text/xml">
<siteZone xmlns="http://adriver.ru/ns/restapi/atom">
<id>1</id>
<name>Главная</name>
<priority>2</priority>
<alias>main</alias>
<urls>
<url>
<pattern>/body/</pattern>
<operation>AND</operation>
<inverse>0</inverse>
</url>
</urls>
</siteZone>
</content>
<adriver:revision>2e94a821b89b9264256af90bd7b2c182716ba4cd</adriver:revision>
</entry>
</feed>
Код ответа 200.
3.3. Редактирование зоны сайта
Если необходимо изменить данные ранее добавленной зоны сайта, то это можно осуществить с помощью запроса на ее изменение. Операция редактирования по своей сути аналогична операции добавления зоны сайта, поскольку в соответствующем запросе содержится полный список необходимых параметров зоны сайта.
В отличие от запроса, выполняемого при добавлении зоны сайта, при редактировании данных зоны сайта запрос содержит дополнительный тег <revision>, в который записывается номер ревизии обновляемого объекта, полученный в ответе от сервера. Номер ревизии представляет собой уникальное значение хэш-функции, вычисляемое для данного объекта. Номер ревизии передается сервером клиенту при создании объекта и просмотре его данных. Этот же номер ревизии необходимо передать серверу при модификации созданного ранее объекта. Перед выполнением операции модификации сервер вычисляет собственный номер ревизии объекта и сравнивает его с номером ревизии, переданным клиентом в запросе на модификацию. Только в случае полного совпадения номеров ревизий клиента и сервера операция модификации будет выполнена. Такая схема работы позволяет избежать коллизий при попытке двух или более пользователей системы одновременно изменить один и тот же объект (в данном случае в качестве объекта выступает зона сайта).
В приведенном примере запрос на редактирование содержит дополнительный шаблон адресов страниц сайта для обозначения редактируемой зоны.
Примечание: При редактировании все данные запроса переписываются заново для редактируемой зоны сайта, независимо от того, изменились ли их значения или нет.
PUT/sites/179042/sitezones/1
Content-Type:application/atom+xml
X-Auth-UserID:179221
X-Auth-Passwd:token
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<content type="text/xml">
<siteZone xmlns="http://adriver.ru/ns/restapi/atom">
<name>Главная</name>
<priority>0</priority>
<alias>main</alias>
<urls>
<url>
<pattern>/body/</pattern>
<operation>AND</operation>
<inverse>0</inverse>
</url>
<url>
<pattern>/body.php</pattern>
<operation>AND</operation>
<inverse>0</inverse>
</url>
</urls>
</siteZone>
</content>
<adriver:siteId>179042</adriver:siteId>
<adriver:revision>535baed91354de9bbd7b1737e16a0a106652288d</adriver:revision>
</entry>
Примечания к коду
- /body.php — добавлен новый шаблон.
- 535baed91354de9bbd7b1737e16a0a106652288d — номер ревизии.
В случае успешного редактирования в ответе возвращаются все текущие данные зоны сайта и обновленный номер ревизии, аналогично ответу системы при добавлении зоны сайта.
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-15T10:42:28+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>SiteZone Atom Entry</title>
<id>https://api.adriver.ru/sites/179042/sitezones/1</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/sites/179042/sitezones/1"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/sites/179042"/>
<adriver:siteId>179042</adriver:siteId>
<content type="text/xml">
<siteZone xmlns="http://adriver.ru/ns/restapi/atom">
<id>1</id>
<name>Главная</name>
<priority>0</priority>
<alias>main</alias>
<urls>
<url>
<pattern>/body/</pattern>
<operation>AND</operation>
<inverse>0</inverse>
</url>
<url>
<pattern>/body.php</pattern>
<operation>AND</operation>
<inverse>0</inverse>
</url>
</urls>
</siteZone>
</content>
<adriver:revision>535baed91354de9bbd7b1737e16a0a106652288d</adriver:revision>
</entry>
Примечания к коду
- body.php— добавлен новый шаблон.
- 535baed91354de9bbd7b1737e16a0a106652288d — новый номер ревизии.
Код ответа 200.
В случае ошибки, например, при несовпадении номеров ревизий клиента (в запросе) и сервера, выдается ответ следующего вида:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2011-12-08T17:25:24+04:00</updated>
<content type="text">revision collision for sitezone (site_id=179042; sz_id=1)</content>
<summary>Adriver::RestAPI::Core::Exception::RevisionCollision</summary>
</entry>
Код ответа 412.
3.4. Просмотр зоны сайта
Имеется возможность также получить данные зоны сайта по ее номеру. Номер зоны сайта выдается в ответе системы при добавлении зоны сайта, также можно получить номера всех зон данного сайта при просмотре списка зон сайта (п.3.2). Пример запроса на просмотр данных зоны сайта:
GET/sites/179042/sitezones/1 Content-Type: application/atom+xml
X-Auth-UserID:179221
X-Auth-Passwd:token
Примечания к коду
- GET/sites/179042/sitezones/1 — 1 – идентификатор зоны сайта, данные которой просматриваются в строке GET/sites/179042/sitezones/1.
В ответ система возвращает все текущие данные по запрошенному номеру зоны сайта:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-15T10:33:27+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>SiteZone Atom Entry</title>
<id>https://api.adriver.ru/sites/179042/sitezones/1</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/sites/179042/sitezones/1"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/sites/179042"/>
<adriver:siteId>179042</adriver:siteId>
<content type="text/xml">
<siteZone xmlns="http://adriver.ru/ns/restapi/atom">
<id>1</id>
<name>Главная</name>
<priority>0</priority>
<alias>main</alias>
<urls>
<url>
<pattern>/body/</pattern>
<operation>AND</operation>
<inverse>0</inverse>
</url>
</urls>
</siteZone>
</content>
<adriver:revision>535baed91354de9bbd7b1737e16a0a106652288d</adriver:revision>
</entry>
Код ответа 200.
3.5. Удаление зоны сайта
Пример запроса на удаление зоны сайта:
DELETE/sites/179042/sitezones/1 Content-Type:application/atom+xml X-Auth-UserID:179221 X-Auth-Passwd:token
Код ответа 200 (в случае успешного выполнения операции).
Если, например, в запросе на удаление была задана несуществующая зона сайта, ответ системы будет выглядеть следующим образом:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2011-12-15T10:52:32+04:00</updated>
<content type="text">Site zone (site 179042; id 13) not found.</content>
<summary>Adriver::RestAPI::Core::Exception::SiteZone::NotFound</summary>
</entry>
Код ответа 404.
Если же, например, в запросе на удаление зоны сайта был задан несуществующий сайт, ответ системы будет иметь следующий вид:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2011-12-15T10:53:23+04:00</updated>
<content type="text">Site (id 11) not found.</content>
<summary>Adriver::RestAPI::Core::Exception::Site::NotFound</summary>
</entry>
Код ответа 404.
3.6. Удаление всех зон сайта
Пример запроса на удаление всех зон сайта:
DELETE/sites/139884/sitezones Content-Type:application/atom+xml X-Auth-UserID:179221 X-Auth-Passwd:token
Код ответа 200 (в случае успешного выполнения операции).
Если в запросе на удаление всех зон сайта идентификатор сайта имеет неверный формат, ответ системы будет иметь следующий вид:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2011-12-15T11:27:52+04:00</updated>
<content type="text">site id should be a number and you set it to '179213_'</content>
<summary>Adriver::RestAPI::Core::Exception::BadRequest</summary>
</entry>
Код ответа 404.
Если в запросе был задан несуществующий идентификатор сайта, ответ системы будет выглядеть следующим образом:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2011-12-15T11:28:58+04:00</updated>
<content type="text">Site (id 34325435) not found.</content>
<summary>Adriver::RestAPI::Core::Exception::Site::NotFound</summary>
</entry>
Код ответа 404.
Если же в запросе был задан существующий идентификатор сайта, принадлежащий другой учетной записи, то ответ системы будет выглядеть так:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2011-12-15T11:29:58+04:00</updated>
<content type="text">Not authorized to work with object [Adriver::API::Site]</content>
<summary>Adriver::RestAPI::Core::Exception::UnAuthorized</summary>
</entry>
Код ответа 401.
В теле запроса указываются значения всех обязательных параметров рекламной кампании. Пример запроса на добавление рекламной кампании:
4. Работа с рекламными кампаниями
Использование программного интерфейса позволяет осуществлять следующие операции с рекламными кампаниями в системе AdRiver:
- добавление рекламной кампании;
- просмотр списка рекламных кампаний данной учетной записи;
- изменение данных рекламной кампании;
- просмотр данных рекламной кампании;
Параметры, используемые при работе с рекламными кампаниями в системе AdRiver через программный интерфейс, подразделяются на обязательные и необязательные. Обязательные параметры необходимо использовать при создании и редактировании рекламной кампании. Значения всех параметров, определенных для рекламных кампаний (как обязательных, так и необязательных), выдаются системой при ответе на запрос.
Обязательные параметры:
- name — наименование рекламной кампании;
- enable — признак включения рекламной кампании (1 – рекламная кампания включена, 0 – рекламная кампания выключена);
- userId — идентификатор аккаунта – владельца рекламной кампании в системе (определяется при аутентификации).
- canBorrow — использовать общие кредиты (1) или нет (0);
- trafficManager name – имя владельца;
- trafficManager email – email владельца.
Необязательные параметры:
- shortname — краткое название рекламной кампании;
- enables — список доступных для редактирования служебных параметров рекламной кампании;
- externalId — внешний ID рекламной кампании (только для обычных рекламных кампаний)
- supportName — название рекламодателя
-
statusNumber — статус рекламной кампании (только для обычных рекламных кампаний)
- 0 – нет статуса
- 1 – создана
- 2 – готова к старту
- 3 – активна
- 4 – приостановлена
- 5 – отменена
- 6 – завершена
Характеристики рекламной кампании (только для чтения):
- сredit — текущее количество кредитов AdRiver на счету рекламной кампании;
- adPlacements — внутренний параметр для специальных целей.
При запросе списка рекламных кампаний возможно использование следующих фильтров:
- для обычных и сетевых кампаний — фильтр по рекламодателю и статусу РК (поля supportName и statusNumber соответственно);
- только для обычных РК — фильтр по полю externalID.
Более подробную информацию о добавлении и настройке рекламной кампании можно получить из документации.
4.1. Добавление рекламной кампании
POST/ads
Content-Type: application/atom+xml
X-Auth-UserID:179221
X-Auth-Passwd:token
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<content type="text/xml">
<ad xmlns="http://adriver.ru/ns/restapi/atom">
<name>Стартовая кампания</name>
<enable>1</enable>
<canBorrow>1</canBorrow>
</ad>
</content>
<adriver:userId>100000</adriver:userId>
</entry>
В случае успешного создания рекламной кампании будет возвращено ее представление:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-16T19:10:32+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AD Atom Entry</title>
<id>urn:x-adriver:316600</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/ads/316600"/>
<content type="text/xml">
<ad xmlns="http://adriver.ru/ns/restapi/atom">
<id>316600</id>
<name>Стартовая кампания</name>
<shortName>Test_Cmp</shortName>
<enable>1</enable>
<enables/>
<canBorrow>1</canBorrow>
<credit>0</credit>
<trafficManager>
<name/>
<email/>
</trafficManager>
<externalId>1expml</externalId>
<statusNumber>4</statusNumber>
<supportName></supportName>
<adPlacements/>
</ad>
</content>
<adriver:revision>a9578a0817bf8c467890d5cefd3c3d54bd63e3a5</adriver:revision>
</entry>
Примечания к коду
- 316600 — идентификатор рекламной кампании.
- a9578a0817bf8c467890d5cefd3c3d54bd63e3a5 — номер ревизии.
4.2. Получение списка рекламных кампаний пользователя
Нижеследующий запрос позволяет получить список всех рекламных кампаний данного аккаунта (в примере – аккаунта 179221).
GET/ads?user_id=179221 Content-Type:application/atom+xml X-Auth-UserID:179221 X-Auth-Passwd:token
В ответ система возвращает все текущие данные по всем рекламным кампаниям запрошенного идентификатора учетной записи.
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-16T19:29:29+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AD Atom Feed</title>
<id>https://api.adriver.ru/ads?user_id=179221</id>
<link rel="self" type="application/atom+xml" href="https://api.adriver.ru/ads?user_id=179221"/>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-16T19:29:29+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AD Atom Entry</title>
<id>urn:x-adriver:314498</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/ads/314498"/>
<content type="text/xml">
<ad xmlns="http://adriver.ru/ns/restapi/atom">
<id>314498</id>
<name>1</name>
<shortName>1</shortName>
<enable>1</enable>
<enables>
<enable name="EXPOSURE">1</enable>
<enable name="BANNER_UU_REPORT">1</enable>
</enables>
<canBorrow>1</canBorrow>
<credit>0</credit>
<trafficManager>
<name>rest_api</name>
</trafficManager>
<externalId>1expml</externalId>
<statusNumber>4</statusNumber>
<supportName></supportName>
<adPlacements/>
</ad>
</content>
<adriver:revision>64bfa5a3e8fa961bc1a04f1180edab947b6d8b1e</adriver:revision>
</entry>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-16T19:29:29+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AD Atom Entry</title>
<id>urn:x-adriver:316600</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/ads/316600"/>
<content type="text/xml">
<ad xmlns="http://adriver.ru/ns/restapi/atom">
<id>316600</id>
<name>Стартовая кампания</name>
<shortName>startAD</shortName>
<enable>0</enable>
<enables/>
<canBorrow>1</canBorrow>
<credit>0</credit>
<trafficManager>
<name/>
<email/>
</trafficManager>
<externalId>1expml</externalId>
<statusNumber>4</statusNumber>
<supportName></supportName>
<adPlacements/>
</ad>
</content>
<adriver:revision>54fb70fa254ec8116b0a101b79f05951a9211d9b</adriver:revision>
</entry>
</feed>
Код ответа 200.
4.3. Получение списка всех делегированных пользователю кампаний
Метод позволяет получить краткую информацию о рекламных кампаниях, делегированных пользователю, и наборе делегированных прав.
Пример запроса для обычных кампаний:
GET /ads/delegated
Пример запроса для сетевых кампаний:
GET /net_ads/delegated
Результат возвращается в виде XML в формате Atom Syndication Format – объект Atom Entry.
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2013-03-28T17:26:48+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Delegated Objects For AD Atom Feed</title>
<id>http://localhost:3000/ads/delegated</id>
<link rel="self" type="application/atom+xml" href="http://localhost:3000/ads/delegated"/>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2013-03-28T17:26:48+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Delegated Object For AD Atom Entry</title>
<id>http://localhost:3000/ads/94005</id>
<link rel="self" type="application/atom+xml" href="http://localhost:3000/ads/94005"/>
<content type="text/xml">
<delegatedObject xmlns="http://adriver.ru/ns/restapi/atom">
<user>
<id>29440</id>
<login>lycos</login>
<href>http://localhost:3000/users/29440</href>
</user>
<rights>
<right name="COMMON_READ">1</right>
<right name="COMMON_WRITE">1</right>
<right name="AD_ANKETA">1</right>
<right name="AD_STAT">1</right>
<right name="BANNER_ADD">1</right>
<right name="BANNER_READ">1</right>
<right name="BANNER_CHANGE_PROFILE">1</right>
<right name="BANNER_EDIT">1</right>
<right name="BANNER_UPLOAD">1</right>
<right name="BANNER_DELETE">1</right>
<right name="BANNER_STAT">1</right>
<right name="SLICE_ADD">1</right>
<right name="SLICE_READ">1</right>
<right name="SLICE_RELEASE">1</right>
<right name="SLICE_STAT">1</right>
<right name="PROFILE_ADD">1</right>
<right name="PROFILE_READ">1</right>
<right name="PROFILE_EDIT">1</right>
<right name="PROFILE_COPY">1</right>
<right name="PROFILE_DELETE">1</right>
<right name="PROFILE_EXPORT">1</right>
<right name="AD_SITE_GENERAL_STAT">1</right>
<right name="AD_BANNER_GENERAL_STAT">1</right>
</rights>
</delegatedObject>
</content>
</entry>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2013-03-28T17:26:48+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Delegated Object For AD Atom Entry</title>
<id>http://localhost:3000/ads/94007</id>
<link rel="self" type="application/atom+xml" href="http://localhost:3000/ads/94007"/>
<content type="text/xml">
<delegatedObject xmlns="http://adriver.ru/ns/restapi/atom">
<user>
<id>29440</id>
<login>lycos</login>
<href>http://localhost:3000/users/29440</href>
</user>
<rights>
<right name="COMMON_READ">1</right>
<right name="COMMON_WRITE">1</right>
<right name="AD_ANKETA">1</right>
<right name="AD_STAT">1</right>
<right name="BANNER_ADD">1</right>
<right name="BANNER_READ">1</right>
<right name="BANNER_CHANGE_PROFILE">1</right>
<right name="BANNER_EDIT">1</right>
<right name="BANNER_UPLOAD">1</right>
<right name="BANNER_DELETE">1</right>
<right name="BANNER_STAT">1</right>
<right name="SLICE_ADD">1</right>
<right name="SLICE_READ">1</right>
<right name="SLICE_RELEASE">1</right>
<right name="SLICE_STAT">1</right>
<right name="PROFILE_ADD">1</right>
<right name="PROFILE_READ">1</right>
<right name="PROFILE_EDIT">1</right>
<right name="PROFILE_COPY">1</right>
<right name="PROFILE_DELETE">1</right>
<right name="PROFILE_EXPORT">1</right>
<right name="AD_SITE_GENERAL_STAT">1</right>
<right name="AD_BANNER_GENERAL_STAT">1</right>
</rights>
</delegatedObject>
</content>
</entry>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2013-03-28T17:26:48+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Delegated Object For AD Atom Entry</title>
<id>http://localhost:3000/ads/94008</id>
<link rel="self" type="application/atom+xml" href="http://localhost:3000/ads/94008"/>
<content type="text/xml">
<delegatedObject xmlns="http://adriver.ru/ns/restapi/atom">
<user>
<id>29440</id>
<login>lycos</login>
<href>http://localhost:3000/users/29440</href>
</user>
<rights>
<right name="COMMON_READ">1</right>
<right name="COMMON_WRITE">1</right>
<right name="AD_ANKETA">1</right>
<right name="AD_STAT">1</right>
<right name="BANNER_ADD">1</right>
<right name="BANNER_READ">1</right>
<right name="BANNER_CHANGE_PROFILE">1</right>
<right name="BANNER_EDIT">1</right>
<right name="BANNER_UPLOAD">1</right>
<right name="BANNER_DELETE">1</right>
<right name="BANNER_STAT">1</right>
<right name="SLICE_ADD">1</right>
<right name="SLICE_READ">1</right>
<right name="SLICE_RELEASE">1</right>
<right name="SLICE_STAT">1</right>
<right name="PROFILE_ADD">1</right>
<right name="PROFILE_READ">1</right>
<right name="PROFILE_EDIT">1</right>
<right name="PROFILE_COPY">1</right>
<right name="PROFILE_DELETE">1</right>
<right name="PROFILE_EXPORT">1</right>
<right name="AD_SITE_GENERAL_STAT">1</right>
<right name="AD_BANNER_GENERAL_STAT">1</right>
</rights>
</delegatedObject>
</content>
</entry>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2013-03-28T17:26:48+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Delegated Object For AD Atom Entry</title>
<id>http://localhost:3000/ads/94014</id>
<link rel="self" type="application/atom+xml" href="http://localhost:3000/ads/94014"/>
<content type="text/xml">
<delegatedObject xmlns="http://adriver.ru/ns/restapi/atom">
<user>
<id>29440</id>
<login>lycos</login>
<href>http://localhost:3000/users/29440</href>
</user>
<rights>
<right name="COMMON_READ">1</right>
<right name="COMMON_WRITE">1</right>
<right name="AD_ANKETA">1</right>
<right name="AD_STAT">1</right>
<right name="BANNER_ADD">1</right>
<right name="BANNER_READ">1</right>
<right name="BANNER_CHANGE_PROFILE">1</right>
<right name="BANNER_EDIT">1</right>
<right name="BANNER_UPLOAD">1</right>
<right name="BANNER_DELETE">1</right>
<right name="BANNER_STAT">1</right>
<right name="SLICE_ADD">1</right>
<right name="SLICE_READ">1</right>
<right name="SLICE_RELEASE">1</right>
<right name="SLICE_STAT">1</right>
<right name="PROFILE_ADD">1</right>
<right name="PROFILE_READ">1</right>
<right name="PROFILE_EDIT">1</right>
<right name="PROFILE_COPY">1</right>
<right name="PROFILE_DELETE">1</right>
<right name="PROFILE_EXPORT">1</right>
<right name="AD_SITE_GENERAL_STAT">1</right>
<right name="AD_BANNER_GENERAL_STAT">1</right>
</rights>
</delegatedObject>
</content>
</entry>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2013-03-28T17:26:48+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Delegated Object For AD Atom Entry</title>
<id>http://localhost:3000/ads/94825</id>
<link rel="self" type="application/atom+xml" href="http://localhost:3000/ads/94825"/>
<content type="text/xml">
<delegatedObject xmlns="http://adriver.ru/ns/restapi/atom">
<user>
<id>29440</id>
<login>lycos</login>
<href>http://localhost:3000/users/29440</href>
</user>
<rights>
<right name="COMMON_READ">1</right>
<right name="COMMON_WRITE">1</right>
<right name="AD_ANKETA">1</right>
<right name="AD_STAT">1</right>
<right name="BANNER_ADD">1</right>
<right name="BANNER_READ">1</right>
<right name="BANNER_CHANGE_PROFILE">1</right>
<right name="BANNER_EDIT">1</right>
<right name="BANNER_UPLOAD">1</right>
<right name="BANNER_DELETE">1</right>
<right name="BANNER_STAT">1</right>
<right name="SLICE_ADD">1</right>
<right name="SLICE_READ">1</right>
<right name="SLICE_RELEASE">1</right>
<right name="SLICE_STAT">1</right>
<right name="PROFILE_ADD">1</right>
<right name="PROFILE_READ">1</right>
<right name="PROFILE_EDIT">1</right>
<right name="PROFILE_COPY">1</right>
<right name="PROFILE_DELETE">1</right>
<right name="PROFILE_EXPORT">1</right>
<right name="AD_SITE_GENERAL_STAT">1</right>
<right name="AD_BANNER_GENERAL_STAT">1</right>
</rights>
</delegatedObject>
</content>
</entry>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2013-03-28T17:26:48+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Delegated Object For AD Atom Entry</title>
<id>http://localhost:3000/ads/94828</id>
<link rel="self" type="application/atom+xml" href="http://localhost:3000/ads/94828"/>
<content type="text/xml">
<delegatedObject xmlns="http://adriver.ru/ns/restapi/atom">
<user>
<id>29440</id>
<login>lycos</login>
<href>http://localhost:3000/users/29440</href>
</user>
<rights>
<right name="COMMON_READ">1</right>
<right name="COMMON_WRITE">1</right>
<right name="AD_ANKETA">1</right>
<right name="AD_STAT">1</right>
<right name="BANNER_ADD">1</right>
<right name="BANNER_READ">1</right>
<right name="BANNER_CHANGE_PROFILE">1</right>
<right name="BANNER_EDIT">1</right>
<right name="BANNER_UPLOAD">1</right>
<right name="BANNER_DELETE">1</right>
<right name="BANNER_STAT">1</right>
<right name="SLICE_ADD">1</right>
<right name="SLICE_READ">1</right>
<right name="SLICE_RELEASE">1</right>
<right name="SLICE_STAT">1</right>
<right name="PROFILE_ADD">1</right>
<right name="PROFILE_READ">1</right>
<right name="PROFILE_EDIT">1</right>
<right name="PROFILE_COPY">1</right>
<right name="PROFILE_DELETE">1</right>
<right name="PROFILE_EXPORT">1</right>
<right name="AD_SITE_GENERAL_STAT">1</right>
<right name="AD_BANNER_GENERAL_STAT">1</right>
</rights>
</delegatedObject>
</content>
</entry>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2013-03-28T17:26:48+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Delegated Object For AD Atom Entry</title>
<id>http://localhost:3000/ads/212697</id>
<link rel="self" type="application/atom+xml" href="http://localhost:3000/ads/212697"/>
<content type="text/xml">
<delegatedObject xmlns="http://adriver.ru/ns/restapi/atom">
<user>
<id>29440</id>
<login>lycos</login>
<href>http://localhost:3000/users/29440</href>
</user>
<rights>
<right name="COMMON_READ">1</right>
<right name="COMMON_WRITE">1</right>
<right name="AD_ANKETA">1</right>
<right name="AD_STAT">1</right>
<right name="BANNER_ADD">1</right>
<right name="BANNER_READ">1</right>
<right name="BANNER_CHANGE_PROFILE">1</right>
<right name="BANNER_EDIT">1</right>
<right name="BANNER_UPLOAD">1</right>
<right name="BANNER_DELETE">1</right>
<right name="BANNER_STAT">1</right>
<right name="SLICE_ADD">1</right>
<right name="SLICE_READ">1</right>
<right name="SLICE_RELEASE">1</right>
<right name="SLICE_STAT">1</right>
<right name="PROFILE_ADD">1</right>
<right name="PROFILE_READ">1</right>
<right name="PROFILE_EDIT">1</right>
<right name="PROFILE_COPY">1</right>
<right name="PROFILE_DELETE">1</right>
<right name="PROFILE_EXPORT">1</right>
<right name="AD_SITE_GENERAL_STAT">1</right>
<right name="AD_BANNER_GENERAL_STAT">1</right>
</rights>
</delegatedObject>
</content>
</entry>
</feed>
Код ответа: 200.
4.4. Получение списка всех делегированных пользователю сетевых кампаний
Метод позволяет получить краткую информацию о сетевых кампаниях, делегированных пользователю, и наборе делегированных прав. Результат возвращается в виде XML в формате Atom Syndication Format – объект Atom Entry.
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2013-03-28T17:25:14+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Delegated Objects For NetAd Atom Feed</title>
<id>http://localhost:3000/net_ads/delegated</id>
<link rel="self" type="application/atom+xml" href="http://localhost:3000/net_ads/delegated"/>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2013-03-28T17:25:14+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Delegated Object For NetAd Atom Entry</title>
<id>http://localhost:3000/net_ads/80756</id>
<link rel="self" type="application/atom+xml" href="http://localhost:3000/net_ads/80756"/>
<content type="text/xml">
<delegatedObject xmlns="http://adriver.ru/ns/restapi/atom">
<user>
<id>29440</id>
<login>lycos</login>
<href>http://localhost:3000/users/29440</href>
</user>
<rights>
<right name="COMMON_READ">1</right>
<right name="COMMON_WRITE">1</right>
<right name="AD_ANKETA">1</right>
<right name="AD_STAT">1</right>
<right name="BANNER_ADD">1</right>
<right name="BANNER_READ">1</right>
<right name="BANNER_CHANGE_PROFILE">1</right>
<right name="BANNER_EDIT">1</right>
<right name="BANNER_UPLOAD">1</right>
<right name="BANNER_DELETE">1</right>
<right name="BANNER_STAT">1</right>
<right name="SLICE_ADD">1</right>
<right name="SLICE_READ">1</right>
<right name="SLICE_RELEASE">1</right>
<right name="SLICE_STAT">1</right>
<right name="PROFILE_ADD">1</right>
<right name="PROFILE_READ">1</right>
<right name="PROFILE_EDIT">1</right>
<right name="PROFILE_COPY">1</right>
<right name="PROFILE_DELETE">1</right>
<right name="PROFILE_EXPORT">1</right>
<right name="AD_SITE_GENERAL_STAT">1</right>
<right name="AD_BANNER_GENERAL_STAT">1</right>
</rights>
</delegatedObject>
</content>
</entry>
</feed>
Код ответа: 200.
4.5. Получение списка рекламных кампаний с использованием фильтров
Возможно использование следующих фильтров:
- для сетевых и обычных РК – фильтр по полю statusNumber (статус РК) и полю supportName (название рекламодателя);
- для обычных РК – фильтр по полю externalId;
Необходимые фильтры указываются в JSON-объекте, если используется сразу несколько фильтров, они перечисляются через запятую:
GET/ads?filter={"statusNumber":4,"supportName":"AdvertiserName"}
Content-Type:application/atom+xml
X-Auth-UserID:111111
X-Auth-Passwd:token
В примере выше запрашивается список кампаний рекламодателя “AdvertiserName”, которые имеют статус 4.
В ответ система возвращает все текущие данные по всем рекламным кампаниям, удовлетворяющим фильтру:
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-16T19:29:29+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AD Atom Feed</title>
<id>https://api.adriver.ru/ads?user_id=179221</id>
<link rel="self" type="application/atom+xml" href="https://api.adriver.ru/ads?user_id=179221"/>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-16T19:29:29+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AD Atom Entry</title>
<id>urn:x-adriver:314498</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/ads/314498"/>
<content type="text/xml">
<ad xmlns="http://adriver.ru/ns/restapi/atom">
<id>314498</id>
<name>1</name>
<shortName>1</shortName>
<enable>1</enable>
<enables>
<enable name="EXPOSURE">1</enable>
<enable name="BANNER_UU_REPORT">1</enable>
</enables>
<canBorrow>1</canBorrow>
<credit>0</credit>
<trafficManager>
<name>rest_api</name>
</trafficManager>
<externalId>1expml</externalId>
<statusNumber>4</statusNumber>
<supportName>AdvertiserName</supportName>
<adPlacements/>
</ad>
</content>
<adriver:revision>64bfa5a3e8fa961bc1a04f1180edab947b6d8b1e</adriver:revision>
</entry>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-16T19:29:29+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AD Atom Entry</title>
<id>urn:x-adriver:316600</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/ads/316600"/>
<content type="text/xml">
<ad xmlns="http://adriver.ru/ns/restapi/atom">
<id>316600</id>
<name>Стартовая кампания</name>
<shortName>startAD</shortName>
<enable>0</enable>
<enables/>
<canBorrow>1</canBorrow>
<credit>0</credit>
<trafficManager>
<name/>
<email/>
</trafficManager>
<externalId>1expml</externalId>
<statusNumber>4</statusNumber>
<supportName>AdvertiserName</supportName>
<adPlacements/>
</ad>
</content>
<adriver:revision>54fb70fa254ec8116b0a101b79f05951a9211d9b</adriver:revision>
</entry>
</feed>
Код ответа 200.
Пример запроса на получение списка кампаний с фильтром по полю externalId:
GET/ads?filter={"externalId":"AD1000"}
Content-Type:application/atom+xml
X-Auth-UserID:111111
X-Auth-Passwd:token
Пример ответа системы:
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-16T19:29:29+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AD Atom Feed</title>
<id>https://api.adriver.ru/ads?user_id=179221</id>
<link rel="self" type="application/atom+xml" href="https://api.adriver.ru/ads?user_id=179221"/>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-16T19:29:29+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AD Atom Entry</title>
<id>urn:x-adriver:314498</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/ads/314498"/>
<content type="text/xml">
<ad xmlns="http://adriver.ru/ns/restapi/atom">
<id>314498</id>
<name>1</name>
<shortName>1</shortName>
<enable>1</enable>
<enables>
<enable name="EXPOSURE">1</enable>
<enable name="BANNER_UU_REPORT">1</enable>
</enables>
<canBorrow>1</canBorrow>
<credit>0</credit>
<trafficManager>
<name>rest_api</name>
</trafficManager>
<externalId>AD1000</externalId>
<statusNumber>4</statusNumber>
<supportName>AdvertiserName</supportName>
<adPlacements/>
</ad>
</content>
<adriver:revision>64bfa5a3e8fa961bc1a04f1180edab947b6d8b1e</adriver:revision>
</entry>
</feed>
4.6. Редактирование данных рекламной кампании
Если необходимо изменить данные ранее добавленной рекламной кампании, то это можно осуществить с помощью запроса на ее изменение. Операция редактирования по своей сути аналогична операции добавления рекламной кампании, поскольку в соответствующем запросе содержится полный список необходимых параметров рекламной кампании.
В отличие от команды добавления рекламной кампании команда редактирования рекламной кампании содержит дополнительный тег <revision>, в который записывается номер ревизии обновляемого объекта, полученный в ответе от сервера. Номер ревизии представляет собой уникальное значение хэш-функции, вычисляемое для данного объекта. Номер ревизии передается сервером клиенту при создании объекта и просмотре его данных. Этот же номер ревизии необходимо передать серверу при модификации созданного ранее объекта. Перед выполнением операции модификации сервер вычисляет собственный номер ревизии объекта и сравнивает его с номером ревизии, переданным клиентом в запросе на модификацию. Только в случае точного совпадения номеров ревизий клиента и сервера операция модификации будет выполнена. Такая схема работы позволяет избежать коллизий при попытке двух или более пользователей системы одновременно изменить один и тот же объект (в данном случае в качестве объекта выступает рекламная кампания).
В приведенном примере запрос на редактирование содержит измененное значение краткого наименования рекламной кампании (shortName).
Примечание: При редактировании все данные запроса переписываются заново для редактируемой рекламной кампании, независимо от того, изменились ли их значения или нет.
PUT/ads/316600
Content-Type: application/atom+xml
X-Auth-UserID:179221
X-Auth-Passwd:token
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<content type="text/xml">
<ad xmlns="http://adriver.ru/ns/restapi/atom">
<name>Стартовая кампания</name>
<shortName>startAD</shortName>
<enable>0</enable>
<canBorrow>1</canBorrow>
</ad>
</content>
<adriver:revision>a9578a0817bf8c467890d5cefd3c3d54bd63e3a5</adriver:revision>
</entry>
Примечания к коду
- startAD — изменено краткое название рекламной кампании.
В случае успешного редактирования в ответе возвращаются все текущие данные рекламной кампании и обновленный номер ревизии, аналогично ответу системы при добавлении рекламной кампании.
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-16T19:26:20+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AD Atom Entry</title>
<id>urn:x-adriver:316600</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/ads/316600"/>
<content type="text/xml">
<ad xmlns="http://adriver.ru/ns/restapi/atom">
<id>316600</id>
<name>Стартовая кампания</name>
<shortName>startAD</shortName>
<enable>0</enable>
<enables/>
<canBorrow>1</canBorrow>
<credit>0</credit>
<trafficManager>
<name/>
<email/>
</trafficManager>
<externalId>1</externalId>
<statusNumber>4</statusNumber>
<adPlacements/>
</ad>
</content>
<adriver:revision>54fb70fa254ec8116b0a101b79f05951a9211d9b</adriver:revision>
</entry>
Примечания к коду
- 54fb70fa254ec8116b0a101b79f05951a9211d9b — новый номер ревизии.
Код ответа 200.
В случае ошибки, например, при несовпадении номеров ревизий клиента (в запросе) и сервера, выдается ответ следующего вида:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2011-12-08T17:25:24+04:00</updated>
<content type="text">revision collision for ad (id=316600)</content>
<summary>Adriver::RestAPI::Core::Exception::RevisionCollision</summary>
</entry>
Код ответа 412.
4.7. Просмотр данных рекламной кампании
Имеется возможность также получить данные рекламной кампании по ее уникальному идентификатору. Идентификатор рекламной кампании выдается в ответе системы при добавлении рекламной кампании, также можно получить уникальные идентификаторы всех рекламных кампаний данной учетной записи при просмотре списка рекламных кампаний (п.4.2).
Пример запроса на просмотр данных рекламной кампании:
GET/ads/316600 Content-Type: application/atom+xml
X-Auth-UserID:179221
X-Auth-Passwd:token
Примечания к коду
- 316600 — идентификатор рекламной кампании, данные которой просматриваются.
В ответ система возвращает все текущие данные по запрошенному идентификатору рекламной кампании:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2011-12-16T19:19:27+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AD Atom Entry</title>
<id>urn:x-adriver:316600</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/ads/316600"/>
<content type="text/xml">
<ad xmlns="http://adriver.ru/ns/restapi/atom">
<id>316600</id>
<name>Стартовая кампания</name>
<shortName>316600</shortName>
<enable>1</enable>
<enables/>
<canBorrow>1</canBorrow>
<credit>0</credit>
<trafficManager>
<name/>
<email/>
</trafficManager>
<externalId>1</externalId>
<statusNumber>4</statusNumber>
<adPlacements/>
</ad>
</content>
<adriver:revision>a9578a0817bf8c467890d5cefd3c3d54bd63e3a5</adriver:revision>
</entry>
Код ответа 200.
Если в запросе на просмотр данных рекламной кампании был указан идентификатор несуществующей рекламной кампании, то ответ системы будет выглядеть следующим образом:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2011-12-16T19:20:35+04:00</updated>
<content type="text">Ad (id 3166001) not found.</content>
<summary>Adriver::RestAPI::Core::Exception::Ad::NotFound</summary>
</entry>
Код ответа 404.
5. Работа со слайсами
Слайс – это часть трафика рекламного места, передаваемая с площадки (сайта издателя) в рекламную кампанию.
Слайсы используются для проведения на одном рекламном месте нескольких рекламных кампаний одновременно. Трафик рекламного места (показы баннеров на этом рекламном месте в единицу времени) делится на части (слайсы), которые передаются в разные рекламные кампании. Если на рекламном месте проводится только одна рекламная кампания, издатель должен определить один слайс для всего трафика этого рекламного места.
Таким образом, слайсы обеспечивают организацию связи между рекламными кампаниями и рекламными местами.
Более подробную информацию о слайсах можно получить из документации на сайте.
Рекламная кампания, в которую не переданы слайсы, не может показываться (у такой рекламной кампании нет рекламных мест).
Использование программного интерфейса позволяет осуществлять следующие операции с сайтами в системе AdRiver:
- добавление слайса;
- просмотр списка слайсов сайта;
- изменение данных слайса;
- просмотр данных слайса.
Параметры, используемые при работе с рекламными кампаниями в системе AdRiver через программный интерфейс, подразделяются на обязательные и необязательные. Обязательные параметры необходимо использовать при создании и редактировании рекламной кампании. Значения всех параметров, определенных для рекламных кампаний (как обязательных, так и необязательных), выдаются системой при ответе на запрос.
Обязательные параметры:
- siteId — идентификатор сайта в системе (отображается при добавлении сайта и чтении списка сайтов);
- type — тип слайса (1 – процентный коммерческий, 2 – числовой коммерческий, 3 – дефолтный);
- enable — признак включения слайса (1 – слайс включен, 0 – слайс выключен);
- period — период отображения слайса, задается с помощью параметров startDate (дата начала показа слайса) и stopDate (дата окончания показа слайса) в формате YYYY-MM-DD, при задании следует следить за тем, чтобы период отображения слайса не заканчивался раньше текущей даты;
- bannerType — тип баннеров в создаваемом слайсе (задается с помощью указания кода типа баннера в системе AdRiver, таблица соответствия типов баннеров их кодам приведена в приложении 2).
Необязательные параметры:
- enables — список доступных для редактирования служебных параметров слайса;
- burst_mode — распределение показов в течение дня (0 – равномерное, 1 – с максимальной скоростью), используется только для числовых слайсов;
- priority — приоритет слайса (задается только для числовых слайсов), используется в том случае, если по условиям показа одновременно могут быть выбраны несколько слайсов (с одинаковым таргетингом), наименьший приоритет – 1, наивысший – 9;
- limits — ограничения на максимальное количество показов и кликов всего и за день для числовых слайсов;
- tz_convertion — признак использования локального времени посетителя сайта для демонстрации рекламы (1 – используется локальное время, 0 – используется московское время);
- bannerNumber — порядковый номер баннера на странице, используется в том случае, если на одной странице размещается несколько баннеров;
- pageZone — зона страницы, в которой располагается слайс (0 – любая, 1 – верх, 2 – середина, 3 – низ)*;
- adId — идентификатор рекламной кампании в системе AdRiver, в которую передается создаваемый слайс;
- net_adId — идентификатор сетевой рекламной кампании в системе AdRiver, в которую передается создаваемый слайс;
- advertiserId — идентификатор рекламного агентства в системе AdRiver, в которое передается создаваемый слайс для использования в его рекламных кампаниях;
- siteZoneId — идентификатор зоны сайта, на которую выделяется создаваемый слайс.
5.1. Добавление слайса
В теле запроса указываются значения всех обязательных параметров слайса. Пример запроса на добавление слайса:
Характеристики слайса (только для чтения):
- assigned — флаг принадлежности слайса рекламной кампании (1 – слайс передан в рекламную кампанию, 0 – свободный слайс);
- exposures — текущее количество показов в слайсе за сегодня;
- clicks — текущее количество кликов в слайсе за сегодня.
POST/slices
Content-Type: application/atom+xml
X-Auth-UserID:UserID
X-Auth-Passwd:token
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<title>Slice Atom Entry</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2011-09-27T19:39:53+04:00</updated>
<content type="text/xml">
<slice xmlns="http://adriver.ru/ns/restapi/atom" type="2">
<enable>0</enable>
<burst_mode>1</burst_mode>
<priority>9</priority>
<bannerType>52</bannerType>
<bannerNumber>1</bannerNumber>
<pageZone>2</pageZone>
<period>
<startDate>2012-03-14</startDate>
<stopDate>2020-12-31</stopDate>
</period>
<limits>
<total>
<exposures>1000000</exposures>
<clicks>5000</clicks>
<richExposures>0</richExposures>
</total>
<daily>
<exposures>10000</exposures>
<clicks>500</clicks>
<richExposures>0</richExposures>
</daily>
</limits>
</slice>
</content>
<adriver:siteId>178094</adriver:siteId>
<adriver:siteZoneId>4</adriver:siteZoneId>
</entry>;
Примечания к коду:
- 178094 — Идентификатор сайта, для которого создается слайс.
- 4 — Идентификатор зоны сайта, для которой выделяется слайс (siteZoneId).
В случае успешного создания слайса будет возвращено его представление:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-19T14:02:37+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Slice Atom Entry</title>
<id>urn:x-adriver:1005523</id>
<content type="text/xml">
<slice xmlns="http://adriver.ru/ns/restapi/atom" type="2">
<id>1005523</id>
<assigned>0</assigned>
<enable>0</enable>
<enables/>
<burst_mode>1</burst_mode>
<priority>9</priority>
<period>
<startDate>2012-03-14</startDate>
<stopDate>2020-12-31</stopDate>
</period>
<limits>
<total>
<exposures>1000000</exposures>
<richExposures>0</richExposures>
<clicks>5000</clicks>
</total>
<daily>
<exposures>10000</exposures>
<richExposures>0</richExposures>
<clicks>500</clicks>
</daily>
</limits>
<tz_conversion>0</tz_conversion>
<bannerType>52</bannerType>
<bannerNumber>1</bannerNumber>
<pageZone>2</pageZone>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
</slice>
</content>
<adriver:revision>65d12195b1a5043951e976dcceacb38b4ba41133</adriver:revision>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/slices/1005523"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/sites/178094"/>
<adriver:siteId>178094</adriver:siteId>
<adriver:siteZoneId>4</adriver:siteZoneId>
<adriver:publisherId>178072</adriver:publisherId>
</entry>
Примечания к коду:
- 1005523 — Идентификатор созданного слайса.
Код ответа 201.
5.2. Получение списка слайсов сайта
Нижеследующий запрос позволяет получить список всех слайсов заданного сайта (в примере – сайта 178094).
GET/slices?site_id=178094 Content-Type:application/atom+xml X-Auth-UserID:UserID X-Auth-Passwd:token
В ответ система возвращает все текущие данные по всем слайсам запрошенного идентификатора сайта.
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-14T14:46:52+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Slice Atom Feed</title>
<id>https://api.adriver.ru/slices?site_id=178094</id>
<link rel="self" type="application/atom+xml" href="https://api.adriver.ru/slices?site_id=178094"/>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-14T14:46:52+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Slice Atom Entry</title>
<id>urn:x-adriver:996956</id>
<content type="text/xml">
<slice xmlns="http://adriver.ru/ns/restapi/atom" type="2">
<id>996956</id>
<assigned>1</assigned>
<enable>1</enable>
<enables/>
<burst_mode>1</burst_mode>
<priority>9</priority>
<period>
<startDate>2012-03-14</startDate>
<stopDate>2020-12-31</stopDate>
</period>
<limits>
<total>
<exposures>1000000</exposures>
<richExposures>0</richExposures>
<clicks>5000</clicks>
</total>
<daily>
<exposures>10000</exposures>
<richExposures>0</richExposures>
<clicks>500</clicks>
</daily>
</limits>
<tz_conversion>0</tz_conversion>
<bannerType>52</bannerType>
<bannerNumber>1</bannerNumber>
<pageZone>2</pageZone>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
</slice>
</content>
<adriver:revision>ded428a495682f674d671b3a71dedaddd4cf8bc1</adriver:revision>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/slices/996956"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/sites/178094"/>
<adriver:siteId>178094</adriver:siteId>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/ads/312919"/>
<adriver:adId>312919</adriver:adId>
<adriver:publisherId>178072</adriver:publisherId>
<adriver:advertiserId>178072</adriver:advertiserId>
</entry>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-14T14:46:52+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Slice Atom Entry</title>
<id>urn:x-adriver:996959</id>
<content type="text/xml">
<slice xmlns="http://adriver.ru/ns/restapi/atom" type="2">
<id>996959</id>
<assigned>1</assigned>
<enable>1</enable>
<enables/>
<burst_mode>1</burst_mode>
<priority>9</priority>
<period>
<startDate>2012-03-14</startDate>
<stopDate>2020-12-31</stopDate>
</period>
<limits>
<total>
<exposures>0</exposures>
<richExposures>0</richExposures>
<clicks>0</clicks>
</total>
<daily>
<exposures>0</exposures>
<richExposures>0</richExposures>
<clicks>0</clicks>
</daily>
</limits>
<tz_conversion>0</tz_conversion>
<bannerType>21</bannerType>
<bannerNumber>0</bannerNumber>
<pageZone>0</pageZone>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
</slice>
</content>
<adriver:revision>cd8c0919990ef25783d08f1969e743e5f1985a7f</adriver:revision>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/slices/996959"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/sites/178094"/>
<adriver:siteId>178094</adriver:siteId>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/ads/312919"/>
<adriver:siteZoneId>3</adriver:siteZoneId>
<adriver:adId>312919</adriver:adId>
<adriver:publisherId>178072</adriver:publisherId>
<adriver:advertiserId>178072</adriver:advertiserId>
</entry>
</feed>
Примечания к коду:
- 996956 — Идентификатор первого слайса из списка слайсов сайта.
- 996959 — Идентификатор второго слайса из списка слайсов сайта.
Код ответа 200.
5.3. Редактирование данных слайса
Если необходимо изменить данные ранее добавленного слайса, то это можно осуществить с помощью запроса на его изменение. Операция редактирования по своей сути аналогична операции добавления слайса, поскольку в соответствующем запросе содержится полный список необходимых параметров слайса.
В отличие от команды добавления слайса команда редактирования слайса содержит дополнительный тег
Примечание: При редактировании все данные запроса переписываются заново для редактируемого слайса, независимо от того, изменились ли их значения или нет.
В приведенном примере запрос на редактирование содержит измененное значение приоритета и зоны страницы. Кроме того, запрос передает редактируемый слайс в рекламную кампанию с идентификатором 312919.
Примечание: Созданный ранее слайс может быть отредактирован с помощью программного интерфейса только в том случае, если он не был передан в рекламную кампанию. После передачи слайса в рекламную кампанию редактирование его данных становится невозможным.
PUT/slices/997074
Content-Type: application/atom+xml
X-Auth-UserID:UserID
X-Auth-Passwd:token
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<title>Slice Atom Entry</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2011-09-27T19:39:53+04:00</updated>
<content type="text/xml">
<slice xmlns="http://adriver.ru/ns/restapi/atom" type="2">
<enable>1</enable>
<burst_mode>1</burst_mode>
<priority>1</priority>
<bannerType>52</bannerType>
<bannerNumber>1</bannerNumber>
<pageZone>3</pageZone>
<period>
<startDate>2012-03-14</startDate>
<stopDate>2020-12-31</stopDate>
</period>
<limits>
<total>
<exposures>1000000</exposures>
<clicks>5000</clicks>
<richExposures>0</richExposures>
</total>
<daily>
<exposures>1000</exposures>
<clicks>500</clicks>
<richExposures>0</richExposures>
</daily>
</limits>
</slice>
</content>
<adriver:revision>65d12195b1a5043951e976dcceacb38b4ba41133</adriver:revision>
<adriver:siteId>178094</adriver:siteId>
<adriver:adId>312919</adriver:adId>
</entry>
Примечания к коду:
- 178094 — Идентификатор сайта, слайс которого редактируется.
- 312919 — Идентификатор рекламной кампании, в которую передается редактируемый слайс.
Можно передать редактируемый слайс рекламному агентству без указания рекламной кампании для дальнейшего использования этого слайса в тех или иных рекламных кампаниях агентства:
PUT/slices/997074
Content-Type: application/atom+xml
X-Auth-UserID:UserID
X-Auth-Passwd:token
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<title>Slice Atom Entry</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2011-09-27T19:39:53+04:00</updated>
<author>
<name>1C Media Finance</name>
</author>
<content type="text/xml">
<slice xmlns="http://adriver.ru/ns/restapi/atom" type="2">
<enable>1</enable>
<burst_mode>1</burst_mode>
<priority>9</priority>
<bannerType>52</bannerType>
<bannerNumber>1</bannerNumber>
<pageZone>2</pageZone>
<period>
<startDate>2012-03-14</startDate>
<stopDate>2020-12-31</stopDate>
</period>
<limits>
<total>
<exposures>1000000</exposures>
<clicks>5000</clicks>
<richExposures>0</richExposures>
</total>
<daily>
<exposures>10000</exposures>
<clicks>500</clicks>
<richExposures>0</richExposures>
</daily>
</limits>
</slice>
</content>
<adriver:siteId>178094</adriver:siteId>
<adriver:advertiserId>172089</adriver:advertiserId>
</entry>
Примечания к коду:
- 172089 — Идентификатор рекламного агентства, в которое передается редактируемый слайс.
В случае успешного редактирования в ответе возвращаются все текущие данные слайса и обновленный номер ревизии, аналогично ответу системы при добавлении слайса.
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-19T14:06:11+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Slice Atom Entry</title>
<id>urn:x-adriver:1005523</id>
<content type="text/xml">
<slice xmlns="http://adriver.ru/ns/restapi/atom" type="2">
<id>1005523</id>
<assigned>1</assigned>
<enable>1</enable>
<enables/>
<burst_mode>1</burst_mode>
<priority>1</priority>
<period>
<startDate>2012-03-14</startDate>
<stopDate>2020-12-31</stopDate>
</period>
<limits>
<total>
<exposures>1000000</exposures>
<richExposures>0</richExposures>
<clicks>0</clicks>
</total>
<daily>
<exposures>0</exposures>
<richExposures>0</richExposures>
<clicks>0</clicks>
</daily>
</limits>
<tz_conversion>0</tz_conversion>
<bannerType>52</bannerType>
<bannerNumber>0</bannerNumber>
<pageZone>3</pageZone>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
</slice>
</content>
<adriver:revision>32cc9f6e99249095fa6f124c176ae45e277327c6</adriver:revision>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/slices/1005523"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/sites/178094"/>
<adriver:siteId>178094</adriver:siteId>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/ads/312919"/>
<adriver:siteZoneId>4</adriver:siteZoneId>
<adriver:adId>312919</adriver:adId>
<adriver:publisherId>178072</adriver:publisherId>
<adriver:advertiserId>178072</adriver:advertiserId>
</entry>
Примечания к коду:
- <assigned>1</assigned> — Слайс передан в рекламную кампанию .
Код ответа 200.
В случае ошибки, например, при несовпадении номеров ревизий клиента (в запросе) и сервера, выдается ответ следующего вида:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2012-03-19T16:04:16+04:00</updated>
<content type="text">revision collision for slice (id=997074)</content>
<summary>Adriver::RestAPI::Core::Exception::RevisionCollision</summary>
</entry>
Код ответа 412.
5.4. Просмотр данных слайса
Имеется возможность также получить данные слайса по его уникальному идентификатору. Идентификатор слайса выдается в ответе системы при добавлении слайса, также можно получить уникальные идентификаторы всех слайсов данного сайта при просмотре списка слайсов (п.5.2).
Пример запроса на просмотр данных слайса:
GET/slices/996956 Content-Type: application/atom+xml X-Auth-UserID:UserID X-Auth-Passwd:token
В ответ система возвращает все текущие данные по запрошенному идентификатору слайса:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-14T14:39:11+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Slice Atom Entry</title>
<id>urn:x-adriver:996956</id>
<content type="text/xml">
<slice xmlns="http://adriver.ru/ns/restapi/atom" type="2">
<id>996956</id>
<assigned>1</assigned>
<enable>1</enable>
<enables/>
<burst_mode>1</burst_mode>
<priority>9</priority>
<period>
<startDate>2012-03-14</startDate>
<stopDate>2020-12-31</stopDate>
</period>
<limits>
<total>
<exposures>1000000</exposures>
<richExposures>0</richExposures>
<clicks>5000</clicks>
</total>
<daily>
<exposures>10000</exposures>
<richExposures>0</richExposures>
<clicks>500</clicks>
</daily>
</limits>
<tz_conversion>0</tz_conversion>
<bannerType>52</bannerType>
<bannerNumber>1</bannerNumber>
<pageZone>2</pageZone>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
</slice>
</content>
<adriver:revision>ded428a495682f674d671b3a71dedaddd4cf8bc1</adriver:revision>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/slices/996956"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/sites/178094"/>
<adriver:siteId>178094</adriver:siteId>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/ads/312919"/>
<adriver:adId>312919</adriver:adId>
<adriver:publisherId>178072</adriver:publisherId>
<adriver:advertiserId>178072</adriver:advertiserId>
</entry>
Код ответа 200.
Если в запросе на просмотр данных слайса был указан идентификатор несуществующего слайса, то ответ системы будет выглядеть следующим образом:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2012-03-19T13:51:19+04:00</updated>
<content type="text">Slice (id 99695633) not found.</content>
<summary>Adriver::RestAPI::Core::Exception::Slice::NotFound</summary>
</entry>
Код ответа 404.
6. Работа с пулами
Пул – это средство группировки слайсов. В пул можно передавать слайсы, как в рекламную кампанию, и вырезать из него слайсы, как из сайта. Более подробную информацию о пулах можно получить здесь.
Использование программного интерфейса позволяет осуществлять следующие операции с пулами в системе AdRiver:
- создание пула;
- получение списка пулов аккаунта;
- редактирование данных пула;
- вырезание слайса из пула;
- передача слайса в пул;
- получение списка слайсов, вырезанных из пула;
- получение списка слайсов, переданных в пул;
- получение пула по его ID.
6.1. Создание пула
Пример запроса на создание пула:
POST pools?user_id=100000
Content-Type: application/atom+xml
X-Auth-UserID:UserID
X-Auth-Passwd:token
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<content type="text/xml">
<pool xmlns="http://adriver.ru/ns/restapi/atom">
<name>test_new</name>
<shortName>test</shortName>
</pool>
</content>
<adriver:userId>100000</adriver:userId>
</entry>
Примечания к коду:
- user_id – ID вашего аккаунта (в данном примере 100000)
- name – название пула
- short name – краткое название пула.
В случае успешного создания пула будет возвращено его представление:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-19T14:02:37+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Pool Atom Entry</title>
<id>urn:x-adriver:100001</id>
<content type="text/xml">
<pool xmlns="http://adriver.ru/ns/restapi/atom">
<id>100001<id/>
<name>test_new</name>
<shortName>test</shortName>
</pool>
</content>
<adriver:revision>65d12195b1a5043951e976dcceacb38b4ba41133</adriver:revision>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/pools/100001"/>
<adriver:userId>100000</adriver:userId>
</entry>
Примечания к коду:
- 100001 – идентификатор созданного пула:
- test_new – название пула;
- test – краткое название пула.
6.2. Получение списка пулов аккаунта
Нижеследующий запрос позволяет получить список всех пулов указанного аккаунта (в примере – для аккаунта 100000).
GET pools?user_id=100000 Content-Type: application/atom+xml X-Auth-UserID:UserID X-Auth-Passwd:token
В ответ система возвращает текущие данные по всем пулам указанного аккаунта. Пример ответа системы:
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2014-12-10T13:05:18+03:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Pool Atom Feed</title>
<id>https://api.adriver.ru/pools?user_id=100000</id>
<link rel="self" type="application/atom+xml" href="https://api.adriver.ru/pools?user_id=100000"/>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2014-12-10T13:05:18+03:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Pool Atom Entry</title>
<id>urn:x-adriver:100001</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/pools/100001"/>
<content type="text/xml">
<pool xmlns="http://adriver.ru/ns/restapi/atom">
<id>100001</id>
<name>Test</name>
<shortName>Test</shortName>
</pool>
</content>
<adriver:revision>1e90bc58b150d3d4c22b1291d3f43139eab1ba13</adriver:revision>
</entry>
</feed>
Примечания к коду:
- 100000 – ID пользователя, список пулов которого запрашивался;
- 100001 – ID пула, по которому представляется информация ниже.
6.3. Редактирование данных пула
Пример запроса на редактирование данных пула:
PUT /pools/100000
Content-Type: application/atom+xml
X-Auth-UserID:UserID
X-Auth-Passwd:token
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<content type="text/xml">
<pool xmlns="http://adriver.ru/ns/restapi/atom">
<name>test_new_pool</name>
<shortName>test</shortName>
</pool>
</content>
<adriver:userId>111111</adriver:userId>
</entry>
Примечания к коду:
- 100000 – id пула, данные которого необходимо отредактировать.
В ответ возвращается представление отредактированного пула:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2014-12-10T13:57:26+03:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Pool Atom Entry</title>
<id>urn:x-adriver:100000</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/pools/100000"/>
<content type="text/xml">
<pool xmlns="http://adriver.ru/ns/restapi/atom">
<id>100000</id>
<name>test_rename</name>
<shortName>test</shortName>
</pool>
</content>
<adriver:revision>fd358747b5a16ed4dd89cf2ce9c3bdd2da3d939a</adriver:revision>
</entry>
Примечания к коду:
- 100000 – id отредактированного пула.
6.4. Вырезание слайса из пула
Пример запроса на вырезание слайса из пула:
POST slices?pool_id=100000
Content-Type: application/atom+xml
X-Auth-UserID:UserID
X-Auth-Passwd:token
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<content type="text/xml">
<slice xmlns="http://adriver.ru/ns/restapi/atom" type="2">
<enable>0</enable>
<burst_mode>1</burst_mode>
<priority>9</priority>
<bannerType>52</bannerType>
<bannerNumber>1</bannerNumber>
<pageZone>2</pageZone>
<period>
<startDate>2012-03-14</startDate>
<stopDate>2020-12-31</stopDate>
</period>
</slice>
</content>
<adriver:poolId>100000</adriver:poolId>
</entry>
Примечания к коду:
- 100000 – id пула, из которого нужно вырезать слайс.
Пример ответа системы:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2014-12-10T13:59:30+03:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Slice Atom Entry</title>
<id>urn:x-adriver:111111</id>
<content type="text/xml">
<slice xmlns="http://adriver.ru/ns/restapi/atom" type="2">
<id>111111</id>
<assigned>0</assigned>
<enable>0</enable>
<enables/>
<burst_mode>1</burst_mode>
<priority>9</priority>
<period>
<startDate>2012-03-14</startDate>
<stopDate>2020-12-31</stopDate>
</period>
<limits>
<total>
<exposures>0</exposures>
<richExposures>0</richExposures>
<clicks>0</clicks>
</total>
<daily>
<exposures>0</exposures>
<richExposures>0</richExposures>
<clicks>0</clicks>
</daily>
</limits>
<tz_conversion>0</tz_conversion>
<bannerType>52</bannerType>
<bannerNumber>1</bannerNumber>
<pageZone>2</pageZone>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
</slice>
</content>
<adriver:revision>7943ee5eaa3f1640ee15c5581d6b6838baa05172</adriver:revision>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/slices/111111"/>
<adriver:poolId>100000</adriver:poolId>
<adriver:publisherId>100001</adriver:publisherId>
</entry>
Примечания к коду:
- 111111 – id созданного слайса;
- 100000 – id пула, из которого был вырезан слайс.
6.5. Передача слайса в пул
Пример запроса на передачу слайса в пул:
POST slices?pool_into_id=100000 Content-Type: application/atom+xml X-Auth-UserID:UserID X-Auth-Passwd:token <?xml version="1.0" encoding="utf-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom"> <content type="text/xml"> <slice xmlns="http://adriver.ru/ns/restapi/atom" type="2"> <enable>0</enable> <burst_mode>1</burst_mode> <priority>9</priority> <bannerType>52</bannerType> <bannerNumber>1</bannerNumber> <pageZone>2</pageZone> <period> <startDate>2012-03-14</startDate> <stopDate>2020-12-31</stopDate> </period> </slice> </content> <adriver:siteId>111111</adriver:siteId> <adriver:poolIntoId>100000</adriver:poolIntoId> </entry>
Примечания к коду:
- 100000 – id пула, в который нужно передать слайс;
- 111111 – id сайта, с которого передается слайс.
Пример ответа системы:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2014-12-10T14:00:41+03:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Slice Atom Entry</title>
<id>urn:x-adriver:100000</id>
<content type="text/xml">
<slice xmlns="http://adriver.ru/ns/restapi/atom" type="2">
<id>100001</id>
<assigned>1</assigned>
<enable>0</enable>
<enables/>
<burst_mode>1</burst_mode>
<priority>9</priority>
<period>
<startDate>2012-03-14</startDate>
<stopDate>2020-12-31</stopDate>
</period>
<limits>
<total>
<exposures>0</exposures>
<richExposures>0</richExposures>
<clicks>0</clicks>
</total>
<daily>
<exposures>0</exposures>
<richExposures>0</richExposures>
<clicks>0</clicks>
</daily>
</limits>
<tz_conversion>0</tz_conversion>
<bannerType>52</bannerType>
<bannerNumber>1</bannerNumber>
<pageZone>2</pageZone>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
</slice>
</content>
<adriver:revision>1913d94e5604215fd386796e7373bb847c006e8e</adriver:revision>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/slices/100001"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/sites/111111"/>
<adriver:siteId>111111</adriver:siteId>
<adriver:publisherId>100000</adriver:publisherId>
<adriver:advertiserId>110011</adriver:advertiserId>
</entry>
Примечания к коду:
- 100001 – id переданного в пул слайса.
6.6. Получение списка слайсов, вырезанных из пула
Пример запроса на получение слайсов, вырезанных из пула:
GET slices?pool_id=100000
Content-Type: application/atom+xml
X-Auth-UserID:UserID
X-Auth-Passwd:token
Примечания к коду:
- 100000 – id пула.
Пример ответа системы:
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2014-12-10T14:01:26+03:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Slice Atom Feed</title>
<id>https://api.adriver.ru/slices?pool_id=100000</id>
<link rel="self" type="application/atom+xml" href="https://api.adriver.ru/slices?pool_id=100000"/>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2014-12-10T14:01:26+03:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Slice Atom Entry</title>
<id>urn:x-adriver:111111</id>
<content type="text/xml">
<slice xmlns="http://adriver.ru/ns/restapi/atom" type="2">
<id>111111</id>
<assigned>0</assigned>
<enable>0</enable>
<enables/>
<burst_mode>1</burst_mode>
<priority>9</priority>
<period>
<startDate>2012-03-14</startDate>
<stopDate>2020-12-31</stopDate>
</period>
<limits>
<total>
<exposures>0</exposures>
<richExposures>0</richExposures>
<clicks>0</clicks>
</total>
<daily>
<exposures>0</exposures>
<richExposures>0</richExposures>
<clicks>0</clicks>
</daily>
</limits>
<tz_conversion>0</tz_conversion>
<bannerType>52</bannerType>
<bannerNumber>1</bannerNumber>
<pageZone>2</pageZone>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
</slice>
</content>
<adriver:revision>7943ee5eaa3f1640ee15c5581d6b6838baa05172</adriver:revision>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/slices/111111"/>
<adriver:poolId>100000</adriver:poolId>
<adriver:publisherId>100001</adriver:publisherId>
</entry>
</feed>
Примечания к коду:
- 111111 – id слайса, по которому представляется информация ниже;
- 100000 – id пула.
6.7. Получение списка слайсов, переданных в пул
Пример запроса на получение списка слайсов, переданных в пул:
GET slices?pool_into_id=100000
Content-Type: application/atom+xml
X-Auth-UserID:UserID
X-Auth-Passwd:token
Примечания к коду:
- 100000 – id пула.
Пример ответа системы:
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2014-12-10T14:02:14+03:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Slice Atom Feed</title>
<id>https://api.adriver.ru/slices?pool_into_id=100000</id>
<link rel="self" type="application/atom+xml" href="https://api.adriver.ru/slices?pool_into_id=100000"/>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2014-12-10T14:02:14+03:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Slice Atom Entry</title>
<id>urn:x-adriver:1471601</id>
<content type="text/xml">
<slice xmlns="http://adriver.ru/ns/restapi/atom" type="2">
<id>111111</id>
<assigned>1</assigned>
<enable>0</enable>
<enables/>
<burst_mode>1</burst_mode>
<priority>9</priority>
<period>
<startDate>2012-03-14</startDate>
<stopDate>2020-12-31</stopDate>
</period>
<limits>
<total>
<exposures>0</exposures>
<richExposures>0</richExposures>
<clicks>0</clicks>
</total>
<daily>
<exposures>0</exposures>
<richExposures>0</richExposures>
<clicks>0</clicks>
</daily>
</limits>
<tz_conversion>0</tz_conversion>
<bannerType>52</bannerType>
<bannerNumber>1</bannerNumber>
<pageZone>2</pageZone>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
</slice>
</content>
<adriver:revision>1913d94e5604215fd386796e7373bb847c006e8e</adriver:revision>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/slices/111111"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/sites/110011"/>
<adriver:siteId>110011</adriver:siteId>
<adriver:publisherId>222222</adriver:publisherId>
<adriver:advertiserId>333333</adriver:advertiserId>
</entry>
</feed>
Примечания к коду:
- 100000 – id пула;
- 111111 – id слайса.
6.8. Получение пула по его ID
Пример запроса на получение пула по его ID:
GET /pools/100000
Content-Type: application/atom+xml
X-Auth-UserID:UserID
X-Auth-Passwd:token
Примечания к коду:
- 100000 – id пула.
Пример ответа системы:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2014-12-10T14:02:44+03:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Pool Atom Entry</title>
<id>urn:x-adriver:100000</id>
<link rel="edit" type="application/atom+xml"
href="https://api.adriver.ru/pools/100000"/>
<content type="text/xml">
<pool xmlns="http://adriver.ru/ns/restapi/atom">
<id>100000</id>
<name>test_rename</name>
<shortName>test</shortName>
</pool>
</content>
<adriver:revision>b2b01b3a1e8b8f69b274a67ec6503108a137d3d2</adriver:revision>
</entry>
Примечания к коду:
- 100000 – id пула.
7. Работа со сценариями
Сценарий — это набор настроек таргетинга для одного или группы баннеров. Сценарии создаются внутри рекламной кампании.
Более подробную информацию о сценариях можно получить из документации на сайте.
Использование программного интерфейса позволяет осуществлять следующие операции со сценариями в системе AdRiver:
- создание сценария;
- просмотр списка сценариев рекламной кампании;
- изменение данных сценария;
- просмотр данных сценария.
Параметры, используемые при работе со сценариями в системе AdRiver через программный интерфейс, подразделяются на обязательные и необязательные. Обязательные параметры необходимо использовать при создании и редактировании сценария. Значения всех параметров, определенных для сценариев (как обязательных, так и необязательных), выдаются системой при ответе на запрос.
Обязательные параметры:
- name — наименование сценария;
- enable — признак включения сценария (1 – сценарий включен, 0 – сценарий выключен);
- userId — идентификатор учетной записи владельца создаваемого сценария в системе;
- adId — идентификатор рекламной кампании, в которую добавляется сценарий.
Необязательные параметры:
- externalId — внешний идентификатор сценария;
- enables — список доступных для редактирования служебных параметров сценария;
- burst_mode — распределение показов в течение дня (0 – равномерное, 1 – с максимальной скоростью);
-
limits — разнообразные ограничения для сценария:
-
total — ограничения на общее количество (всего):
- exposures — показов;
- clicks — кликов;
- uniqClicks — уникальных кликов;
-
daily — ограничения на количество в день:
- exposures — показов;
- clicks — кликов;
- uniqClicks — уникальных кликов;
-
frequency — ограничения на количество показов уникальным пользователям:
- daily — в день;
- clicks — за неделю;
- uniqClicks — за месяц;
-
schedule — расписание выполнения сценария:
-
period — временной интервал выполнения сценария (возможно задание нескольких неперекрывающихся интервалов):
- startDate, stopDate — даты начала и окончания очередного временного интервала выполнения сценария.
-
period — временной интервал выполнения сценария (возможно задание нескольких неперекрывающихся интервалов):
-
total — ограничения на общее количество (всего):
Характеристики сценария (только для чтения):
- exposures — текущее количество показов в сценарии за сегодня;
- clicks — текущее количество кликов в сценарии за сегодня;
- banners — список ссылок на баннеры данного сценария.
При запросе списка сценариев возможно использование фильтра по полю externalId.
7.1. Добавление сценария
В теле запроса указываются значения всех обязательных параметров сценария. Пример запроса на добавление сценария:
POST/adplacements
Content-Type: application/atom+xml
X-Auth-UserID:UserID
X-Auth-Passwd:token
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<title>AD Atom Entry</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2011-06-08T09:03:24+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<content type="text/xml">
<adPlacement xmlns="http://adriver.ru/ns/restapi/atom">
<name>Profile1</name>
<enable>0</enable>
<limits>
<total>
<exposures>1000000</exposures>
<clicks>10000</clicks>
<uniqClicks>0</uniqClicks>
</total>
<daily>
<exposures>50000</exposures>
<clicks>500</clicks>
</daily>
<frequency>
<daily>1</daily>
<weekly>3</weekly>
<monthly>7</monthly>
</frequency>
</limits>
</adPlacement>
</content>
<adriver:userId>174292</adriver:userId>
<adriver:adId>328525</adriver:adId>
</entry>
В случае успешного создания сценария будет возвращено его представление:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-21T17:18:31+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AdPlacement Atom Entry</title>
<id>urn:x-adriver:791628</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/adplacements/791628"/>
<content type="text/xml">
<adPlacement xmlns="http://adriver.ru/ns/restapi/atom">
<id>791628</id>
<name>Profile1</name>
<enable>0</enable>
<enables>
<enable name="UU_REPORT">1</enable>
</enables>
<burst_mode>1</burst_mode>
<limits>
<total>
<exposures>1000000</exposures>
<clicks>10000</clicks>
<uniqClicks>0</uniqClicks>
</total>
<daily>
<exposures>50000</exposures>
<clicks>500</clicks>
</daily>
<frequency>
<daily>1</daily>
<weekly>3</weekly>
<monthly>7</monthly>
</frequency>
</limits>
<externalId></externalId>
<schedule/>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
<banners/>
</adPlacement>
</content>
<link rel="related" type="text/html" href="http://.../cgi-bin/mngcgi?templ=action/AddBannerLogin&login=zackery&adID=328525&profileID=791628"/>
<adriver:bannerLoader>http://.../cgi-bin/mngcgi?templ=action/AddBannerLogin&login=zackery&adID=328525&profileID=791628</adriver:bannerLoader>
<adriver:revision>cc99eeb3eb95c9a5b8e4be6850a8bff32f780473</adriver:revision>
</entry>
Примечания к коду:
- 791628 — Идентификатор созданного сценария.
Код ответа 201.
7.2. Получение списка сценариев рекламной кампании
Нижеследующий запрос позволяет получить список всех сценариев заданной рекламной кампании (в примере – рекламной кампании 328525).
GET/adplacements?ad_id=328525 Content-Type:application/atom+xml X-Auth-UserID:UserID X-Auth-Passwd:token
В ответ система возвращает все текущие данные по всем сценариям запрошенного идентификатора рекламной кампании.
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-21T17:23:41+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AdPlacement Atom Feed</title>
<id>https://api.adriver.ru/adplacements?ad_id=328525</id>
<link rel="self" type="application/atom+xml" href="https://api.adriver.ru/adplacements?ad_id=328525"/>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-21T17:23:41+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AdPlacement Atom Entry</title>
<id>urn:x-adriver:791553</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/adplacements/791553"/>
<content type="text/xml">
<adPlacement xmlns="http://adriver.ru/ns/restapi/atom">
<id>791553</id>
<name>Шаблон</name>
<enable>1</enable>
<enables/>
<burst_mode>1</burst_mode>
<limits>
<total>
<exposures>0</exposures>
<clicks>0</clicks>
<uniqClicks>0</uniqClicks>
</total>
<daily>
<exposures>0</exposures>
<clicks>0</clicks>
</daily>
<frequency>
<daily>0</daily>
<weekly>0</weekly>
<monthly>0</monthly>
</frequency>
</limits>
<externalId>AD1000</externalId>
<schedule/>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
<banners/>
</adPlacement>
</content>
<link rel="related" type="text/html" href="http://.../cgi-bin/mngcgi?templ=action/AddBannerLogin&login=zackery&adID=328525&profileID=791553"/>
<adriver:bannerLoader>http://.../cgi-bin/mngcgi?templ=action/AddBannerLogin&login=zackery&adID=328525&profileID=791553</adriver:bannerLoader>
<adriver:revision>9456dfde07fb8ac2e180019c094b0f7c7e188323</adriver:revision>
</entry>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-21T17:23:41+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AdPlacement Atom Entry</title>
<id>urn:x-adriver:791628</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/adplacements/791628"/>
<content type="text/xml">
<adPlacement xmlns="http://adriver.ru/ns/restapi/atom">
<id>791628</id>
<name>Profile1</name>
<enable>0</enable>
<enables>
<enable name="UU_REPORT">1</enable>
</enables>
<burst_mode>1</burst_mode>
<limits>
<total>
<exposures>1000000</exposures>
<clicks>10000</clicks>
<uniqClicks>0</uniqClicks>
</total>
<daily>
<exposures>50000</exposures>
<clicks>500</clicks>
</daily>
<frequency>
<daily>0</daily>
<weekly>0</weekly>
<monthly>20</monthly>
</frequency>
</limits>
<externalId>AD1001</externalId>
<schedule/>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
<banners/>
</adPlacement>
</content>
<link rel="related" type="text/html" href="http://.../cgi-bin/mngcgi?templ=action/AddBannerLogin&login=zackery&adID=328525&profileID=791628"/>
<adriver:bannerLoader>http://.../cgi-bin/mngcgi?templ=action/AddBannerLogin&login=zackery&adID=328525&profileID=791628</adriver:bannerLoader>
Примечания к коду:
- 791553 — Идентификатор первого сценария из списка сценариев рекламной кампании.
- 791628 — Идентификатор второго сценария из списка сценариев рекламной кампании.
Код ответа 200.
Пример запроса на получение списка сценариев с использованием фильтра по полю externalId:
GET/adplacements?ad_id=adId&filter={"externalId":"AD1000"}
Content-Type:application/atom+xml
X-Auth-UserID:UserID
X-Auth-Passwd:token
- AD1000 — пример внешнего ID сценария. Его необходимо заменить на ваш внешний ID сценария.
- adId — идентификатор рекламной кампании. Вместо adId необходимо указать ID рекламной кампании, например ad_id=100000.
В ответ система возвращает все текущие данные по найденному сценарию:
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-21T17:23:41+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AdPlacement Atom Feed</title>
<id>https://api.adriver.ru/adplacements?ad_id=328525</id>
<link rel="self" type="application/atom+xml" href="https://api.adriver.ru/adplacements?ad_id=328525"/>
<entry xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-21T17:23:41+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AdPlacement Atom Entry</title>
<id>urn:x-adriver:791553</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/adplacements/791553"/>
<content type="text/xml">
<adPlacement xmlns="http://adriver.ru/ns/restapi/atom">
<id>791553</id>
<name>Шаблон</name>
<enable>1</enable>
<enables/>
<burst_mode>1</burst_mode>
<limits>
<total>
<exposures>0</exposures>
<clicks>0</clicks>
<uniqClicks>0</uniqClicks>
</total>
<daily>
<exposures>0</exposures>
<clicks>0</clicks>
</daily>
<frequency>
<daily>0</daily>
<weekly>0</weekly>
<monthly>0</monthly>
</frequency>
</limits>
<externalId>AD1000</externalId>
<schedule/>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
<banners/>
</adPlacement>
</content>
<link rel="related" type="text/html" href="http://.../cgi-bin/mngcgi?templ=action/AddBannerLogin&login=zackery&adID=328525&profileID=791553"/>
<adriver:bannerLoader>http://.../cgi-bin/mngcgi?templ=action/AddBannerLogin&login=zackery&adID=328525&profileID=791553</adriver:bannerLoader>
<adriver:revision>9456dfde07fb8ac2e180019c094b0f7c7e188323</adriver:revision>
</entry>
7.3. Редактирование данных сценария
Если необходимо изменить данные ранее добавленного сценария, то это можно осуществить с помощью запроса на его изменение. Операция редактирования по своей сути аналогична операции добавления сценария, поскольку в соответствующем запросе содержится полный список необходимых параметров сценария.
В отличие от команды добавления сценария команда редактирования сценария содержит дополнительный тег
Примечание: При редактировании все данные запроса переписываются заново для редактируемого сценария, независимо от того, изменились ли их значения или нет.
В приведенном примере запрос на редактирование содержит измененное значение ограничений на количество показов уникальным пользователям.
PUT/adplacements/791628
Content-Type: application/atom+xml
X-Auth-UserID:UserID
X-Auth-Passwd:token
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<title>AD Atom Entry</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2011-06-08T09:03:24+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<content type="text/xml">
<adPlacement xmlns="http://adriver.ru/ns/restapi/atom">
<name>Profile1</name>
<enable>false</enable>
<limits>
<total>
<exposures>1000000</exposures>
<clicks>10000</clicks>
<uniqClicks>0</uniqClicks>
</total>
<daily>
<exposures>50000</exposures>
<clicks>500</clicks>
</daily>
<frequency>
<daily>0</daily>
<weekly>0</weekly>
<monthly>20</monthly>
</frequency>
</limits>
<externalId>AD1000</externalId>
</adPlacement>
</content>
<adriver:revision>cc99eeb3eb95c9a5b8e4be6850a8bff32f780473</adriver:revision>
</entry>
В случае успешного редактирования в ответе возвращаются все текущие данные сценария и обновленный номер ревизии, аналогично ответу системы при добавлении сценария.
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-21T17:22:16+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AdPlacement Atom Entry</title>
<id>urn:x-adriver:791628</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/adplacements/791628"/>
<content type="text/xml">
<adPlacement xmlns="http://adriver.ru/ns/restapi/atom">
<id>791628</id>
<name>Profile1</name>
<enable>0</enable>
<enables>
<enable name="UU_REPORT">1</enable>
</enables>
<burst_mode>1</burst_mode>
<limits>
<total>
<exposures>1000000</exposures>
<clicks>10000</clicks>
<uniqClicks>0</uniqClicks>
</total>
<daily>
<exposures>50000</exposures>
<clicks>500</clicks>
</daily>
<frequency>
<daily>0</daily>
<weekly>0</weekly>
<monthly>20</monthly>
</frequency>
</limits>
<externalId>AD1000</externalId>
<schedule/>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
<banners/>
</adPlacement>
</content>
<link rel="related" type="text/html" href="http://.../cgi-bin/mngcgi?templ=action/AddBannerLogin&login=zackery&adID=328525&profileID=791628"/>
<adriver:bannerLoader>http://.../cgi-bin/mngcgi?templ=action/AddBannerLogin&login=zackery&adID=328525&profileID=791628</adriver:bannerLoader>
<adriver:revision>9cfdf743fd3e429c2d3bdf53b2044261c75bc9ff</adriver:revision>
</entry>
Код ответа 200.
В случае ошибки, например, при несовпадении номеров ревизий клиента (в запросе) и сервера, выдается ответ следующего вида:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2012-03-23T13:22:16+04:00</updated>
<content type="text">revision collision for adplacement (id=791628)</content>
<summary>Adriver::RestAPI::Core::Exception::RevisionCollision</summary>
</entry>
Код ответа 412.
Если пользователь делает запрос на редактирование чужого сценария, выдается ответ следующего вида:
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2012-03-23T13:24:43+04:00</updated>
<content type="text">Not authorized to work with object [Adriver::API::AdPlacementX]</content>
<summary>Adriver::RestAPI::Core::Exception::UnAuthorized</summary>
</entry>
Код ответа 401.
7.4. Просмотр данных сценария
Имеется возможность также получить данные сценария по его уникальному идентификатору. Идентификатор сценария выдается в ответе системы при добавлении сценария, также можно получить уникальные идентификаторы всех сценариев данного сайта при просмотре списка сценариев (п.7.2).
Пример запроса на просмотр данных сценария:
GET/adplacements/791628 Content-Type: application/atom+xml X-Auth-UserID:UserID X-Auth-Passwd:token
В ответ система возвращает все текущие данные по запрошенному идентификатору сценария (в сценарии пока отсутствуют баннеры):
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-21T17:20:09+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AdPlacement Atom Entry</title>
<id>urn:x-adriver:791628</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/adplacements/791628"/>
<content type="text/xml">
<adPlacement xmlns="http://adriver.ru/ns/restapi/atom">
<id>791628</id>
<name>Profile1</name>
<enable>0</enable>
<enables>
<enable name="UU_REPORT">1</enable>
</enables>
<burst_mode>1</burst_mode>
<limits>
<total>
<exposures>1000000</exposures>
<clicks>10000</clicks>
<uniqClicks>0</uniqClicks>
</total>
<daily>
<exposures>50000</exposures>
<clicks>500</clicks>
</daily>
<frequency>
<daily>1</daily>
<weekly>3</weekly>
<monthly>7</monthly>
</frequency>
</limits>
<externalId></externalId>
<schedule/>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
<banners/>
</adPlacement>
</content>
<link rel="related" type="text/html" href="http://.../cgi-bin/mngcgi?templ=action/AddBannerLogin&login=zackery&adID=328525&profileID=791628"/>
<adriver:bannerLoader>http://.../cgi-bin/mngcgi?templ=action/AddBannerLogin&login=zackery&adID=328525&profileID=791628</adriver:bannerLoader>
<adriver:revision>cc99eeb3eb95c9a5b8e4be6850a8bff32f780473</adriver:revision>
</entry>
Код ответа 200.
Ответ системы для сценария с одним баннером выглядит следующим образом:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-26T14:22:56+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>AdPlacement Atom Entry</title>
<id>urn:x-adriver:791628</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/adplacements/791628"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/banners/1683048"/>
<content type="text/xml">
<adPlacement xmlns="http://adriver.ru/ns/restapi/atom">
<id>791628</id>
<name>Profile1</name>
<enable>0</enable>
<enables>
<enable name="UU_REPORT">1</enable>
</enables>
<burst_mode>1</burst_mode>
<limits>
<total>
<exposures>1000000</exposures>
<clicks>10000</clicks>
<uniqClicks>0</uniqClicks>
</total>
<daily>
<exposures>50000</exposures>
<clicks>500</clicks>
</daily>
<frequency>
<daily>0</daily>
<weekly>0</weekly>
<monthly>20</monthly>
</frequency>
</limits>
<externalId></externalId>
<schedule/>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
<banners>
<href>https://api.adriver.ru/banners/1683048</href>
</banners>
</adPlacement>
</content>
<link rel="related" type="text/html" href="http://.../cgi-bin/mngcgi?templ=action/AddBannerLogin&login=zackery&adID=328525&profileID=791628"/>
<adriver:bannerLoader>http://.../cgi-bin/mngcgi?templ=action/AddBannerLogin&login=zackery&adID=328525&profileID=791628</adriver:bannerLoader>
<adriver:revision>f89891edd4e18f34fa6854bf7a7c0fe618d8096c</adriver:revision>
</entry>
Код ответа 200.
Если в запросе на просмотр данных сценария был указан идентификатор несуществующего сценария, то ответ системы будет выглядеть следующим образом:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2012-03-19T13:51:19+04:00</updated>
<content type="text"> adPlacement (id 99695635) not found.</content>
<summary>Adriver::RestAPI::Core::Exception::Slice::NotFound</summary>
</entry>
Код ответа 404.
4.7.5. Просмотр данных сценария “Дефолтовые Баннеры”
Данный ресурс предоставляет доступ к дефолтному сценарию кампании. Его нельзя создать, обновить или удалить.
Обращение происходит по id кампании или id сетевой кампании. Для получения этого ресурса необходимы права на чтение данных о кампании.
GET /default_adplacement/ad/410332 Content-Type: application/atom+xml X-Auth-UserID:UserID X-Auth-Passwd:token
GET /default_adplacement/net_ad/210045 Content-Type: application/atom+xml X-Auth-UserID:UserID X-Auth-Passwd:token </entry>
В ответ система возвращает все текущие данные по запрошенному идентификатору сценария:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2013-07-03T18:07:50+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>DefaultAdPlacement Atom Entry</title>
<id>urn:x-adriver:410332</id>
<link rel="read" type="application/atom+xml" href="https://api.adriver.ru/DefaultAdPlacement/ad/410332"/>
<content type="text/xml">
<DefaultAdPlacement xmlns="http://adriver.ru/ns/restapi/atom">
<id>410332</id>
<banners>
<href>https://api.adriver.ru/banners/2691791</href>
</banners>
</DefaultAdPlacement>
</content>
</entry>
8. Работа с баннерами
Использование программного интерфейса позволяет осуществлять следующие операции с баннерами в системе AdRiver:
- добавление баннера;
- просмотр настроек баннера;
- изменение настроек баннера.
Параметры, используемые при работе с баннерами в системе AdRiver через программный интерфейс, подразделяются на обязательные и необязательные. Обязательные параметры необходимо использовать при создании и редактировании баннера. Значения всех параметров, определенных для баннеров (как обязательных, так и необязательных), выдаются системой при ответе на запрос.
Обязательные параметры:
- userId – идентификатор учетной записи в системе (определяется при аутентификации);
- adPlacementId – идентификатор сценария, в котором демонстрируется баннер;
- type – тип баннера (задается с помощью указания кода типа баннера в системе AdRiver, таблица соответствия типов баннеров их кодам приведена в приложении 2);
- spec – подтип баннера (задается с помощью указания кода подтипа баннера в системе AdRiver, таблица соответствия подтипов баннеров их кодам приведена в приложении 3);
- target_url – адрес (URL), на который осуществляется переход по клику на баннер;
- period – период отображения баннера, задается с помощью параметров startDate (дата начала показа баннера) и stopDate (дата окончания показа баннера) в формате YYYY-MM-DD, при задании следует следить за тем, чтобы период отображения баннера не заканчивался раньше текущей даты.
Необязательные параметры:
- userEnable – признак включения баннера пользователем (1 – баннер включен, 0 – баннер выключен);
- enables* – список доступных для редактирования служебных параметров баннера;
- burst_mode – распределение показов в течение дня (0 – равномерное, 1 – с максимальной скоростью);
- priority – приоритет показа баннера (наименьший приоритет – 0, наивысший – 9);
- limits – ограничения на показ баннера (максимальное количество показов всего/в день, максимальное количество кликов всего/в день);
- comment – произвольный комментарий к баннеру;
- alt – текст, который отображается при наведении мыши на графический баннер, или вместо баннера, если в браузере у посетителя сайта выключена загрузка изображений;
- catId – категория баннера (используется только для баннеров сети RLE, устанавливается модератором сети);
- labelId – метка баннера (используется только для баннеров сети RLE, устанавливается модератором сети).
Примечания:
- Служебный параметр STANDART_FLASH блока enables используется при создании размерных html-баннеров (1 – если создаваемый размерный html-баннер является флеш-баннером; 0 – если создаваемый размерный html-баннер не является флеш-баннером). Параметр имеет значение для типов загрузки баннеров multipart и template (см. п.8.1).
- Служебный параметр ONLY_CLICK_BANNERS блока enables используется при создании кликовых баннеров (1 – если создаваемый баннер является кликовым; 0 – если создаваемый баннер не является кликовым). Параметр имеет значение для типа загрузки баннеров no (см. п.8.1).
Характеристики баннера (только для чтения):
- enable — признак включения баннера, вычисляется как userEnable&adminEnable;
- adminEnable — признак включения баннера модератором (1 – баннер включен, 0 – баннер выключен);
- on_moderation — признак ожидания баннером модерации в сети RLE (используется только для баннеров сети RLE, 1 – баннер ожидает модерации, 0 – баннер прошел модерацию);
- exposures — текущее количество показов баннера за сегодня;
- clicks — текущее количество кликов по баннеру за сегодня;
- uploadedFiles — загруженные файлы – компоненты баннера.
Более подробную информацию о баннерах можно получить из документации на сайте.
8.1. Добавление баннера
В теле запроса указываются значения всех обязательных параметров баннера. Пример запроса на добавление баннера:
POST/banners
Content-Type: application/atom+xml
X-Auth-UserID:UserID
X-Auth-Passwd:token
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<title>Banner Atom Entry</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2011-07-08T16:11:11+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<content type="text/xml">
<banner xmlns="http://adriver.ru/ns/restapi/atom" type="52" spec="100">
<userEnable>0</userEnable>
<burst_mode>1</burst_mode>
<priority>9</priority>
<target_url>http://www.adriver.ru</target_url>
<period>
<startDate>2012-03-26</startDate>
<stopDate>2012-12-30</stopDate>
</period>
<limits>
<total>
<exposures>50000</exposures>
<clicks>0</clicks>
<uniqClicks>0</uniqClicks>
</total>
<daily>
<exposures>500</exposures>
<clicks>0</clicks>
</daily>
<frequency>
<daily>2</daily>
<weekly>0</weekly>
<monthly>0</monthly>
</frequency>
</limits>
<alt>Тестовый баннер</alt>
<comment>test</comment>
</banner>
</content>
<adriver:userId>UserID</adriver:userId>
<adriver:adPlacementId>791628</adriver:adPlacementId>
</entry>
Примечания к коду:
- 52 — тип добавляемого баннера.
- 100 — подтип добавляемого баннера.
В случае успешного создания баннера будет возвращено его представление:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-26T14:26:48+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Banner Atom Entry</title>
<id>urn:x-adriver:1683144</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/banners/1683144"/>
<content type="text/xml">
<banner xmlns="http://adriver.ru/ns/restapi/atom" type="52" spec="100">
<id>1683144</id>
<on_moderation>0</on_moderation>
<enable>0</enable>
<userEnable>0</userEnable>
<adminEnable>1</adminEnable>
<enables>
<enable name="ADMIN_ENABLE">1</enable>
<enable name="UU_REPORT">1</enable>
</enables>
<burst_mode>1</burst_mode>
<priority>9</priority>
<target_url>http://www.adriver.ru</target_url>
<period>
<startDate>2012-03-26</startDate>
<stopDate>2012-12-30</stopDate>
</period>
<limits>
<total>
<exposures>50000</exposures>
<clicks>0</clicks>
<uniqClicks>0</uniqClicks>
</total>
<daily>
<exposures>500</exposures>
<clicks>0</clicks>
</daily>
<frequency>
<daily>2</daily>
<weekly>0</weekly>
<monthly>0</monthly>
</frequency>
</limits>
<comment>test</comment>
<alt>Тестовый баннер</alt>
<catId>0</catId>
<labelId>0</labelId>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
</banner>
</content>
<adriver:revision>e6e65c3b2f9353cb61b77f39c30a06fc04e2b5c5</adriver:revision>
</entry>
Примечания к коду:
- 1683144 — идентификатор добавленного баннера.
Код ответа 201.
8.2. Просмотр данных баннера
Имеется возможность получить данные баннера по его уникальному идентификатору. Идентификатор баннера выдается в ответе системы при добавлении баннера.
Пример запроса на просмотр данных баннера:
GET/banners/1683048 Content-Type: application/atom+xml X-Auth-UserID:UserID X-Auth-Passwd:token
В ответ система возвращает все текущие данные по запрошенному идентификатору баннера:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-26T14:28:43+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Banner Atom Entry</title>
<id>urn:x-adriver:1683048</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/banners/1683048"/>
<content type="text/xml">
<banner xmlns="http://adriver.ru/ns/restapi/atom" type="52" spec="101">
<id>1683048</id>
<on_moderation>0</on_moderation>
<enable>1</enable>
<userEnable>1</userEnable>
<adminEnable>1</adminEnable>
<enables>
<enable name="ADMIN_ENABLE">1</enable>
<enable name="USER_ENABLE">1</enable>
<enable name="UU_REPORT">1</enable>
<enable name="TARGET">1</enable>
</enables>
<burst_mode>1</burst_mode>
<priority>9</priority>
<target_url>http://adriver.ru</target_url>
<period>
<startDate>2012-03-26</startDate>
<stopDate>2020-12-31</stopDate>
</period>
<limits>
<total>
<exposures>0</exposures>
<clicks>0</clicks>
<uniqClicks>0</uniqClicks>
</total>
<daily>
<exposures>400</exposures>
<clicks>25</clicks>
</daily>
<frequency>
<daily>1</daily>
<weekly>0</weekly>
<monthly>0</monthly>
</frequency>
</limits>
<comment/>
<alt>AdRiver</alt>
<catId>0</catId>
<labelId>0</labelId>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
<uploadedFiles/>
</banner>
</content>
<adriver:revision>beab115c4ee18124d3b3185cba216911f5bc2793</adriver:revision>
</entry>
Код ответа 200.
Если в запросе на просмотр данных баннера был указан идентификатор несуществующего баннера, то ответ системы будет выглядеть следующим образом:
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2012-03-27T16:29:43+04:00</updated>
<content type="text">Banner (id 1693048) not found.</content>
<summary>Adriver::RestAPI::Core::Exception::Banner::NotFound</summary>
</entry>
Код ответа 404.
8.3. Редактирование данных баннера
Если необходимо изменить данные ранее добавленного баннера, то это можно осуществить с помощью запроса на его изменение. Операция редактирования по своей сути аналогична операции добавления баннера, поскольку в соответствующем запросе содержится полный список необходимых параметров баннера.
В отличие от команды добавления баннера команда редактирования баннера содержит дополнительный тег
Примечание: При редактировании все данные запроса переписываются заново для редактируемого баннера, независимо от того, изменились ли их значения или нет.
В приведенном примере запрос на редактирование содержит измененные значения распределения показов в течение дня, приоритета, а также ограничений на количество показов всего, в течение дня и уникальным пользователям.
PUT/banners/1683048
Content-Type: application/atom+xml
X-Auth-UserID:UserID
X-Auth-Passwd:token
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<title>Banner Atom Entry</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2011-07-08T16:11:11+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<content type="text/xml">
<banner xmlns="http://adriver.ru/ns/restapi/atom" type="52" spec="100">
<userEnable>0</userEnable>
<burst_mode>0</burst_mode>
<priority>8</priority>
<target_url>http://www.ria.ru</target_url>
<period>
<startDate>2012-03-26</startDate>
<stopDate>2013-01-30</stopDate>
</period>
<limits>
<total>
<exposures>777</exposures>
<clicks>777</clicks>
<uniqClicks>777</uniqClicks>
</total>
<daily>
<exposures>777</exposures>
<clicks>777</clicks>
</daily>
<frequency>
<daily>777</daily>
<weekly>777</weekly>
<monthly>777</monthly>
</frequency>
</limits>
<comment>новый комментарий</comment>
<catId>0</catId>
<labelId>0</labelId>
</banner>
</content>
<adriver:revision>171cbfba427b08f3c10936055af5523dd815fbb4</adriver:revision>
</entry>
В случае успешного редактирования в ответе возвращаются все текущие данные баннера и обновленный номер ревизии, аналогично ответу системы при добавлении баннера.
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-26T14:33:13+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Banner Atom Entry</title>
<id>urn:x-adriver:1683048</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/banners/1683048"/>
<content type="text/xml">
<banner xmlns="http://adriver.ru/ns/restapi/atom" type="52" spec="101">
<id>1683048</id>
<on_moderation>0</on_moderation>
<enable>0</enable>
<userEnable>0</userEnable>
<adminEnable>1</adminEnable>
<enables>
<enable name="ADMIN_ENABLE">1</enable>
<enable name="UU_REPORT">1</enable>
<enable name="TARGET">1</enable>
</enables>
<burst_mode>0</burst_mode>
<priority>8</priority>
<target_url>http://www.ria.ru</target_url>
<period>
<startDate>2012-03-26</startDate>
<stopDate>2013-01-30</stopDate>
</period>
<limits>
<total>
<exposures>777</exposures>
<clicks>777</clicks>
<uniqClicks>777</uniqClicks>
</total>
<daily>
<exposures>777</exposures>
<clicks>777</clicks>
</daily>
<frequency>
<daily>777</daily>
<weekly>777</weekly>
<monthly>777</monthly>
</frequency>
</limits>
<comment>новый комментарий</comment>
<alt>AdRiver</alt>
<catId>0</catId>
<labelId>0</labelId>
<exposures period="today">0</exposures>
<clicks period="today">0</clicks>
<uploadedFiles/>
</banner>
</content>
<adriver:revision>6117bbfd762745aa5f0c2a16098a39cc85fd5930</adriver:revision>
</entry>
Код ответа 200.
В случае ошибки, например, при несовпадении номеров ревизий клиента (в запросе) и сервера, выдается ответ следующего вида:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2012-03-27T16:31:17+04:00</updated>
<content type="text">revision collision for banner (id=1683048)</content>
<summary>Adriver::RestAPI::Core::Exception::RevisionCollision</summary>
</entry>
Код ответа 412.
Если пользователь делает запрос на редактирование чужого баннера, выдается ответ следующего вида:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2012-03-27T16:30:37+04:00</updated>
<content type="text">Not authorized to work with object [Adriver::API::Banner]</content>
<summary>Adriver::RestAPI::Core::Exception::UnAuthorized</summary>
</entry>
Код ответа 401.
8.4. Запрос на получение списка дефолтовых баннеров кампании
Пример запроса на получение списка всех дефолтовых баннеров кампании:
GET https://api.adriver.ru/default_adplacement/ad/ID_РК
Content-Type:application/atom+xml
X-Auth-UserID:UserID
X-Auth-Passwd:Token
Вместо ID_РК необходимо подставить ID рекламной кампании.
Пример запроса на получение списка всех дефолтовых баннеров сетевой РК:
GET https://api.adriver.ru/default_adplacement/net_ad/ID_РК
Content-Type:application/atom+xml
X-Auth-UserID:UserID
X-Auth-Passwd:Token
Вместо ID_РК необходимо подставить ID рекламной кампании.
В ответе системы будет возвращен список дефолтовых баннеров кампании (при их наличии). Пример ответа системы:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2014-05-14T10:43:51+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>DefaultAdPlacement Atom Entry</title>
<id>urn:x-adriver:422197</id>
<link rel="read" type="application/atom+xml" href="https://api.adriver.ru/default_adplacement/ad/422197"/>
<content type="text/xml">
<DefaultAdPlacement xmlns="http://adriver.ru/ns/restapi/atom">
<id>422197</id>
<type>ad</type>
<banners/>
</DefaultAdPlacement>
</content>
</entry>
9. Загрузка баннеров
Использование программного интерфейса позволяет осуществлять загрузку файлов для баннеров, созданных в системе AdRiver в соответствии с п.8 настоящего руководства. Загрузка файлов для баннеров включает в себя следующие этапы:
- получение формы для загрузки баннера;
- загрузка заполненной формы на сервер.
При загрузке файлов баннеров в систему AdRiver через программный интерфейс используются обязательные параметры, в ответах системы также отображаются характеристики баннера. Обязательные параметры необходимо использовать при заполнении формы для загрузки баннера.
Обязательные параметры:
-
fields – поля формы, необходимые для загрузки баннера определенного типа (подтипа):
- name – внутрисистемное наименование поля формы (не может быть изменено);
- value – имя файла компонента баннера, соответствующего этому полю (если тип данного поля формы – file) или необходимое значение (цифровое или символьное) для других типов данного поля формы;
- file – ссылка на файл (компонент баннера) в атрибуте href или содержимое файла, закодированное с помощью метода Base64.
Характеристики баннера (только для чтения):
- main_component — имя файла главной компоненты баннера (например, index.html, script.js и т.п.), может быть списком (массивом) имен файлов компонент баннера (например, массив [0.jpg/0.gif/0.png] для изображений);
- max_components — максимальное количество компонент баннера (используется только для баннеров типа Rich-media, для остальных типов баннера значение равно 0);
- upload_type — тип загрузки, возможные значения – singlepart (баннеры, состоящие из одного файла – изображения gif/jpg/png, ролики redirect_flash подтипов 81, 83, 84, 85 и Flv video подтипа 104), multipart (баннеры, состоящие из нескольких файлов – размерные html баннеры, не являющиеся флеш-баннерами, с файлом главной компоненты index.html; баннеры Javascript подтипов 20, 91, 99, 100, 102 с файлом главной компоненты script.js; баннеры generic xml подтипа 109 с файлом главной компоненты index.xml), template (баннеры, имеющие в своем составе типовой системный скрипт – размерные html баннеры, являющиеся флеш-баннерами, а также баннеры подтипов : 59, 76, 77, 80, 92, 97, 98, 101, 105, 107, 108, 113, 114), richmedia (баннеры типа Rich-media), teaser (баннеры, содержащие изображение и текст), no (баннеры, которые не требуют загрузки файлов – кликовые баннеры и баннеры подтипов 31, 103, 106, 110, 111 (различные зеропиксели));
-
fields — поля формы для загрузки баннера определенного типа (подтипа):
- type — тип поля (file | string | enum);
- enum — множество значений;
- file_type — тип файла (img | swf | flv);
- comp_num — номер компоненты (для баннеров типа Rich-media);
- size_limit — ограничение по размеру для файлов;
- mandatory — является ли обязательным (0 | 1);
- read_only — только для чтения (0 | 1).
9.1. Получение формы для загрузки баннера
Форму для загрузки баннера можно получить по его уникальному идентификатору. Форма для загрузки баннера выдается в ответе системы на соответствующий запрос. Для разных форматов баннеров выдаются разные формы для загрузки. Формы загрузки выдаются в виде XML в формате Atom Syndication Format – объекта Atom Entry.
Пример запроса на получение формы для загрузки баннера:
GET/banners/1723364/upload_form Content-Type: application/atom+xml X-Auth-UserID:UserID X-Auth-Passwd:token
В ответ система возвращает форму для загрузки баннера запрошенного идентификатора 1723364 (для баннера Flv video, состоящего из одного файла, тип загрузки singlepart):
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-04-12T15:41:21+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Banner Upload Form Atom Entry</title>
<id>https://api.adriver.ru/banners/1723364/upload_form</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/banners/1723364/upload_form"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/banners/1723364"/>
<content type="text/xml">
<bannerForm xmlns="http://adriver.ru/ns/restapi/atom">
<main_component>0.flv</main_component>
<max_components>0</max_components>
<upload_type>singlepart</upload_type>
<fields>
<field>
<name>upl_file</name>
<type>file</type>
<file_type>flv</file_type>
</field>
</fields>
</bannerForm>
</content>
</entry>
Примечания к коду:
- 0.flv — Имя файла баннера.
- singlepart — Тип загрузки баннера.
- <field>….</field> — Блок описания файла баннера.
Код ответа 200.
Пример ответа системы с формой для загрузки баннера запрошенного идентификатора 1723380 (для баннера html, состоящего из нескольких файлов и не являющегося флеш-баннером, тип загрузки multipart):
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-04-12T15:42:56+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Banner Upload Form Atom Entry</title>
<id>https://api.adriver.ru/banners/1723380/upload_form</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/banners/1723380/upload_form"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/banners/1723380"/>
<content type="text/xml">
<bannerForm xmlns="http://adriver.ru/ns/restapi/atom">
<main_component>index.html</main_component>
<max_components>0</max_components>
<upload_type>multipart</upload_type>
<fields>
<field>
<name>upl_file0</name>
<type>file</type>
</field>
<field>
<name>upl_file1</name>
<type>file</type>
</field>
<field>
<name>upl_file2</name>
<type>file</type>
</field>
<field>
<name>upl_file3</name>
<type>file</type>
</field>
<field>
<name>upl_file4</name>
<type>file</type>
</field>
<field>
<name>upl_file5</name>
<type>file</type>
</field>
<field>
<name>upl_file6</name>
<type>file</type>
</field>
<field>
<name>upl_file7</name>
<type>file</type>
</field>
<field>
<name>upl_file8</name>
<type>file</type>
</field>
<field>
<name>upl_file9</name>
<type>file</type>
</field>
</fields>
</bannerForm>
</content>
</entry>
Примечания к коду:
- index.html — Имя главной компоненты баннера.
- multipart — Тип загрузки баннера.
- <field>….</field> — Блоки описания файлов (компонент) баннера. В форме предусмотрена возможность загрузки 9 компонент баннера в виде различных файлов. Если необходимо загрузить больше файлов, следует сделать несколько запросов на загрузку баннера. При этом файлы, загруженные ранее, не удаляются, однако, могут заново перезаписаться при совпадении имен. Если файл главной компоненты не загружен, то баннер показываться не будет.
Код ответа 200.
Пример ответа системы с формой для загрузки баннера запрошенного идентификатора 1723384 (для размерного флеш-баннера, тип загрузки template):
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-04-12T15:44:16+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Banner Upload Form Atom Entry</title>
<id>https://api.adriver.ru/banners/1723384/upload_form</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/banners/1723384/upload_form"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/banners/1723384"/>
<content type="text/xml">
<bannerForm xmlns="http://adriver.ru/ns/restapi/atom">
<main_component>index.html</main_component>
<max_components>0</max_components>
<upload_type>template</upload_type>
<fields>
<field>
<name>gif_pixel</name>
<type>string</type>
<value/>
</field>
<field>
<name>flash_pixel</name>
<type>string</type>
<value/>
</field>
<field>
<name>img_name</name>
<type>file</type>
<file_type>img</file_type>
</field>
<field>
<name>img_action</name>
<type>enum</type>
<value> no</value>
<enum>no upload remove</enum>
</field>
<field>
<name>alt_click</name>
<type>string</type>
<value/>
</field>
<field>
<name>swf_name</name>
<type>file</type>
<file_type>swf </file_type>
</field>
<field>
<name>swf_action</name>
<type>enum</type>
<value>no</value>
<enum>no upload remove</enum>
</field>
<field>
<name>flash_ver</name>
<type>enum</type>
<value>5</value>
<enum>5 6 7 8 9 10</enum>
</field>
<field>
<name>wmode</name>
<type>enum</type>
<value>opaque</value>
<enum>window opaque transparent</enum>
</field>
<field>
<name>quality</name>
<type>enum</type>
<value>best</value>
<enum>best high medium low autohigh autolow</enum>
</field>
</fields>
</bannerForm>
</content>
</entry>
Примечания к коду:
- index.html — Имя главной компоненты баннера.
- template — Тип загрузки баннера.
- <value/> — Строка вызова стороннего счетчика (если он есть) при показе статической компоненты баннера.
- <value/> — Строка вызова стороннего счетчика (если он есть) при показе динамической (флеш) компоненты баннера.
- <field>….</field> — Блок описания файла статической компонеты баннера.
- <field>….</field> — Блок описания действия с файлом статической компонеты баннера при загрузке заполненной формы на сервер (оставить без изменений, загрузить, удалить).
- <value/> — Адрес (URL), по которому осуществляется переход по клику на баннер при показе только его статической компоненты.
- <field>….</field> — Блок описания файла динамической (флеш) компоненты баннера.
- <field>….</field> — Блок описания действия с файлом динамической компонеты баннера при загрузке заполненной формы на сервер (оставить без изменений, загрузить, удалить).
- 5 — Минимальная версия флеш-плагина пользователя для отображения флеш-компоненты баннера.
- opaque — Режим внедрения флеш-компоненты баннера на страницу сайта.
- best — Качество отображения флэш-компоненты баннера на странице сайта.
Код ответа 200.
Примечание: Форма для загрузки баннера по типу template для некоторых подтипов баннеров может содержать и другие поля для заполнения, отсутствующие в приведенном выше примере (например, высота и ширина изображения, расположение на странице относительно других окон и т.п.). При возникновении сложностей с заполнением таких полей следует обращаться в отдел технической поддержки компании AdRiver.
Пример ответа системы с формой для загрузки баннера запрошенного идентификатора 1726801 (для баннера Rich-media, состоящего из нескольких компонент и отображающегося поверх html-страницы сайта, тип загрузки richmedia):
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-04-13T17:42:36+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Banner Upload Form Atom Entry</title>
<id>https://api.adriver.ru/banners/1726801/upload_form</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/banners/1726801/upload_form"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/banners/1726801"/>
<content type="text/xml">
<bannerForm xmlns="http://adriver.ru/ns/restapi/atom">
<main_component>script.js</main_component>
<max_components>5</max_components>
<upload_type>richmedia</upload_type>
<fields>
<field>
<name>flash_ver</name>
<type>enum</type>
<value>5</value>
<enum>5 6 7 8 9 10</enum>
</field>
<field>
<name>width0</name>
<type>string</type>
<value>0</value>
<comp_num>0</comp_num>
</field>
<field>
<name>x_abs0</name>
<type>enum</type>
<value>0</value>
<enum>1 0 -1</enum>
<comp_num>0</comp_num>
</field>
<field>
<name>inline0</name>
<type>enum</type>
<value>0</value>
<enum>1 0</enum>
<comp_num>0</comp_num>
</field>
<field>
<name>scale_size0</name>
<type>string</type>
<value>1</value>
<comp_num>0</comp_num>
</field>
<field>
<name>jump0</name>
<type>enum</type>
<value>0</value>
<enum>1 0</enum>
<comp_num>0</comp_num>
</field>
<field>
<name>height0</name>
<type>string</type>
<value>0</value>
<comp_num>0</comp_num>
</field>
<field>
<name>scale_client0</name>
<type>enum</type>
<value>0</value>
<enum>0 1 2</enum>
<comp_num>0</comp_num>
</field>
<field>
<name>swf_name0</name>
<type>file</type>
<file_type>swf</file_type>
<comp_num>0</comp_num>
</field>
<field>
<name>swf_action0</name>
<type>enum</type>
<value>no</value>
<enum>no upload remove</enum>
<comp_num>0</comp_num>
</field>
<field>
<name>wmode0</name>
<type>enum</type>
<value>transparent</value>
<enum>window opaque transparent</enum>
<comp_num>0</comp_num>
</field>
<field>
<name>nailed0</name>
<type>enum</type>
<value>0</value>
<enum>1 0</enum>
<comp_num>0</comp_num>
</field>
<field>
<name>y_abs0</name>
<type>enum</type>
<value>0</value>
<enum>1 0 -1</enum>
<comp_num>0</comp_num>
</field>
<field>
<name>sticky0</name>
<type>enum</type>
<value>0</value>
<enum>1 0</enum>
<comp_num>0</comp_num>
</field>
<field>
<name>y_pos0</name>
<type>string</type>
<value>0.5</value>
<comp_num>0</comp_num>
</field>
<field>
<name>x_pos0</name>
<type>string</type>
<value>0.5</value>
<comp_num>0</comp_num>
</field>
<field>
<name>action0</name>
<type>enum</type>
<value>skip</value>
<enum>skip change add remove</enum>
<comp_num>0</comp_num>
</field>
<field>
<name>bg_color0</name>
<type>string</type>
<value>#ffffff</value>
<comp_num>0</comp_num>
</field>
<field> . . . </field> . . .
</fields>
</bannerForm>
</content>
</entry>
Примечания к коду:
- script.js — Имя главной компоненты баннера.
- 5 — Минимальная версия флеш-плагина пользователя для отображения баннера.
- <value>0</value> — Ширина флеш-клипа в пикселях.
- <comp_num>0</comp_num> — Порядковый номер компоненты.
- <value>0</value> — Абсолютное положение флеш-клипа по оси X.
- <value>0</value> — Положение флеш-клипа внутри текста (1-да, 0 – нет).
- <value>1</value> — Масштабирование изображения флеш-клипа.
- <value>0</value> — Скачкообразное перемещение флеш-клипа по экрану (1 – да, 0 – нет)та.
- <value>0</value> — Высота флеш-клипа в пикселях.
- <value>0</value> — Масштабирование изображения флеш-клипа относительно исходного размера (0), по меньшей стороне (1), по большей стороне (2).
- <field>….</field> — Блок описания файла флеш-компоненты.
- <field>….</field> — Блок описания действия с файлом флеш-компоненты баннера при загрузке заполненной формы на сервер (оставить без изменений, загрузить, удалить).
- transparent — Режим внедрения флеш-компоненты баннера на страницу сайта .
- <value>0</value> — Флеш-клип не перемещается при скроллинге страницы сайта (1 – да, 0 – нет).
- <value>0</value> — Абсолютное положение флеш-клипа по оси Y.
- <value>0</value> — Флеш-клип всегда находится на экране (1 – да, 0 – нет).
- <value>0.5</value>— Положение флеш-клипа по оси Y.
- <value>0.5</value>— Положение флеш-клипа по оси X.
- <field>….</field> — Блок описания действия с данной компонентой при загрузке заполненной формы на сервер (оставить параметры без изменений, изменить параметры, добавить компоненту, удалить компоненту).
- <value>#ffffff</value>— Цвет фона (подложки).
- <field>….</field> — Аналогичные блоки описаний для всех последующих компонент баннера (отдельно для каждого порядкового номера).
Код ответа 200.
Пример ответа системы с формой для загрузки баннера запрошенного идентификатора 1730310 (для баннера, содержащего изображение и текст, тип загрузки teaser):
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-04-17T12:58:24+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Banner Upload Form Atom Entry</title>
<id>https://api.adriver.ru/banners/1730310/upload_form</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/banners/1730310/upload_form"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/banners/1730310"/>
<content type="text/xml">
<bannerForm xmlns="http://adriver.ru/ns/restapi/atom">
<main_component>0.gif</main_component>
<main_component>0.jpg</main_component>
<main_component>0.png</main_component>
<max_components>0</max_components>
<upload_type>teaser</upload_type>
<fields>
<field>
<name>upl_file</name>
<type>file</type>
<file_type>img</file_type>
</field>
<field>
<name>alt_text</name>
<type>string</type>
<value/>
</field>
</fields>
</bannerForm>
</content>
</entry>
Примечания к коду:
- 0.gif или 0.jpg или 0.png— Имя главной компоненты баннера (можно загрузить файл любого из трех вариантов форматов).
- teaser — Тип загрузки баннера.
- <field>….</field> — Блок описания файла изображения.
- <value/> — Текст баннера (слоган).
Код ответа 200.
Пример ответа системы на запрос формы для загрузки баннера запрошенного идентификатора 1730316 (для зеропикселя подтипа 106, тип загрузки no):
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-04-17T13:00:52+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Banner Upload Form Atom Entry</title>
<id>https://api.adriver.ru/banners/1730316/upload_form</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/banners/1730316/upload_form"/>
<link rel="related" type="application/atom+xml" href="https://api.adriver.ru/banners/1730316"/>
<content type="text/xml">
<bannerForm xmlns="http://adriver.ru/ns/restapi/atom">
<fields/>
</bannerForm>
</content>
</entry>
Код ответа 200.
9.2. Загрузка заполненной формы на сервер
В примере запроса на загрузку заполненной формы загружается баннер Generic AjaxJS типа 52 подтипа 100:
PUT/banners/1683144/upload_form Content-Type: application/atom+xml X-Auth-UserID:UserID X-Auth-Passwd:token <?xml version="1.0" encoding="utf-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom"> <updated>2012-03-30T17:45:38+04:00</updated> <author> <name>Adriver::RestAPI</name> </author> <title>Banner Upload Form Atom Entry</title> <id>https://api.adriver.ru/banners/1683144/upload_form</id> <link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/banners/1683144/upload_form"/> <link rel="related" type="application/atom+xml" href="https://api.adriver.ru/banners/1683144"/> <content type="text/xml"> <bannerForm xmlns="http://adriver.ru/ns/restapi/atom"> <main_component>script.js</main_component> <max_components>0</max_components> <upload_type>multipart</upload_type> <fields> <field> <name>upl_file0</name> <type>file</type> <value>banner.html</value> <file href="http://files.adriver.ru/share/husainov/ajax_html/banner.html"></file> </field> <field> <name>upl_file1</name> <type>file</type> <value>script.js</value> <file href="http://files.adriver.ru/share/husainov/ajax_html/script.js"></file> </field> </fields> </bannerForm> </content> </entry>
Примечания к коду:
- 1683144— Идентификатор загружаемого баннера.
- script.js — Имя главной компоненты баннера.
- multipart — Тип загрузки баннера.
- http://files.adriver.ru/share/husainov/ajax_html/banner.html — Ссылка на файл первой компоненты баннера.
- http://files.adriver.ru/share/husainov/ajax_html/script.js — Ссылка на файл второй компоненты баннера.
В случае успешной загрузки формы клиенту возвращается объект Atom Entry со ссылкой на загруженный баннер:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:adriver="http://adriver.ru/ns/restapi/atom">
<updated>2012-03-30T17:52:21+04:00</updated>
<author>
<name>Adriver::RestAPI</name>
</author>
<title>Banner Upload Status Atom Entry</title>
<id>https://api.adriver.ru/banners/1683144/upload_form</id>
<link rel="edit" type="application/atom+xml" href="https://api.adriver.ru/banners/1683144/upload_form"/>
<link rel="alternate" type="application/atom+xml" href="https://api.adriver.ru/banners/1683144"/>
<adriver:revision>2e249942a01a41c5f3e14cf40bffb66a1b657495</adriver:revision>
</entry>
Код ответа 200.
Если в процессе загрузки произошла ошибка, например, не найден файл баннера, выдается ответ следующего вида:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Adriver::RestAPI Exception</title>
<author>
<name>Adriver::RestAPI</name>
</author>
<updated>2012-03-30T17:54:07+04:00</updated>
<content type="text">couldn't download file: '404 Not Found'</content>
<summary>Adriver::RestAPI::Core::Exception</summary>
</entry>
Код ответа 500.