README

用于操作 API Директа 的库。

交互格式： SOAP

注意：此库仅与 64 位 PHP 版本兼容。

安装

最简单的安装方法是使用包管理器 - composer。

$ composer require biplane/yandex-direct

关于 Reports 服务的附加信息

为了使用 Reports 服务，需要一个与 PSR-18 兼容的 HTTP 客户端。依赖项中没有指定具体的实现。相反，使用 php-http/discovery 来在已安装的包中搜索合适的实现，这是默认的策略。

使用示例

获取广告数据

此示例反映与 Ads 服务（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 服务

许可证

本软件包使用 MIT 许可证授权。