Пишем Ruby gem для Yandex Direct API. Директ апи

API Директа — Варианты использования — Технологии Яндекса

Ведение рекламных кампаний

Программный интерфейс позволяет эффективно управлять сложными и масштабными рекламными кампаниями с большим количеством объявлений и ключевых фраз. С помощью API можно автоматизировать рутинные операции — например, периодическое обновление цен клика по определенному алгоритму. API также позволяет создавать удобные пользовательские инструменты для просмотра и редактирования кампаний: чтобы внести изменения, не нужно ждать загрузки страниц, как в веб-интерфейсе.

Интеграция с бизнес-приложениями С помощью API Директа можно управлять рекламой на основе информации о товарах и услугах из вашей базы данных, например:

автоматически генерировать большие массивы ключевых фраз, добавляя в них названия конкретных брендов или моделей товаров — по таким уточненным фразам цены клика ниже, а кликабельность и конверсия выше, чем по «обобщенным»;
останавливать и возобновлять показы объявлений в зависимости от наличия товаров на складе;

обновлять тексты объявлений при изменении цены товара;
автоматически формировать объявления о проведении акций и распродаж; повышать объем трафика для таких объявлений.

A/B-тестирование объявлений

Через API можно создавать и редактировать группы объявлений — несколько вариантов объявлений с одинаковым набором ключевых слов и других настроек показа. Вначале объявления в группе показываются в ротации, а по мере накопления статистики система начинает чаще показывать объявление с самым высоким CTR. Таким образом, из группы объявлений будет автоматически выбран вариант, наиболее привлекательный для аудитории.

Мониторинг и анализ эффективности рекламных кампаний API Директа позволяет получать как сводную, так и детальную статистику показов, кликов, конверсии и расходов и выгружать ее в системы поддержки принятия решений, системы финансового учета и др. Подбор ключевых фраз и расширение рекламных кампаний Инструмент подбора слов позволяет по заданным ключевым словам получить статистику поисковых запросов с этими словами, а также статистику других запросов пользователей, выполнявших запросы с этими словами. Полученные данные можно использовать для дополнения списка ключевых фраз. Оценить стоимость и потенциальное количество кликов для этих фраз на разных позициях показа поможет инструмент прогнозирования бюджета.

Полный список доступных операций приведен в документации.

tech.yandex.ru

API Директа — Доступ — Технологии Яндекса

Приложение (программа, скрипт и др.) выполняет запрос к API от имени пользователя Директа — рекламодателя или рекламного агентства — и управляет данными, принадлежащими этому пользователю.

Доступ приложения к данным пользователя возможен при выполнении следующих условий:

Разработчик приложения выполнил процедуру регистрации приложения, и заявка на доступ была одобрена.
Пользователь Директа является прямым рекламодателем, рекламным агентством или клиентом рекламного агентства, которому агентство разрешило доступ к его данным.
Примечание.
- Если агентство предоставило клиенту доступ в веб-интерфейс только на чтение, то и через API клиент сможет только получать данные.
- Если агентство предоставило клиенту право на редактирование кампаний, то клиент сможет управлять своими кампаниями как в веб-интерфейсе, так и через API.
От имени пользователя создана хотя бы одна рекламная кампания в веб-интерфейсе.
Пользователь принял условия пользовательского соглашения на странице API сервиса Яндекс.Директ.
Пользователь разрешил приложению выполнять запросы от своего имени.

Приложение должно запросить у пользователя разрешение на доступ к его данным, получить авторизационный токен и указывать его в запросах.

Чтобы получить токен, приложение должно перенаправить пользователя на страницу запроса доступа. Пользователь авторизуется на Яндексе (под своим логином в Директе) и нажимает кнопку Подтвердить. Далее сервер Яндекса генерирует токен и передает его приложению.

Ограничение доступа по IP-адресу

Доступ к API можно ограничить по IP-адресу, что повышает информационную безопасность. Список разрешенных IP-адресов пользователь может указать на странице Настройки API на вкладке Параметры.

Формат взаимодействия

Доступ к API предоставляется через криптографический протокол SSL. Установка SSL-соединения обязательна для вызова методов API.

API Яндекс.Директа поддерживает два способа взаимодействия:

Запросы JSON меньше нагружают сервер и быстрее обрабатываются.

tech.yandex.ru

API Директа — Доступ и авторизация — Технологии Яндекса

Доступ приложения к данным пользователя возможен при выполнении следующих условий:

Разработчик приложения выполнил процедуру регистрации приложения, и заявка на доступ была одобрена.
Пользователь Директа является прямым рекламодателем, рекламным агентством или клиентом рекламного агентства, которому агентство разрешило доступ к его данным.
Примечание.
- Если агентство предоставило клиенту доступ в веб-интерфейс только на чтение, то и через API клиент сможет только получать данные.
- Если агентство предоставило клиенту право на редактирование кампаний, то клиент сможет управлять своими кампаниями как в веб-интерфейсе, так и через API.
От имени пользователя создана хотя бы одна рекламная кампания в веб-интерфейсе.
Пользователь принял условия пользовательского соглашения на странице API сервиса Яндекс.Директ.
Пользователь разрешил приложению выполнять запросы от своего имени.

Приложение должно запросить у пользователя разрешение на доступ к его данным, получить авторизационный токен и указывать его в запросах.

Чтобы получить токен, приложение должно перенаправить пользователя на страницу запроса доступа. Пользователь авторизуется на Яндексе (под своим логином в Директе) и нажимает кнопку Подтвердить. Далее сервер Яндекса генерирует токен и передает его приложению.

Ограничение доступа по IP-адресу

tech.yandex.ru

Пишем Ruby gem для Yandex Direct API / Хабр

Очень хотелось изучить Ruby получше, а рабочего проекта не было. И я попробовал написать gem для работы с Yandex Direct API.

Причин было несколько. Среди них: Yandex Direct API очень типичен для Яндекса и современных REST-сервисов вообще. Если разобраться и преодолеть типичные ошибки, то можно легко и быстро написать аналоги для прочих API Яндекса (и не только). И ещё: у всех аналогов, которые мне удалось найти, были проблемы с поддержкой версий Директа: одни были заточены под 4, другие под новую 5, и поддержке units я нигде не нашёл.

Основная идея gem-а — раз в языке вроде Ruby или Python можно создавать новые методы и JSON-подобные объекты на лету, то методы интерфейс для доступа к REST-сервису могут повторять функции самого Rest-сервиса. Чтобы можно было писать так:

request = { "SelectionCriteria" => { "Types" => ["TEXT_CAMPAIGN"] }, "FieldNames" => ["Id", "Name"], "TextCampaignFieldNames" => ["BiddingStrategy"] } options = { token: Token } @direct = Ya::API::Direct::Client.new(options) json = direct.campaigns.get(request)

А вместо того, чтобы писать справку, отсылать пользователей к мануалам по указанному API.

Методы из старых версий вызывать, например, так:

json = direct.v4.GetCampaignsList

На тот случай, если вам не интересно читать, а хочется попробовать — готовый gem можно взять отсюда:

О получении omniauth-token из rails можно узнать из примера по twitter. А названия методов и процедура регистрации очень подробно расписана в документации от Яндекса.

Если интересны подробности — они дальше.

Начинаем разработку

Разумеется, в статье описан самый базовый опыт и самые простые вещи. Но она может быть полезна начинающим (вроде меня), как памятка по созданию типового gem-а. Собирать информацию по статьям, конечно, интересно, — но долго.

Наконец, может быть, что кому-то из читателей действительно надо по быстрому добавить поддержку Yandex Direct API в свой проект.

А ещё она будет полезна мне — в плане фидбека.

Проверочный скрипт

Для начала зарегистрируемся в Yandex Direct, создадим там тестовое приложение и получим для него временный Token.

Потом откроем справку по Yandex Direct API и поучимся вызывать методы. Как-нибудь так:

Для версии 5:

require "net/http" require "openssl" require "json" Token = "TOKEN" # Сюда пишем тестовый TOKEN. def send_api_request_v5(request_data) url = "https://%{api}.direct.yandex.com/json/v5/%{service}" % request_data uri = URI.parse(url) request = Net::HTTP::Post.new(uri.path, initheader = { 'Client-Login' => request_data[:login], 'Accept-Language' => "ru", 'Authorization' => "Bearer #{Token}" }) request.body = { "method" => request_data[:method], "params" => request_data[:params] }.to_json http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true http.verify_mode = OpenSSL::SSL::VERIFY_NONE response = http.request(request) if response.kind_of? Net::HTTPSuccess JSON.parse response.body else raise response.inspect end end p send_api_request_v5 api: "api-sandbox", login: "YOUR LOGIN HERE", service: "campaigns", method: "get", params: { "SelectionCriteria" => { "Types" => ["TEXT_CAMPAIGN"] }, "FieldNames" => ["Id", "Name"], "TextCampaignFieldNames" => ["BiddingStrategy"] }

Для версии 4 Live (Token подходит к обоим):

require "net/http" require "openssl" require "json" Token = "TOKEN" # Сюда пишем тестовый TOKEN. def send_api_request_v4(request_data) url = "https://%{api}.direct.yandex.com/%{version}/json/" % request_data uri = URI.parse(url) request = Net::HTTP::Post.new(uri.path) request.body = { "method" => request_data[:method], "param" => request_data[:params], "locale" => "ru", "token" => Token }.to_json http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true http.verify_mode = OpenSSL::SSL::VERIFY_NONE response = http.request(request) if response.kind_of? Net::HTTPSuccess JSON.parse(response.body) else raise response.inspect end end p send_api_request_v4 api: "api-sandbox", version: "live/v4", method: "GetCampaignsList", params: []

Эти скрипты уже годятся для отладки и быстрых тестовых запросов.

Но, как учит нас (мифический) человеко-месяц, скрипт для себя и библиотека для других — это два разных класса приложений. И чтобы передалать один в другой, предстоит попотеть.

Для начала надо было определиться с названием — простым и не занятым. И пришёл к выводу, что ya-api-direct — это то, что надо.

Во-первых, сама структура логична — и если появится, к примеру, ещё и ya-api-weather, то будет ясно, к чему он относится. Во-вторых, у меня всё-таки не официальный продукт от Яндекса, чтобы использовать торговую марку как префикс. К тому же, это намёк на ya.ru, где бережно хранится прежний лаконичный дизайн.

Создавать руками все папки немного лениво. Пусть за нас это сделает bundler:

bundle gem ya-api-direct

В качестве средства для UnitTest я указал minitest. Потом будет ясно, почему.

Теперь у нас есть папка, и в ней готовый для сборки gem. Его единственный недостаток в том, что он совершенно пуст.

Но сейчас мы это исправим.

Пишем тесты

UnitTest-ы невероятно полезны для выявления хитро спрятаных багов. Почти каждый программист, который всё-таки сподобился их написать и исправил попутно пару десятков багов, что затаились в исходниках, обещает себе, что будет их теперь писать всегда. Но всё равно не пишет.

В некоторых проектах (наверное, их пишут особенно неленивые программисты) есть одновременно и test и spec-тесты. Но в последних версиях minitest вдруг научился spec-интерфейсу, и я решил обойтись и одними spec-ами.

Так как интерфейс у нас онлайновый и, к тому же, за каждый запрос с нас списываются баллы, мы подделаем ответы от Yandex Direct API. Для этого нам потребуются хитрый gem webmock.

Добавляем в gems

group :test do gem 'rspec', '>= 2.14' gem 'rubocop', '>= 0.37' gem 'webmock' end

Обновляем, переименовываем папку test в spec. Так как я торопился, то тесты написал только для внешних интерфейсов.

require 'ya/api/direct' require 'minitest/autorun' require 'webmock/minitest' describe Ya::API::Direct::Client do Token = "TOKEN" # Не трогаем, т.к. API всё равно ненастоящий. before do @units = { just_used: 10, units_left: 20828, units_limit: 64000 } units_header = {"Units" => "%{just_used}/%{units_left}/%{units_limit}" % @units } @campaigns_get_body = { # Тут взятый из справки Yandex Direct API пример результата запроса } # Тут другие инициализации stub_request(:post, "https://api-sandbox.direct.yandex.ru/json/v5/campaigns") .with( headers: {'Accept'=>'*spec_*.rb').each { |file| require file} end task test: [:spec] task default: [:spec]

Теперь наши spec-и можно вызывать так:

rake test

Или даже:

rake

Правда, тестировать ему пока нечего.

Пишем gem

Сначала заполяем с информацией о gem-е (без этого bundle откажется запускаться). Потом пишем в gemspec, какие сторонние библиотеки будем использовать.

gem 'jruby-openssl', platforms: :jruby gem 'rake' gem 'yard' group :test do gem 'rspec', '>= 2.14' gem 'rubocop', '>= 0.37' gem 'webmock' gem 'yardstick' end

Делаем

bundle install

и отправляемся в lib создавать файлы.

Файлы у нас будут такие:

client.rb — внешний интерфейс
direct_service_base.rb — базовый сервис для работы с API
direct_service_v4.rb — сервис для работы с API 4 и 4 Live
direct_service_v5.rb — сервис для работы с API 5
gateway.rb — пересылает и обрабатывает сетевые запросыю=
url_helper.rb — всякие статические функции, которым не место в gateway.rb
constants.rb — список доступных методов Yandex DIrect API
exception.rb — исключение, чтобы ошибки API показывать
version.rb — служебный файл с настройками версии

Контроллеры для разных версий

Для начала создадим файл с константами, в который и запишем все функции из API.

contants.rb

module Ya module API module Direct API_V5 = { "Campaigns" => [ "add", "update", "delete", "suspend", "resume", "archive", "unarchive", "get" ], # и т.д. } API_V4 = [ "GetBalance", # и т.д. ] API_V4_LIVE = [ "CreateOrUpdateCampaign", # и т.д. ] end end end

Теперь создадим базовый сервис-обёртку, от которого мы унаследуем сервис для версий 4 и 5.

direct_service_base.rb

module Ya::API::Direct class DirectServiceBase attr_reader :method_items, :version def initialize(client, methods_data) @client = client @method_items = methods_data init_methods end protected def init_methods @method_items.each do |method| self.class.send :define_method, method do |params = {}| result = exec_request(method, params || {}) callback_by_result result result[:data] end end end def exec_request(method, request_body) client.gateway.request method, request_body, @version end def callback_by_result(result={}) end end end

В конструкторе он получает исходный клиент и список методов. А потом создаёт их внутри себя через :define_method.

А почему нам не обойтись методом respond_to_missing? (как до сих пор делают многие gem-ы)? Потому что он медленней и не такой удобный. И без того небыстрый интерпретатор попадает в него после исключения и проверки в is_respond_to_missing?.. К тому же, созданные таким образом методы попадают в результаты вызова methods, а это удобно для отладки.

Теперь создадим сервис для версий 4 и 4 Live.

direct_service_v4.rb

require "ya/api/direct/constants" require "ya/api/direct/direct_service_base" module Ya::API::Direct class DirectServiceV4 < DirectServiceBase def initialize(client, methods_data, version = :v4) super(client, methods_data) @version = version end def exec_request(method, request_body = {}) @client.gateway.request method, request_body, nil, (API_V4_LIVE.include?(method) ? :v4live : @version) end end end

В версии 5 сервер не просто отвечает на запросы пользователя, но ещё и сообщает, сколько баллов потрачено на последнем запросе, сколько осталось и сколько их было в текущей сессии всего. Наш сервис должен уметь их разбирать (но мы пока не написали, как он это сделает). Но мы заранее укажем, что он должен обновлять поля в основном клиентском классе.

direct_service_v5.rb

require "ya/api/direct/direct_service_base" module Ya::API::Direct class DirectServiceV5 < DirectServiceBase attr_reader :service, :service_url def initialize(client, service, methods_data) super(client, methods_data) @service = service @service_url = service.downcase @version = :v5 end def exec_request(method, request_body={}) @client.gateway.request method, request_body, @service_url, @version end def callback_by_result(result={}) if result.has_key? :units_data @client.update_units_data result[:units_data] end end end end

Кстати, вы заметили, что за вызов запроса отвечает какой-то загадочный gateway?

Gateway и UrlHelper

Класс Gateway обеспечивает запросы. В него переехала большая часть кода из нашего скрипта.gateway.rb

require "net/http" require "openssl" require "json" require "ya/api/direct/constants" require "ya/api/direct/url_helper" module Ya::API::Direct class Gateway # конструктор тоже есть def request(method, params, service = "", version = nil) ver = version || (service.nil? ? :v4 : :v5) url = UrlHelper.direct_api_url @config[:mode], ver, service header = generate_header ver body = generate_body method, params, ver uri = URI.parse url request = Net::HTTP::Post.new(uri.path, initheader = header) request.body = body.to_json http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true http.verify_mode = @config[:ssl] ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE response = http.request(request) if response.kind_of? Net::HTTPSuccess UrlHelper.parse_data response, ver else raise response.inspect end end # а чуть ниже объявлены generate_header и generate_body # они есть в исходниках, поэтому обрезаны end end

Стандартый Net::HTTP задействован, потому что прост как грабли. Вполне можно посылать запросы и из faraday. На ней и так работает OmniAuth (про который я расскажу ниже), так что лишними gem-ами приложение не обрастёт.

Наконец, UrlHelper заполняем статичными функциями, которые генерируют URL, разбирают данные и парсят Units (что несложно):

require "json" require "ya/api/direct/exception" module Ya::API::Direct RegExUnits = Regexp.new /(\d+)\/(\d+)\/(\d+)/ class UrlHelper def self.direct_api_url(mode = :sandbox, version = :v5, service = "") format = :json protocol = "https" api_prefixes = { sandbox: "api-sandbox", production: "api" } api_prefix = api_prefixes[mode || :sandbox] site = "%{api}.direct.yandex.ru" % {api: api_prefix} api_urls = { v4: { json: '%{protocol}://%{site}/v4/json', soap: '%{protocol}://%{site}/v4/soap', wsdl: '%{protocol}://%{site}/v4/wsdl', }, v4live: { json: '%{protocol}://%{site}/live/v4/json', soap: '%{protocol}://%{site}/live/v4/soap', wsdl: '%{protocol}://%{site}/live/v4/wsdl', }, v5: { json: '%{protocol}://%{site}/json/v5/%{service}', soap: '%{protocol}://%{site}/v5/%{service}', wsdl: '%{protocol}://%{site}/v5/%{service}?wsdl', } } api_urls[version][format] % { protocol: protocol, site: site, service: service } end def self.extract_response_units(response_header) matched = RegExUnits.match response_header["Units"] matched.nil? ? {} : { just_used: matched[1].to_i, units_left: matched[2].to_i, units_limit: matched[3].to_i } end private def self.parse_data(response, ver) response_body = JSON.parse(response.body) validate_response! response_body result = { data: response_body } if [:v5].include? ver result.merge!({ units_data: self.extract_response_units(response) }) end result end def self.validate_response!(response_body) if response_body.has_key? 'error' response_error = response_body['error'] raise Exception.new(response_error['error_detail'], response_error['error_string'], response_error['error_code']) end end end end

Если сервер вернул ошибку, мы кидаем Exception с её текстом.

Код выглядит самоочевидным и это весьма хорошо. Самоочевидный код легче поддерживать.

Client

Теперь нам нужно написать сам класс клиента, с которым взаимодействуют внешние интерфейсы. Так как большая часть функционала уже переехала во внутренние классы, то он будет очень коротким.

require "ya/api/direct/constants" require "ya/api/direct/gateway" require "ya/api/direct/direct_service_v4" require "ya/api/direct/direct_service_v5" require "ya/api/direct/exception" require 'time' module Ya::API::Direct AllowedAPIVersions = [:v5, :v4] class Client attr_reader :cache_timestamp, :units_data, :gateway, :v4, :v5 def initialize(config = {}) @config = { token: nil, app_id: nil, login: '', locale: 'en', mode: :sandbox, format: :json, cache: true, api: :v5, ssl: true }.merge(config) @units_data = { just_used: nil, units_left: nil, units_limit: nil } raise "Token can't be empty" if @config[:token].nil? raise "Allowed Yandex Direct API versions are #{AllowedVersions}" unless AllowedAPIVersions.include? @config[:api] @gateway = Ya::API::Direct::Gateway.new @config init_v4 init_v5 start_cache! if @config[:cache] yield self if block_given? end def update_units_data(units_data = {}) @units_data.merge! units_data end def start_cache! case @config[:api] when :v4 result = @gateway.request("GetChanges", {}, nil, :v4live) timestamp = result[:data]['data']['Timestamp'] when :v5 result = @gateway.request("checkDictionaries", {}, "changes", :v5) timestamp = result[:data]['result']['Timestamp'] update_units_data result[:units_data] end @cache_timestamp = Time.parse(timestamp) @cache_timestamp end private def init_v4 @v4 = DirectServiceV4.new self, (API_V4 + API_V4_LIVE) end def init_v5 @v5 = {} API_V5.each do |service, methods| service_item = DirectServiceV5.new(self, service, methods) service_key = service_item.service_url @v5[service_key] = service_item self.class.send :define_method, service_key do @v5[service_key] end end end end end

Методы версии 4 записываются в свойство v4, методы версии 5, сгруппированные по отдельным сервисам, становятся методами класса клиента через уже знакомую нам конструкцию. Теперь, когда мы вызываем client.campaigns.get Ruby сначала выполнит client.campaigns(), а потом вызовет у полученного сервиса метод get.

Последняя срока конструктора нужна, чтобы класс можно было использовать в конструкции do… end.

Сразу после инициализации же выполняет (если это указано в настройках) start_cache!, чтобы послать API команду на включение кэширования. Версия в настройках влияет только на это, из экземпляра класса можно вызывать методы обоих версий. Полученная дата будет доступна в свойстве cache_timestamp.

А в свойстве units_data будут лежать последние сведения по Units.

Также в проекте есть класс с настройками версии и исключения. С ними всё настолько понятно, что даже и сказать нечего. Класс с настройками версий и вовсе сгенерирован bundle вместе с проектом.

Ну а файле direct.rb нужно указать те классы, которые должны быть видны пользователю снаружи. В нашем случае это только класс клиента. Плюс версия и исключение (он они совсем служебные).

Компилируем и заливаем

Чтобы cкомпилировать gem, можно следовать мануалу с RubyGems.org (там ничего сложного). Или применить Mountable Engine из Rails.

А потом загружаем на rubygems — вдруг этот gem может быть полезен не только нам.

Как получить token из Ruby on Rails

Войти из Rails в Yandec API и получить токен — дело очень простое для любого разработчика… если не в первый раз.

Как мы уже узнали, для доступа к Direct API требуется токен. Из справки от Яндекса следует, что перед нами — старый добрый OAuth3, которым пользуется куча сервисов, включая Twitter и Facebook.

Для Ruby есть классический gem omniauth, от которого и наследуют реализации OAuth3 для различных сервисов. Уже реализован и omniauth-yandex. С ним мы и попытаемся разобраться.

Создадим новое rails приложение (добавлять в рабочие проекты будем после того, как научимся). Добавляем в Gemfile:

gem "omniauth-yandex"

И делаем bundle install.

А потом пользуемся любым мануалом по установке Omniauth-аутенфикации для rails. Вот пример для twitter. Переводить и пересказывать его, я думаю, не стоит — статья и так получилась огромная.

У меня описанный в статье пример заработал. Единственной поправкой было то, что я не стал писать в таблицу User дополнительные индексы, потому что их не поддерживает SQLite.

Правда, в статье не указано, где скрывается token. Но это совсем не секрет. В SessionController его можно будет получить через

request.env['omniauth.auth'].credentials.token

Только не забывайте — каждая такая аутенфикация генерирует token заново. И если вы потом попытаетесь использовать скрипты с прямым указанием token, то сервер будет говорить, что старый уже не подходит. Надо вернуться в настройки приложения Яндекса, снова указать отладочный callback URL (__https://oauth.yandex.ru/verification_code__), а затем заново сгенерировать token.

А ещё лучше — создать для статичного токена отдельное приложение, чтобы отлаживать не мешал.

Ссылки

habr.com

API Директа — Ограничения при работе с API Яндекс.Директа — Технологии Яндекса

Каждому рекламодателю предоставляется индивидуальный суточный лимит вызова торгов — ограничение на количество фраз, по которым можно получить результаты торгов. Этот лимит зависит от активности рекламных кампаний — количества показов и кликов и, соответственно, расходования средств.

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

Суточный лимит разделен на 24 часовых интервала и предоставляется по принципу скользящего окна. В текущем часовом интервале рекламодатель может потратить суточный лимит минус количество фраз, по которым были запрошены результаты торгов за предыдущие 23 интервала.

Время начала часового интервала может различаться для разных рекламодателей и не совпадать с началом астрономического часа.

Пример

Предположим, для рекламодателя суточный лимит запросов в торги составляет 1,5 млн. фраз, а интервалы начинаются в 00:18, 01:18, 02:18 и т. д.

Если с 12:18 предыдущего дня до 11:18 текущего дня рекламодатель получил результаты торгов по 1,4 млн. фраз, то с 11:18 до 12:18 он может получить результаты торгов по 100 тыс. фраз. В 12:18 остаток лимита снова перерассчитывается.

Получением результатов торгов являются следующие запросы к API:

вызов метода GetBanners или GetBanners (Live), если во входном параметре GetPhrases указано значение WithPrices;
вызов метода GetBannerPhrasesFilter, если параметр RequestPrices не задан или задано значение No;
вызов метода GetBannerPhrasesFilter (Live), если параметр FieldNames не задан или в массиве присутствует хотя бы одно из значений Prices, Max, Min, PremiumMax, PremiumMin, LowCTR, ContextLowCTR, Shows, Clicks, ContextShows, ContextClicks, CurrentOnSearch, LowCTRWarning, MinPrice, ContextCoverage, Coverage, AuctionBids.
вызов метода GetBannerPhrases или GetBannerPhrases (Live).

В перечисленных случаях ответ метода содержит HTTP-заголовок GetPhrasesLimit, в котором указано:

количество фраз, по которым получены результаты торгов при вызове метода;
доступный остаток суточного лимита;
суточный лимит;
количество секунд до начала следующего часового интервала.

Пример: GetPhrasesLimit: 1/23553853/23553900/1922 secs

tech.yandex.ru

API Метрики — Директ — Технологии Яндекса

ym:ad:directOrder	Кампания Яндекс.Директа	!., !=, =., ==	Рекламная кампания Яндекс.Директа.	ym:ad:directOrderName	2015-06-17
ym:ad:directBannerGroup	Группа объявлений	!., !=, <, <=, =., ==, >, >=	Группа объявлений Яндекс.Директа.	ym:ad:directBannerGroupName	2015-06-17
ym:ad:directBanner	Объявление Яндекс.Директа	!, !., !=, !@, !~, <, <=, =, =., ==, =@, =~, >, >=		ym:ad:directBannerName	2015-06-17
ym:ad:directPhraseOrCond	Условие показа объявления	!., !=, =., ==	Условие показа объявления. Условием могут быть либо ключевые слова, либо условие ретаргетинга.	ym:ad:directPhraseOrCondName	2015-06-17
ym:ad:directPlatformType	Тип площадки	!., !=, =., ==	Тип рекламной площадки Яндекс.Директа.	ym:ad:directPlatformTypeName	2015-06-17
ym:ad:directPlatform	Площадка	!., !=, =., ==	Рекламная площадка Яндекс.Директа.	ym:ad:directPlatformName	2009-11-18
ym:ad:directSearchPhrase	Поисковая фраза (Директ)	!, !., !=, !@, !~, <, <=, =, =., ==, =@, =~, >, >=	Поисковая фраза последнего перехода по объявлению Яндекс.Директа.		2015-06-17
ym:ad:directConditionType	Тип условия показа объявления	!., !=, =., ==	Тип условия показа объявления.	ym:ad:directConditionTypeName	2015-06-17
ym:ad:currency	Валюта	!, !., !=, !@, !~, <, <=, =, =., ==, =@, =~, >, >=	Валюта, установленная в Яндекс.Директе для рекламной кампании.	ym:ad:currencyName	2015-06-17
ym:ad:displayCampaign	Номер заказа Яндекс.Дисплея	!., !=, =., ==			2015-08-26

tech.yandex.ru

API Директа — Соответствие методов — Технологии Яндекса

ArchiveBanners (Live)	Сервис Ads, метод archive
CreateOrUpdateBanners (Live)	Функциональность разделена между следующими методами: Создание групп объявлений — сервис AdGroups, метод add Редактирование групп объявлений — сервис AdGroups, метод update Создание объявлений — сервис Ads, метод add Редактирование объявлений — сервис Ads, метод update Создание и редактирование ключевых фраз — сервис Keywords, метод add Назначение ставок — сервис Bids, методы set и setAuto Добавление визиток — сервис VCards, метод add, привязка визиток к объявлению — сервис Ads, методы add, update Добавление набора быстрых ссылок — сервис Sitelinks, метод add, привязка набора быстрых ссылок к объявлению — сервис Ads, методы add, update
DeleteBanners (Live)	Сервис Ads, метод delete
GetBanners (Live)	Функциональность разделена между следующими методами: Получение параметров групп объявлений — сервис AdGroups, метод get Получение объявлений — сервис Ads, метод get Получение ключевых фраз — сервис Keywords, метод get Получение ставок — сервис Bids, метод get Получение визитки — сервис VCards, метод get Получение быстрых ссылок — сервис Sitelinks, метод get
GetBannerPhrases (Live), GetBannerPhrasesFilter (Live)	Функциональность разделена между следующими методами: Получение ключевых фраз — сервис Keywords, метод get Получение ставок — сервис Bids, метод get
ModerateBanners (Live)	Сервис Ads, метод moderate
ResumeBanners (Live)	Сервис Ads, метод resume
StopBanners (Live)	Сервис Ads, метод suspend
UnArchiveBanners (Live)	Сервис Ads, метод unarchive
Keyword (Live)	Сервис Keywords, методы suspend, resume, get
SetAutoPrice (Live)	Сервис Bids, метод setAuto
UpdatePrices (Live)	Сервис Bids, метод set