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.