بازیابی اشیاء

سرویس 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 .