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