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

برای آشنایی با نحوه ایجاد گزارش‌های جستجو در Search Ads 360 Reporting API، بخش‌های زیر را بخوانید.

سرویس جستجو

Search Ads 360 Reporting API یک سرویس ویژه برای جستجو و گزارش ارائه می کند.

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

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

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

روش های جستجو

SearchStream

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

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

Search

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

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

روشی که استفاده می‌کنید بر سهمیه‌ها و محدودیت‌های 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 به سرور Search Ads 360 Reporting 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

مستندات مرجع

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

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

منابع نسبت داده شده

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

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

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

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

ستون بخش ها

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

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

ستون متریک

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

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

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

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

بخش Segmenting Source منابع تقسیم بندی موجود را فهرست می کند. همه منابع دارای منابع تقسیم بندی نیستند.

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

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

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

تقسیم بندی

شما می توانید نتایج جستجوی خود را با افزودن یک segments. FIELD_NAME فیلد 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	7 روز گذشته بدون احتساب امروز.
LAST_BUSINESS_WEEK	هفته کاری 5 روزه قبلی (دوشنبه تا جمعه).
THIS_MONTH	تمام روزهای ماه جاری
LAST_MONTH	تمام روزهای ماه قبل
LAST_14_DAYS	14 روز قبل به استثنای امروز.
LAST_30_DAYS	30 روز قبل به استثنای امروز.
THIS_WEEK_SUN_TODAY	بازه زمانی بین یکشنبه قبل و روز جاری.
THIS_WEEK_MON_TODAY	بازه زمانی بین دوشنبه قبل و روز جاری.
LAST_WEEK_SUN_SAT	دوره 7 روزه از یکشنبه قبل شروع می شود.
LAST_WEEK_MON_SUN	دوره 7 روزه از دوشنبه قبل شروع می شود.

مثال:

WHERE segments.date DURING LAST_30_DAYS

معیارهای صفر

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

انواع enum ناشناخته

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

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

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