如何通过日期范围筛选Google Ads广告系列的指定周期指标数据？

use Google\Ads\GoogleAds\V15\Common\DateRange;
use Google\Ads\GoogleAds\V15\Services\SearchGoogleAdsStreamRequest;

/**
 * Runs the example.
 *
 * @param GoogleAdsClient $googleAdsClient the Google Ads API client
 * @param int $customerId the customer ID
 * @param string|null $startDate 起始日期（格式：Ymd，如20240501）
 * @param string|null $endDate 结束日期（格式：Ymd，如20240507）
 */
public static function getGoogleAdCampaigns(GoogleAdsClient $googleAdsClient, int $customerId, ?string $startDate = null, ?string $endDate = null)
{
    $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
    
    // 未传入日期时，自动计算上周的周一到周日作为默认范围
    if (is_null($startDate) || is_null($endDate)) {
        $lastWeekStart = (new DateTime())->modify('last week monday')->format('Ymd');
        $lastWeekEnd = (new DateTime())->modify('last week sunday')->format('Ymd');
        $startDate = $startDate ?? $lastWeekStart;
        $endDate = $endDate ?? $lastWeekEnd;
    }

    // 查询广告系列及指定指标
    $query = "SELECT campaign.id, campaign.name, campaign.status, metrics.impressions, metrics.clicks, metrics.conversions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.start_date, campaign.end_date FROM campaign WHERE campaign.status = 'ENABLED'";

    // 构建带日期范围的搜索请求
    $request = SearchGoogleAdsStreamRequest::build(
        $customerId,
        $query,
        ['date_ranges' => [DateRange::build($startDate, $endDate)]]
    );

    // 发起流式搜索请求
    /** @var GoogleAdsServerStreamDecorator $stream */
    $stream = $googleAdsServiceClient->searchStream($request);

    // 收集广告系列数据
    $campaigns = [];
    foreach ($stream->iterateAllElements() as $googleAdsRow) {
        /** @var GoogleAdsRow $googleAdsRow */
        $campaigns[] = [
            'id' => $googleAdsRow->getCampaign()->getId(),
            'name' => $googleAdsRow->getCampaign()->getName(),
            'start_date' => $googleAdsRow->getCampaign()->getStartDate(),
            'end_date' => $googleAdsRow->getCampaign()->getEndDate(),
            'status' => $googleAdsRow->getCampaign()->getStatus(),
            'impressions' => $googleAdsRow->getMetrics()->getImpressions(),
            'clicks' => $googleAdsRow->getMetrics()->getClicks(),
            'conversions' => $googleAdsRow->getMetrics()->getConversions(),
            'ctr' => $googleAdsRow->getMetrics()->getCtr(),
            'average_cpc' => $googleAdsRow->getMetrics()->getAverageCpc(),
            'cost_micros' => $googleAdsRow->getMetrics()->getCostMicros(),
        ];
    }

    echo json_encode($campaigns);
    exit();
}

• 新增日期参数：函数添加可选的$startDate和$endDate参数，支持自定义日期范围，格式需为Ymd（如20240501）。
• 自动计算上周日期：未传入日期时，自动生成上一周的周一到周日作为默认统计范围，可根据需求调整日期逻辑（比如改为上周日到本周六）。
• 添加日期范围过滤：通过SearchGoogleAdsStreamRequest的date_ranges参数指定指标的统计区间，这是Google Ads API限定指标时间范围的标准方式，确保返回的点击量、展示量等数据仅对应指定日期。
• 导入必要类：新增DateRange类导入，用于构建日期范围对象。

1. 获取上周数据：直接调用函数即可，无需传入日期参数：

getGoogleAdCampaigns($googleAdsClient, 123456789);

2. 自定义日期范围：传入指定的起始和结束日期：

getGoogleAdCampaigns($googleAdsClient, 123456789, '20240501', '20240507');

内容的提问来源于stack exchange，提问作者Varinder Sohal