GoogleAdsService سرویس یکپارچه بازیابی اشیاء و گزارش API Google Ads است. این سرویس دارای روش هایی است که:
- بازیابی ویژگی های خاص اشیاء
- بازیابی معیارهای عملکرد برای اشیاء بر اساس محدوده تاریخ.
- اشیاء را بر اساس ویژگی های آنها مرتب کنید.
- از شرایط برای نشان دادن اینکه کدام اشیاء را می خواهید در پاسخ بازگردانید استفاده کنید.
- تعداد اشیاء برگشتی را محدود کنید.
GoogleAdsService می تواند نتایج را به دو روش بازگرداند:
-
GoogleAdsService.SearchStreamهمه ردیف ها را در یک پاسخ جریانی برمی گرداند که برای مجموعه نتایج بزرگ (بیش از 10000 ردیف) کارآمدتر است. اگر برنامه دستهای شما بخواهد دادهها را با بیشترین سرعت ممکن دانلود کند، ممکن است مناسبتر باشد. -
GoogleAdsService.Searchپاسخ های بزرگ را به صفحات قابل مدیریت نتایج تقسیم می کند. اگر برنامه تعاملی شما یک صفحه از نتایج را در یک زمان نمایش دهد، می تواند مناسب تر باشد.
درباره صفحه بندی در مقابل پخش جریانی بیشتر بیاموزید.
درخواست بدهید
روش جستجو به یک SearchGoogleAdsRequest نیاز دارد که از ویژگی های زیر تشکیل شده است:
-
customer_id - یک
queryزبان Google Ads Query که نشان میدهد کدام منبع باید پرس و جو شود، ویژگیها، بخشها و معیارهای بازیابی، و شرایطی که باید برای محدود کردن اشیاء بازگردانده شوند استفاده کرد. - (فقط
GoogleAdsService.Search) یکpage_tokenاختیاری برای بازیابی دسته بعدی نتایج هنگام استفاده از صفحهبندی .
برای کسب اطلاعات بیشتر در مورد زبان جستجوی Google Ads، راهنمای زبان جستجوی Google Ads را بررسی کنید.
یک پاسخ را پردازش کنید
GoogleAdsService فهرستی از اشیاء GoogleAdsRow را برمی گرداند.
هر GoogleAdsRow نشان دهنده یک شی است که توسط یک پرس و جو برگردانده می شود و شامل مجموعه ای از ویژگی ها است که بر اساس فیلدهای درخواست شده در عبارت SELECT پر می شوند. ویژگیهایی که در بند SELECT گنجانده نشدهاند، در اشیاء GoogleAdsRow در پاسخ پر نشدهاند.
به عنوان مثال، اگرچه یک ad_group_criterion دارای یک ویژگی status است، فیلد status صفت ad_group_criterion ردیف در پاسخی برای درخواستی که در آن بند SELECT شامل ad_group_criterion.status نیست، پر نمی شود. به طور مشابه، اگر بند SELECT شامل هیچ فیلدی از منبع campaign نباشد، ویژگی campaign ردیف پر نمی شود.
هر GoogleAdsRow میتواند ویژگیها و معیارهای متفاوتی از ردیف دیگر در همان مجموعه نتایج داشته باشد. بنابراین سطرها باید بهعنوان اشیاء دیده شوند تا ردیفهای ثابت جدول.
انواع enum ناشناخته
منابعی که با یک نوع UNKNOWN برگردانده می شوند در آن نسخه API به طور کامل پشتیبانی نمی شوند. این منابع را میتوان از طریق رابطهای دیگری مانند رابط کاربری Google Ads ایجاد کرد. هنگامی که یک منبع دارای یک نوع UNKNOWN است، می توانید معیارها را انتخاب کنید، اما نمی توانید منبع را از طریق API تغییر دهید. یک مثال از این یک کمپین یا تبلیغ جدید است که در UI معرفی شده است، اما در نسخه API مورد نظر شما پشتیبانی نمی شود.
در اینجا چند نکته وجود دارد که باید در نظر داشت:
- منبعی با نوع
UNKNOWNمی تواند بعداً پشتیبانی شود یا برای مدت نامحدودUNKNOWNبماند. - اشیاء جدید با نوع
UNKNOWNمی توانند در هر زمانی ظاهر شوند. این اشیاء با عقب سازگار هستند زیرا مقدار enum از قبل در دسترس است. منابع با این تغییر با در دسترس بودن معرفی می شوند تا دید دقیقی از حساب خود داشته باشید. منبعUNKNOWNمی تواند به دلیل فعالیت های جدید در حساب شما از طریق واسط های دیگر ظاهر شود، یا زمانی که منبعی دیگر پشتیبانی نمی شود. - منابع
UNKNOWNمی توانند معیارهای دقیقی را به آنها متصل کرده باشند که قابل پرس و جو هستند. - منابع
UNKNOWNمعمولاً به طور کامل در رابط کاربری Google Ads قابل مشاهده هستند. - منابع
UNKNOWNعموماً قابل تغییر نیستند.
تقسیم بندی
پاسخ شامل یک GoogleAdsRow برای هر ترکیب از موارد زیر است:
- نمونه ای از منبع اصلی مشخص شده در عبارت
FROM - مقدار هر
segmentانتخاب شده
به عنوان مثال، پاسخ برای یک پرس و جو که FROM campaign انتخاب می کند و segments.ad_network_type و segments.date در عبارت SELECT دارد، برای هر ترکیبی از موارد زیر یک ردیف دارد:
-
campaign -
segments.ad_network_type -
segments.date
نتایج به طور ضمنی با هر نمونه از منبع اصلی تقسیم می شوند، نه بر اساس مقادیر فیلدهای جداگانه انتخاب شده. به عنوان مثال،
SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS
نتیجه یک ردیف در هر کمپین است، نه یک ردیف در هر مقدار مشخص از فیلد campaign.status .