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 будут записываться в журнал, но уровень логирования будет определяться ответом, успех или ошибка.

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

License

This package is licensed using the MIT License.