تقسیم بندی

بخش بندی، که در رابط کاربری Google Ads به عنوان یک منوی جداگانه موجود است، می تواند در Google Ads API فقط با افزودن فیلد مناسب به یک پرس و جو پیاده سازی شود. برای مثال، افزودن segments.device به یک جستار، منجر به یک گزارش با یک ردیف برای هر ترکیبی از دستگاه و منبع مشخص شده در عبارت FROM می‌شود و مقادیر آماری (نمایش‌ها، کلیک‌ها، تبدیل‌ها و غیره) بین آنها تقسیم می‌شود.

در حالی که در رابط کاربری Google Ads فقط می توان از یک بخش در یک زمان استفاده کرد، با API می توانید چندین بخش را در یک جستجو مشخص کنید.

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions
FROM campaign

نتایج ارسال این درخواست به GoogleAdsService.SearchStream چیزی شبیه به این رشته JSON خواهد بود:

{
  "results":[
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"10922"
      },
      "segments":{
        "device":"MOBILE"
      }
    },
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"28297"
      },
      "segments":{
        "device":"DESKTOP"
      }
    },
    ...
  ]
}

توجه داشته باشید که در نتیجه نمونه بالا، ویژگی های شی اول و دوم از جمله نام منبع یکسان است. برداشت ها بر اساس دستگاه تقسیم می شوند و بنابراین می توان دو یا چند شی را برای یک کمپین بازگرداند.

تقسیم بندی ضمنی

هر گزارش در ابتدا توسط منبع مشخص شده در عبارت FROM تقسیم بندی می شود. فیلد resource_name منبع در عبارت FROM برگردانده می‌شود و معیارها توسط آن بخش‌بندی می‌شوند، حتی زمانی که قسمت resource_name به صراحت در پرس و جو گنجانده نشده باشد. به عنوان مثال، وقتی ad_group به‌عنوان منبع در عبارت FROM مشخص می‌کنید، ad_group.resource_name به‌طور خودکار برگردانده می‌شود و معیارها به طور ضمنی در سطح ad_group آن را تقسیم‌بندی می‌کنند.

بنابراین برای این پرس و جو،

SELECT metrics.impressions
FROM ad_group

شما یک رشته JSON مانند این دریافت خواهید کرد:

{
  "results":[
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/2222222222"
      },
      "metrics":{
        "impressions":"237"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/33333333333"
      },
      "metrics":{
        "impressions":"15"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/44444444444"
      },
      "metrics":{
        "impressions":"0"
      }
    }
  ]
}

توجه داشته باشید که قسمت resource_name adGroup همیشه برگردانده می شود زیرا ad_group به عنوان منبع در عبارت FROM مشخص شده است.

فیلدهای بخش قابل انتخاب

همه فیلدهای بخش برای یک منبع معین در عبارت FROM قابل انتخاب نیستند. به عنوان مثال، ما به پرس و جو از منبع ad_group ادامه می دهیم. برای اینکه یک قسمت بخش از منبع ad_group قابل انتخاب باشد، باید آن قسمت در لیست Segments for ad_group وجود داشته باشد. لیست Segments قسمت زرد رنگ جدول فیلدهای موجود در صفحه ابرداده منبع ad_group است.

منابع بخش

هنگام انتخاب از برخی منابع، ممکن است این گزینه را داشته باشید که به طور ضمنی به منابع مرتبط با انتخاب فیلدهای آنها در کنار فیلدهای منبع در عبارت FROM بپیوندید. این منابع مرتبط را می توان در فهرست Attributed Resources در منبع موجود در صفحه فراداده بند FROM یافت. در مورد منبع ad_group ، خواهید دید که می توانید فیلدهایی را نیز از منبع campaign انتخاب کنید. فیلد resource_name هر Attributed Resources با حداقل 1 فیلد در عبارت SELECT به طور خودکار بازگردانده می شود، حتی زمانی که قسمت resource_name به صراحت در پرس و جو گنجانده نشده باشد.

مشابه انتخاب فیلدهای Attributed Resource ، می‌توانید قسمت‌های Segmenting Resource را نیز انتخاب کنید. اگر منبع معینی دارای فهرست Segmenting Resources در صفحه ابرداده خود باشد، انتخاب فیلدها از یکی از منابع فهرست‌شده باعث می‌شود که پرس و جو توسط resource_name برگشتی آن Segmenting Resource بخش‌بندی شود. به عنوان مثال، متوجه خواهید شد که منبع campaign به عنوان یک Segmenting Resource برای منبع campaign_budget فهرست شده است. انتخاب هر فیلد کمپین، مانند campaign.name ، از منبع campaign_budget نه تنها باعث می‌شود که فیلد campaign.name برگردانده شود، بلکه باعث می‌شود که فیلد campaign.resource_name برگردانده شده و در آن بخش‌بندی شود.

قابلیت انتخاب بین بخش ها و معیارها

ممکن است یک قسمت بخش معین با برخی از فیلدهای بخش دیگر یا با برخی از فیلدهای سنجه سازگار نباشد. برای تشخیص اینکه کدام قسمت‌ها با یکدیگر سازگار هستند، می‌توانید فهرست selectable_with از بخش‌های موجود در عبارت SELECT را بررسی کنید.

در مورد منبع ad_group ، بیش از 50 بخش موجود است که می توانید انتخاب کنید. با این حال، لیست selectable_with برای segments.hotel_check_in_date مجموعه بسیار کوچکتری از بخش های سازگار است. این بدان معناست که اگر قسمت segments.hotel_check_in_date را به بند SELECT اضافه کنید، بخش‌های موجودی را که برای انتخاب باقی گذاشته‌اید به تقاطع این دو لیست محدود می‌کنید.

هنگام افزودن برخی از بخش‌ها، ممکن است معیارهای موجود در ردیف خلاصه کاهش یابد

وقتی segments.keyword.info.match_type با FROM ad_group_ad به یک جستار اضافه می‌شود، آن بخش به درخواست می‌گوید فقط ردیف‌هایی از داده‌ها را دریافت کند که دارای کلمات کلیدی هستند و هر ردیفی را که با کلمه کلیدی مرتبط نیست حذف کند. در این مورد، معیارها کمتر خواهد بود زیرا هر معیار غیرکلیدی را حذف می کند.

قوانین برای بخش ها در عبارت WHERE

هنگامی که یک بخش در عبارت WHERE قرار دارد، باید در عبارت SELECT نیز باشد. استثناء این قاعده، بخش‌های تاریخ زیر هستند که به آن‌ها بخش‌های اصلی تاریخ گفته می‌شود:

• segments.date
• segments.week
• segments.month
• segments.quarter
• segments.year

قوانین مربوط به فیلدهای بخش اصلی تاریخ

بخش‌های segments.date ، segments.week ، segments.month ، segments.quarter و segments.year به شرح زیر عمل می‌کنند:

• این بخش‌ها را می‌توان در عبارت WHERE بدون ظاهر شدن در عبارت SELECT فیلتر کرد.

• اگر هر یک از این بخش‌ها در بند SELECT باشد، یک محدوده تاریخ محدود متشکل از بخش‌های تاریخ اصلی باید در عبارت WHERE مشخص شود (لازم نیست بخش‌های تاریخ همان‌هایی باشند که در SELECT مشخص شده‌اند).

نمونه ها

SELECT
  campaign.name,
  metrics.clicks,
  segments.date
FROM campaign

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
WHERE segments.date > '2024-01-01'
  AND segments.date < '2024-02-01'

SELECT
  campaign.name,
  metrics.clicks,
  segments.date
FROM campaign
WHERE segments.date > '2024-01-01'
  AND segments.date < '2024-02-01'

SELECT
  campaign.name,
  metrics.clicks,
  segments.month
FROM campaign
WHERE segments.date > '2024-01-01'
  AND segments.date < '2024-02-01'

SELECT
  campaign.name,
  metrics.clicks,
  segments.quarter,
  segments.month
FROM campaign
WHERE segments.year > 2019
  AND segments.year < 2024

search_term_view

توجه داشته باشید که برای منبع search_term_view ، به طور ضمنی بر اساس گروه تبلیغات، نه فقط یک عبارت جستجو، تقسیم بندی می شود، همانطور که در ساختار نام منبع آن منعکس می شود، که شامل گروه تبلیغات نیز می شود. بنابراین، تعدادی ردیف به ظاهر تکراری با همان عبارات جستجویی که در نتایج شما ظاهر می‌شوند، دریافت خواهید کرد، در حالی که در واقع، ردیف‌ها متعلق به یک گروه تبلیغاتی متفاوت هستند:

{
  "results":[
    {
      "searchTermView":{
        "resourceName":"customers/1234567890/searchTermViews/111111111~2222222222~Z29vZ2xlIHBob3RvcyBpb3M",
        "searchTerm":"google photos"
      },
      "metrics":{
        "impressions":"3"
      },
      "segments":{
        "date":"2024-06-15"
      }
    },
    {
      "searchTermView":{
        "resourceName":"customers/1234567890/searchTermViews/111111111~33333333333~Z29vZ2xlIHBob3RvcyBpb3M",
        "searchTerm":"google photos"
      },
      "metrics":{
        "impressions":"2"
      },
      "segments":{
        "date":"2024-06-15"
      }
    }
  ]
}

اگرچه به نظر می رسد دو شیء برگشتی در این مثال تکراری هستند، نام منابع آنها در واقع متفاوت است، به ویژه در قسمت "گروه تبلیغات". این بدان معناست که عبارت جستجوی "عکس‌های گوگل" به دو گروه تبلیغاتی (ID 2222222222 و 33333333333 ) در همان تاریخ (15/06/2024) نسبت داده می‌شود. بنابراین، می‌توان نتیجه گرفت که API همانطور که در نظر گرفته شده بود کار می‌کرد و در این مورد اشیاء تکراری را برنمی‌گرداند.