گزارش های جستجو را در Search Ads 360 Reporting API ایجاد کنید

برای یادگیری نحوه ایجاد گزارش‌های جستجو در API گزارش‌دهی Search Ads 360، بخش‌های زیر را مطالعه کنید.

سرویس جستجو

API گزارش‌دهی تبلیغات جستجو ۳۶۰، سرویس ویژه‌ای برای جستجو و گزارش‌گیری ارائه می‌دهد.

SearchAds360Service یک سرویس بازیابی و گزارش‌دهی یکپارچه اشیاء است که دو روش جستجو ارائه می‌دهد: SearchStream و Search . جستجوها در یک رشته پرس‌وجو که به زبان پرس‌وجوی Search Ads 360 نوشته شده است، ارسال می‌شوند. می‌توانید پرس‌وجوها را برای موارد زیر تعریف کنید:

  • بازیابی ویژگی‌های خاص اشیاء.
  • معیارهای عملکرد را برای اشیاء بر اساس محدوده تاریخ بازیابی کنید.
  • اشیاء را بر اساس ویژگی‌هایشان مرتب کنید.
  • نتایج خود را با استفاده از شرط‌هایی که مشخص می‌کنند کدام اشیاء را برگردانید، فیلتر کنید
  • تعداد اشیاء برگشتی را محدود کنید.

هر دو روش جستجو، تمام ردیف‌هایی را که با پرس‌وجوی شما مطابقت دارند، برمی‌گردانند. برای مثال، وقتی campaign.id ، campaign.name و metrics.clicks را بازیابی می‌کنید، API یک SearchAds360Row را برمی‌گرداند که شامل یک شیء کمپین با فیلدهای id و name تنظیم شده آن و یک شیء metrics با فیلد clicks تنظیم شده آن است.

روش‌های جستجو

SearchStream

صرف نظر از اندازه گزارش، یک درخواست واحد ارسال می‌کند و یک اتصال پایدار با API گزارش‌دهی Search Ads 360 آغاز می‌کند.

  • بسته‌های داده بلافاصله شروع به دانلود می‌کنند و کل نتیجه در یک بافر داده ذخیره می‌شود.
  • کد شما می‌تواند بدون نیاز به انتظار برای اتمام کل جریان، شروع به خواندن داده‌های بافر شده کند.
Search

چندین درخواست صفحه‌بندی‌شده برای دانلود کل گزارش ارسال می‌کند.

SearchStream معمولاً عملکرد بهتری ارائه می‌دهد زیرا زمان رفت و برگشت شبکه مورد نیاز برای درخواست صفحات جداگانه را حذف می‌کند. ما استفاده از SearchStream را برای همه گزارش‌های بیش از 10،000 ردیف توصیه می‌کنیم. هیچ تفاوت عملکردی قابل توجهی بین روش‌ها برای گزارش‌های کوچکتر (<10،000 ردیف) وجود ندارد.

روشی که استفاده می‌کنید تاثیری بر سهمیه‌ها و محدودیت‌های API شما ندارد: یک پرس‌وجو یا گزارش واحد، صرف نظر از اینکه نتایج صفحه‌بندی شده یا پخش شده باشند، به عنوان یک عملیات محسوب می‌شود.

نمونه عبارت جستجو

این نمونه کوئری، داده‌های عملکرد یک حساب کاربری را برای 30 روز گذشته بر اساس کمپین و تقسیم‌بندی شده بر اساس دستگاه، برمی‌گرداند:

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

درخواستی بدهید

برای صدور درخواست، باید یک customer_id و یک رشته query را به رابط‌های SearchAds360Service.SearchStream یا SearchAds360Service.Search ارسال کنید.

این درخواست شامل یک HTTP POST به سرور API گزارش‌دهی تبلیغات جستجو ۳۶۰ در یکی از URLهای زیر است:

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search

در اینجا یک مثال کامل از تعریف گزارش برای searchStream که در یک درخواست HTTP POST محصور شده است، آورده شده است:

POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1
Host: searchads360.googleapis.com
User-Agent: curl
Content-Type: application/json
Accept: application/json
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]

Parameters:
{
  "query" : "SELECT campaign.name, campaign.status, segments.device,
                    metrics.impressions, metrics.clicks, metrics.ctr,
                    metrics.average_cpc, metrics.cost_micros
            FROM campaign
            WHERE segments.date DURING LAST_30_DAYS"
}

پردازش یک پاسخ

SearchAds360Service فهرستی از اشیاء SearchAds360Row را برمی‌گرداند.

هر SearchAds360Row نشان دهنده یک شیء است که توسط پرس و جو برگردانده شده است. هر شیء شامل مجموعه‌ای از ویژگی‌ها است که بر اساس فیلدهای درخواست شده در عبارت SELECT پرس و جو پر می‌شوند. ویژگی‌هایی که در عبارت SELECT گنجانده نشده‌اند، در اشیاء موجود در پاسخ پر نمی‌شوند.

برای مثال، کوئری زیر هر شیء SearchAds360Row را فقط با campaign.id ، campaign.name و campaign.status پر می‌کند. سایر ویژگی‌ها، مانند campaign.engine_id یا campaign.bidding_strategy_type ، حذف می‌شوند.

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign

مستندات مرجع

بخش مرجع شامل تمام اطلاعات مورد نیاز برای استفاده صحیح از هر مصنوع است. برای هر منبع، مثلاً ad_group و campaign ، یک صفحه وجود دارد. صفحات segments و metrics ، تمام فیلدهای بخش‌ها و معیارهای موجود را فهرست می‌کنند.

برخی از منابع، بخش‌ها و معیارها با هم سازگار نیستند و نمی‌توان آنها را با هم استفاده کرد، در حالی که برخی دیگر کاملاً سازگار هستند و مکمل یکدیگرند. هر صفحه منبع شامل اطلاعات زیر (در صورت وجود و مناسب بودن) و موارد دیگر است:

منابع منتسب

برای برخی منابع، ممکن است این گزینه را داشته باشید که با انتخاب فیلدهای منابع مرتبط به همراه فیلدهای منبع در عبارت FROM خود، به طور ضمنی آنها را به هم متصل کنید. به عنوان مثال، منبع campaign یک منبع نسبت داده شده به منبع ad_group است. این بدان معناست که می‌توانید فیلدهایی مانند campaign.id و campaign.bidding_strategy_type را هنگام استفاده از ad_group در عبارت FROM خود در کوئری خود بگنجانید.

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

ستون فیلدهای منابع

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

ستون بخش‌ها

همه فیلدهای سگمنت با یک منبع مشخص قابل انتخاب نیستند.

ستون Segments فیلدهای segments را که می‌توانید در همان عبارت SELECT به عنوان فیلدهای منبع استفاده کنید، فهرست می‌کند. هر فیلد به جزئیات کامل در مورد فیلد، از جمله توضیحات، دسته، نوع داده، نوع URL و تنظیمات قابل فیلتر، قابل انتخاب، قابل مرتب‌سازی و تکرار آن، لینک می‌دهد. اگر از منبع در عبارت FROM خود استفاده می‌کنید، می‌توانید از منوی کشویی Yes/No برای فیلتر کردن بخش‌هایی که در دسترس نیستند استفاده کنید.

ستون معیارها

همه فیلدهای معیارها با یک منبع مشخص قابل انتخاب نیستند.

ستون «معیارها» (Metrics) فیلدهای metrics را فهرست می‌کند که می‌توانید در همان عبارت SELECT به عنوان فیلدهای منبع استفاده کنید. هر فیلد به جزئیات کامل در مورد فیلد، از جمله توضیحات، دسته، نوع داده، نوع URL و تنظیمات قابل فیلتر، قابل انتخاب، قابل مرتب‌سازی و تکرار آن، لینک می‌دهد. اگر از منبع در عبارت FROM خود استفاده می‌کنید، از منوی کشویی «بله/خیر» برای فیلتر کردن معیارهایی که در دسترس نیستند استفاده کنید.

تقسیم‌بندی منابع

برخی منابع دارای فیلدهای منبع بخش‌بندی هستند که می‌توانید هنگام قرار گرفتن منبع در عبارت FROM خود، آنها را انتخاب کنید. برای مثال، اگر هنگام استفاده از campaign_budget در عبارت FROM خود، یک فیلد منبع campaign مانند campaign.name را انتخاب کنید، campaign.resource_name به طور خودکار برگردانده شده و بخش‌بندی می‌شود، زیرا campaign یک منبع بخش‌بندی شده از campaign_budget است.

بخش منابع بخش‌بندی، منابع بخش‌بندی موجود را فهرست می‌کند. همه منابع دارای منابع بخش‌بندی نیستند.

قابل انتخاب با

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

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

تقسیم‌بندی

شما می‌توانید نتایج جستجوی خود را با اضافه کردن فیلد segments. FIELD_NAME به عبارت SELECT در کوئری خود، بخش‌بندی کنید.

برای مثال، segments.device در کوئری زیر، منجر به گزارشی با ردیفی برای impressions هر دستگاه برای منبعی که در عبارت FROM مشخص شده است، می‌شود.

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

نتایج برگردانده شده توسط SearchAds360Service.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"
      }
    },
    ...
  ]
}

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

بخش‌های چندگانه

شما می‌توانید چندین بخش را در عبارت SELECT از پرس‌وجوی خود مشخص کنید. پاسخ شامل یک شیء SearchAds360Row برای هر ترکیبی از نمونه منبع اصلی مشخص شده در عبارت FROM و مقدار هر فیلد segment انتخاب شده است.

برای مثال، کوئری زیر برای هر ترکیبی از campaign ، segments.ad_network_type و segments.date یک ردیف برمی‌گرداند.

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

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

پرس و جوی مثال زیر منجر به یک ردیف به ازای هر کمپین می‌شود، نه یک ردیف به ازای هر مقدار مجزا از فیلد campaign.status .

SELECT
  campaign.status,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

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

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

این کوئری نمونه به طور خودکار 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"
      }
    }
  ]
}

بخش‌های اصلی تاریخ

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

فیلدهای سگمنت زیر به عنوان سگمنت‌های اصلی تاریخ شناخته می‌شوند: segments.date ، segments.week ، segments.month ، segments.quarter و segments.year .

این نمونه کوئری، معیارهای clicks کمپین را برای 30 روز گذشته برمی‌گرداند. 

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

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

قوانین بخش تاریخ اصلی:

  • شما می‌توانید از یک فیلد تاریخ اصلی در عبارت WHERE خود استفاده کنید بدون اینکه آن را در عبارت SELECT خود بگنجانید. همچنین در صورت تمایل می‌توانید این فیلد را در هر دو عبارت بگنجانید.

    این مثال کوئری، معیارهای clicks بر اساس نام کمپین در محدوده تاریخ برمی‌گرداند. توجه داشته باشید که segments.date در عبارت SELECT گنجانده نشده است. 

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

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

    این نمونه کوئری، معیارهای clicks را بر اساس نام کمپین و به تفکیک ماه برای تمام روزهای محدوده تاریخ، برمی‌گرداند. 

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

تاریخ‌های ISO 8601

شما می‌توانید از قالب YYYY-MM-DD (ISO 8601) برای مشخص کردن تاریخ‌ها و محدوده‌های تاریخ استفاده کنید، برای مثال: 

WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'

WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'

برای بخش‌های اصلی تاریخ که به یک دوره زمانی نیاز دارند ( segments.week ، segments.month ، segments.quarter ) می‌توانید از عملگر = به همراه اولین روز دوره زمانی استفاده کنید، برای مثال: 

WHERE segments.month = '2022-06-01'

تاریخ‌های از پیش تعریف‌شده

همچنین می‌توانید از تاریخ‌ها و محدوده‌های تاریخ از پیش تعریف شده زیر استفاده کنید:

تاریخ‌های از پیش تعریف‌شده
TODAY فقط امروز.
YESTERDAY فقط دیروز.
LAST_7_DAYS ۷ روز گذشته، بدون احتساب امروز.
LAST_BUSINESS_WEEK هفته کاری ۵ روزه قبلی (دوشنبه تا جمعه).
THIS_MONTH تمام روزهای ماه جاری.
LAST_MONTH تمام روزهای ماه قبل.
LAST_14_DAYS ۱۴ روز گذشته به جز امروز.
LAST_30_DAYS ۳۰ روز گذشته به جز امروز.
THIS_WEEK_SUN_TODAY دوره زمانی بین یکشنبه قبل و روز جاری.
THIS_WEEK_MON_TODAY دوره زمانی بین دوشنبه قبل و روز جاری.
LAST_WEEK_SUN_SAT دوره ۷ روزه که از یکشنبه قبل شروع می‌شود.
LAST_WEEK_MON_SUN دوره ۷ روزه که از دوشنبه قبل شروع می‌شود.

مثال: 

WHERE segments.date DURING LAST_30_DAYS

صفر معیار

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

انواع شمارشی ناشناخته

اگر منبعی با نوع داده شمارشی UNKNOWN برگردانده شود، به این معنی است که این نوع داده در نسخه API به طور کامل پشتیبانی نمی‌شود. این منابع ممکن است از طریق رابط‌های دیگر ایجاد شده باشند. به عنوان مثال، یک کمپین یا تبلیغ جدید در رابط کاربری Search Ads 360 معرفی شده است، اما هنوز در نسخه API مورد نظر شما پشتیبانی نمی‌شود.

شما همچنان می‌توانید معیارها را انتخاب کنید وقتی که یک منبع از نوع UNKNOWN باشد، اما باید موارد زیر را در نظر داشته باشید:

  • منبعی با نوع UNKNOWN ممکن است بعداً پشتیبانی شود، اما می‌تواند به طور نامحدود UNKNOWN باقی بماند.

  • اشیاء جدید با نوع UNKNOWN ممکن است در هر زمانی ظاهر شوند. این اشیاء با نسخه‌های قبلی سازگار هستند زیرا مقدار enum از قبل موجود است. ما منابع را با این تغییر به محض موجود شدن معرفی می‌کنیم تا شما دید دقیقی از حساب خود داشته باشید. منبع UNKNOWN ممکن است به دلیل فعالیت جدید در حساب شما از طریق رابط‌های دیگر یا به دلیل اینکه یک منبع دیگر به طور رسمی پشتیبانی نمی‌شود، ظاهر شود.

  • منابع UNKNOWN ممکن است معیارهای دقیقی داشته باشند که می‌توانید آنها را جستجو کنید.

  • منابع UNKNOWN معمولاً در رابط کاربری Search Ads 360 کاملاً قابل مشاهده هستند.