Skip to content

biplane/yandex-direct

Repository files navigation

Yandex.Direct API PHP Client

Package version Build Status License

Библиотека для работы с 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.