Yandex.Direct API PHP Client

Библиотека для работы с API Директа.

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

NOTE: Библиотека совместима только с 64-битной версией PHP.

Установка

Проще всего установить с помощью менеджера пакетов - composer.

$ composer require biplane/yandex-direct

Дополнительно для работы с сервисом Reports

Для работы с сервисом Reports нужен HTTP-клиент, совместимый с PSR-18. В зависимостях не указана какая-то конкретная реализация. Вместо этого используется php-http/discovery для поиска подходящей реализации среди установленных пакетов, как стратегия по умолчанию.

Примеры использования

Получение данных по объявлениям

Данный пример отражает взаимодействие с сервисом Ads для получения списка объявлений.

<?php

use Biplane\YandexDirect\ApiServiceFactory;
use Biplane\YandexDirect\Api\V5\Ads;
use Biplane\YandexDirect\Api\V5\Contract;
use Biplane\YandexDirect\ConfigBuilder;

$serviceFactory = new ApiServiceFactory();

$config = ConfigBuilder::create()
    ->setAccessToken('<INSERT_ACCESS_TOKEN>')
    ->setClientLogin('agrom')
    ->setLocale('ru')
    ->getConfig();
$service = $serviceFactory->createService($config, Ads::class);

$campaignsIds = [123];

$criteria = Contract\AdsSelectionCriteria::create()
    ->setCampaignIds($campaignsIds)
    ->setStates([
        Contract\StateEnum::ON,
    ]);
$request = Contract\GetAdsRequest::create()
    ->setSelectionCriteria($criteria)
    ->setFieldNames([
        Contract\AdFieldEnum::AD_CATEGORIES,
        Contract\AdFieldEnum::AGE_LABEL,
        Contract\AdFieldEnum::AD_GROUP_ID,
        Contract\AdFieldEnum::ID,
        Contract\AdFieldEnum::STATUS,
    ]);

$response = $service->get($request);

foreach ($response->getAds() ?? [] as $item) {
    // Здесь $item будет являться экземпляром `Biplane\YandexDirect\Api\V5\Contract\AdGetItem`
    // Например, получение информации о возрастной метке:
    // $item->getAgeLabel();
}

Получение отчета

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

use Biplane\YandexDirect\Api\V5\Reports;
use Biplane\YandexDirect\ConfigBuilder;
use Biplane\YandexDirect\ReportServiceFactory;

$serviceFactory = new ReportServiceFactory();

$config = ConfigBuilder::create()
    ->setAccessToken('<INSERT_ACCESS_TOKEN>')
    ->setClientLogin('agrom')
    ->setLocale('ru')
    ->getConfig();
$service = $serviceFactory->createService($config);

$reportDefinition = Reports\ReportDefinition::create()
    ->setReportName('demo')
    ->setReportType(Reports\ReportTypeEnum::CAMPAIGN_PERFORMANCE_REPORT)
    ->setDateRangeType(Reports\DateRangeTypeEnum::LAST_7_DAYS)
    ->setFieldNames([
        Reports\FieldEnum::CAMPAIGN_ID,
        Reports\FieldEnum::CAMPAIGN_NAME,
        Reports\FieldEnum::IMPRESSIONS,
        Reports\FieldEnum::CLICKS,
        Reports\FieldEnum::COST,
    ])
    ->setIncludeVAT(false);

$request = Reports\ReportRequestBuilder::create()
    ->setReportDefinition($reportDefinition)
    ->returnMoneyInMicros(false)
    ->skipReportHeader(true)
    ->getReportRequest();

$result = $service->getReady($request);

$result->saveToFile('/path/to/file.tsv');

Логирование

Для логирования запросов к API можно реализовать интерфейс Biplane\YandexDirect\Log\SoapLogger. Либо использовать адаптер для psr/log:

use Biplane\YandexDirect\ApiServiceFactoryBuilder;
use Biplane\YandexDirect\Log\SoapLogger\PsrLogger;

$serviceFactory = ApiServiceFactoryBuilder::create()
    ->setLogger(new PsrLogger($psrLogger))
    ->getFactory();

// ...

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

Response	Log level
OK	`DEBUG`
Error	`ERROR`

Поддерживаемые сервисы API

Сервис	Документация
`V4\YandexAPIService`	API Live 4 doc
`V5\AdExtensions`	Doc
`V5\AdGroups`	Doc
`V5\AdImages`	Doc
`V5\Ads`	Doc
`V5\AgencyClients`	Doc
`V5\AudienceTargets`	Doc
`V5\BidModifiers`	Doc
`V5\Bids`	Doc
`V5\Campaigns`	Doc
`V5\Changes`	Doc
`V5\Clients`	Doc
`V5\Dictionaries`	Doc
`V5\DynamicTextAdTargets`	Doc
`V5\Feeds`	Doc
`V5\KeywordBids`	Doc
`V5\Keywords`	Doc
`V5\KeywordsResearch`	Doc
`V5\Leads`	Doc
`V5\NegativeKeywordSharedSets`	Doc
`V5\RetargetingLists`	Doc
`V5\Sitelinks`	Doc
`V5\SmartAdTargets`	Doc
`V5\Strategies`	Doc
`V5\TurboPages`	Doc
`V5\VCards`	Doc
`V5\Reports`	Doc

License

This package is licensed using the MIT License.

biplane / yandex-direct