Урок 10. Как использовать API эффективно: ограничения и рекомендации

В этом уроке вы узнаете:

В этом уроке мы расскажем, какие ограничения применяются в API Директа и как рационально организовать работу приложения с учетом этих ограничений.

Чтобы регулировать нагрузку на сервер API, применяются различные виды ограничений. От имени одного рекламодателя можно выполнить не более 5 запросов одновременно. В каждом методе предусмотрены лимиты на количество объектов в одном запросе. Кроме того, в API действует система баллов.

Каждому рекламодателю (и агентству) предоставляется индивидуальный суточный лимит баллов. Начисление баллов происходит равномерно в течение суток. Баллы списываются за вызов метода, за изменение или получение каждого объекта, за ошибку в запросе. Нехватка баллов не позволяет выполнять запросы к API.

Как узнать, сколько баллов израсходовано и сколько осталось

В ответе на каждый запрос сервер API передает HTTP-заголовок Units, в котором указано количество баллов:

Units: израсходовано при выполнении запроса/доступный остаток/суточный лимит

Пример ответа

HTTP/1.1 200 OK
Connection:close
Content-Type:application/json
Date:Fri, 28 Jun 2018 17:07:02 GMT
RequestId: 1111111111111111112
Units: 10/20828/64000
Server:nginx
Transfer-Encoding:chunked

{
  "result": {
    ...
  }
}

RequestId — идентификатор запроса.
Units — количество баллов.

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

Как оптимизировать расход баллов

Мы рекомендуем все данные, с которыми работает приложение, хранить в кэше — например, в локальной базе данных. Получив с сервера параметры кампаний, групп, объявлений, ключевых фраз, а также справочники регионов и часовых поясов, вы можете отслеживать их актуальность с помощью методов сервиса Changes. Перед тем как обновлять данные в кэше, следует проверить наличие изменений. Заново получать с сервера нужно только фактически изменившиеся объекты. Таким образом вы сможете уменьшить объем передаваемых данных, ускорить работу приложения и снизить расход баллов.

Как отслеживать изменения с помощью сервиса Changes

1. При первом запуске приложения вызовите в сервисе Changes метод checkDictionaries без параметров. В ответе вы получите параметр Timestamp — текущее время на сервере по UTC.

cURL

curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"checkDictionaries","params":{}}' https://api.direct.yandex.com/json/v5/changes

cURL для Windows

curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"checkDictionaries\",\"params\":{}}" https://api.direct.yandex.com/json/v5/changes

Запрос

{
  "method": "checkDictionaries",
  "params": { }
}

Ответ

{
  "result": {
    "Timestamp": "2018-06-03T12:48:27Z"
  } 
}

2. Чтобы получить список кампаний, в которых произошли изменения, вызовите метод checkCampaigns. При каждом последующем вызове указывайте значение параметра Timestamp, полученное при предыдущем вызове: это гарантирует непрерывность интервалов для проверки изменений.

cURL

curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"checkCampaigns","params":{"Timestamp":"2018-06-03T12:48:27Z"}}' https://api.direct.yandex.com/json/v5/changes

cURL для Windows

curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"checkCampaigns\",\"params\":{\"Timestamp\":\"2018-06-03T12:48:27Z\"}}" https://api.direct.yandex.com/json/v5/changes

Запрос

{
  "method": "checkCampaigns",
  "params": {
    "Timestamp": "2018-06-03T12:48:27Z"
  }
}

Ответ

{
  "result": {
    "Timestamp": "2018-07-01T13:11:27Z",
    "Campaigns": [{
      "CampaignId": 136200,
      "ChangesIn": [ "SELF", "CHILDREN" ]
    }, {
      "CampaignId": 136201,
      "ChangesIn": [ "STAT" ]
    }]
  }
}

Метод возвращает идентификаторы кампаний, в которых произошли изменения. В параметре ChangesIn указывается, где произошли изменения:

SELF — в параметрах кампании;
CHILDREN — в дочерних объектах (группах, объявлениях, фразах);
STAT — корректировка статистики кампании (как правило, в связи с фильтрацией недобросовестных кликов).

3. Если метод checkCampaigns показал наличие изменений в дочерних объектах, получите более подробную информацию об изменениях с помощью метода check.

cURL

curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"check","params": {"Timestamp":"2018-06-03T12:48:27Z","CampaignIds": [136200],"FieldNames": ["AdGroupIds","AdIds"]}}'  https://api.direct.yandex.com/json/v5/changes

cURL для Windows

curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"check\",\"params\": {\"Timestamp\":\"2018-06-03T12:48:27Z\",\"CampaignIds\": [136200],\"FieldNames\": [\"AdGroupIds\",\"AdIds\"]}}" https://api.direct.yandex.com/json/v5/changes

Запрос

{
  "method": "check",
  "params": {
    "CampaignIds": [136200],
    "FieldNames": ["AdGroupIds","AdIds"],
    "Timestamp": "2018-06-03T12:48:27Z"
  }
}

Ответ

{
  "result": {
    "Timestamp": "2018-07-01T13:12:22Z",
    "Modified": {
      "AdGroupIds": [22222222],
      "AdIds": [33333333,33333334]      
    }
  }
}

Внимание. Если метод check показал наличие изменений в группе объявлений (идентификатор группы указан в массиве AdGroupIds), это может означать изменение в параметрах самой группы или в ключевых фразах.

Получите с сервера изменившиеся объекты с помощью методов get соответствующих сервисов — Campaigns, AdGroups, Ads или Keywords.

Задание

Создайте в Песочнице новую кампанию, группу и объявление.
Отправьте объявление на модерацию с помощью метода moderate сервиса Ads.
Получите данные по всем кампаниям.
Получите данные об изменениях по всем кампаниям.
Узнайте с помощью метода check, в каких объявлениях произошли изменения (должен измениться статус объявления, отправленного на модерацию).
Получите заголовки и тексты принятых на модерации объявлений.
Посмотрите, сколько баллов вы потратили на эти запросы.

Все аспекты работы с API Директа подробно описаны в документации.

Желаем успеха!

Полезные ссылки

Документация:

Вопросы

Была ли статья полезна?

Расскажите, что вам не понравилось в статье:

Урок 9. Как перейти к реальной работе

API версии 5. История изменений

В этой статье

Как узнать, сколько баллов израсходовано и сколько осталось Как оптимизировать расход баллов Как отслеживать изменения с помощью сервиса Changes Задание Полезные ссылки Вопросы

Урок 9. Как перейти к реальной работе

API версии 5. История изменений