Компонент ServiceAPI

Компонент ServiceAPI представляет из себя коллекции различных API, предназначенных для работы со сторонними сервисами.

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

$api = CMS::component('ServiceAPI')->api('my_api');

Метод возвращает объект Component.ServiceAPI.App.Collection, содержащий в себе коллекцию api зарегистрированных в компоненте.

Для регистрации своего api нужно использовать метод register_api($name, $class) компонента. Параметрами метода являются:

• $name - имя, под которым будет зарегистрировано api.
• $class - имя модуля api.

После регистрации добавленное api будет доступно в коллекции по имени.

В компоненте реализованы обертки для API:

• direct - api по работе с объявлениями в Яндекс Директ.
• adwords - api по работе с объявлениями в Google Adwords.

Component.ServiceAPI.API.Direct, Component.ServiceAPI.API.Adwords

Данные классы являются обертками над API Яндекс Директа и Google Adwords и предоставляют простые методы для работы с объявлениями.

Доступные методы

• connect() - метод для создания соединения со сторонним сервисом для работы с api. Перед началом работы необходимо создать новое соединение.
• Параметры для Директа:
• $login - логин аккаунта в Директе.
• $token - токен приложения, выдается при регистрации приложения в Яндексе.
• $app_id - id приложения.
• $debug - если указан данный параметр, то все запросы будут перенаправлены в Песочницу Яндекса.
• Параметры для Google Adwrods:
• $developer_token - токен разработчика, получается при регистрации приложения в Google.
• $user_agent - имя приложения.
• $client_customer_id - id клиента в Google,
• $oauth2_info - массив параметров oauth-авторизации вида array( 'client_id' => 'id клиента oauth', 'client_secret' => 'секретный ключ', 'refresh_token' => 'refresh token', ).
• $debug - если параметр указан, то будут собираться все виды логов, в противном случае только ошибки.

• get_companies($login) - метод возвращает кампании. Если в Директе аккаунт, через который производится доступ, является агенством, то необходимо передать логин клиента, чьи кампании необходимо получить. В ответ возвращается массив следующего вида:

array(
    0 => array(
	    'id' => 'Номер кампании',
	    'name' => 'Имя кампании',
	    'status' => 'Статус кампании: ENABLED - активна, PAUSED - остановлена'
	    'start_date' => 'Дата старта кампании'
	),
)

• get_adverts($company_id, array $advert_ids = array()) - метод возвращает список объявлений кампании. Параметром является номер кампании, объявления которой необходимо получить. В ответ возвращается массив следующего вида:

array(
    0 => array(
	'id' => 'Номер объявления',
	'title' => 'Заголовок',
	'description1' => 'текст объявления',
	'description2' => 'текст объявления, строка 2 - только для adwords',
	'url' => 'целевой url',
	'display_url' => 'отображаемый урл',
	'status' => 'Статус объявления: ENABLED - активна, PAUSED - остановлена',
	'geo' => 'Только для директа, код региона показа объявления',
	'contact_info' => 'Только для директа, Объект ContactInfo с контактными данными рекламодателя (визитка), см https://tech.yandex.ru/direct/doc/dg-v4/reference/GetBanners-docpage/',
	'shows' => 'кол-во показов объявления',
	'clicks' => 'кол-во кликов по объявлению',
	'ctr' => 'ЦТР',
	'keywords' => array(
	     	0 => array(
		    'id' => 'ID ключевого слова',
	            'title' => 'Заголовок ключевика',
	)
    ),
),

• get_advert($company_id, $advert_id) - Возвращает одно объявление из кампании. На вход ожидает 2 параметра: номер кампании и номер объявления в этой кампании, которые необходимо получить
• stop_advert($company_id, $advert_id) - отключает показ объявления.
• resume_advert($company_id, $advert_id) - включает показ объявления.
• delete_advert($company_id, $advert_id) - удаляет объявление.
• insert_advert($company_id, $params) - добавляет новое объявление в кампании, $params должен содержать структуру, аналогичную тому, что возвращает метод get_advert().
• update_advert($company_id, $advert_id, $params) - обновляет объявление, $params должен содержать структуру, аналогичную тому, что возвращает метод get_advert().
• stop_company($company_id) - останавливает все кампании.
• resume_company($company_id) - возобновляет показ кампании.