Этот инструмент позволяет пользователям API узнавать об изменении ресурсов API, используя push- вместо pull-модели.
Пользователь API подписывается на изменения конкретного ресурса с указанием его типа и идентификатора или же на изменения всех ресурсов одного типа без указания идентификатора. При подписке указывается URL, на который при любом изменении ресурса будет отправлен HTTP-запрос методом POST с содержимым следующего вида:
{
"id": "07c0810ac51c47c98e001b1e91c94ba4",
"resource_id": 864614,
"resource": "CAMPAIGN",
"created": "2014-06-02 18:23:29.797499",
"diff": {
"updated": {
"---": "2014-06-02 18:21:58",
"+++": "2014-06-02 18:23:29"
},
"name": {
"---": "Новая кампания",
"+++": "Новая кампания123"
}
}
}
Пожалуйста, учтите, что запрос имеет тип Content-type: application/json, поэтому, например, в PHP нельзя использовать переменные $_POST и $_REQUEST для доступа к его содержимому. До версии 5.6.0 можно использовать $HTTP_RAW_POST_DATA, а если PHP более новый, то php://input. Например:
$push_data = json_decode(file_get_contents('php://input'), true);
Для управления подписками в API реализован специальный ресурс:
/api/v2/subscriptions.json
Чтобы подписаться на уведомления об изменении ресурса нужно послать запрос вида:
POST /api/v2/subscriptions.json HTTP/1.1
Host: target.my.com
Content-Type: application/json
{"callback_url": "http://mysuperhost.com/callback", "resource": "CAMPAIGN", "resource_id": 123}
Если не указать resource_id в запросе, то подписка будет осуществлена на изменения всех пользовательских объектов указанного типа, включая вновь создаваемые. Для ресурса OKLEADAD resource_id указывать не нужно, указание приведёт к ошибке.
Посмотреть все подписки пользователя можно, отправив GET-запрос:
GET /api/v2/subscriptions.json HTTP/1.1
Host: target.my.com
Удалить подписку — DELETE-запрос с идентификатором конкретной подписки:
DELETE /api/v2/subscriptions/{идентификатор подписки}.json HTTP/1.1
Host: target.my.com
На данный момент уведомления работают только для
кампаний - resource=CAMPAIGN,
объявлений - resource=BANNER,
аудиторий - resource=REMARKETING,
лиды - resource=OKLEADAD, для получения информации о новых лидах не нужно указывать resource_id.
В случае, если отправка сообщений получателю по какой-то причине не завершилась корректно, производится повторная попытка через 10 минут, затем через час и сутки после первой попытки.