Урок 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 — количество баллов.

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

Мы рекомендуем все данные, с которыми работает приложение, хранить в кэше — например, в локальной базе данных. Получив с сервера параметры кампаний, групп, объявлений, ключевых фраз, а также справочники регионов и часовых поясов, вы можете отслеживать их актуальность с помощью методов сервиса 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]      
        }
      }
    }

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

Задание

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

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

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