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

GoogleAdsService سرویس یکپارچه بازیابی اشیاء و گزارش API Google Ads است. این سرویس دارای روش هایی است که:

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

GoogleAdsService می تواند نتایج را به دو روش بازگرداند:

• GoogleAdsService.SearchStream همه ردیف ها را در یک پاسخ جریانی برمی گرداند که برای مجموعه نتایج بزرگ (بیش از 10000 ردیف) کارآمدتر است. اگر برنامه دسته‌ای شما بخواهد داده‌ها را با بیشترین سرعت ممکن دانلود کند، ممکن است مناسب‌تر باشد.
• GoogleAdsService.Search پاسخ های بزرگ را به صفحات قابل مدیریت نتایج تقسیم می کند. اگر برنامه تعاملی شما یک صفحه از نتایج را در یک زمان نمایش دهد، می تواند مناسب تر باشد.

درباره صفحه بندی در مقابل پخش جریانی بیشتر بیاموزید.

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

روش جستجو به یک SearchGoogleAdsRequest نیاز دارد که از ویژگی های زیر تشکیل شده است:

• customer_id
• یک query زبان Google Ads Query که نشان می‌دهد کدام منبع باید پرس و جو شود، ویژگی‌ها، بخش‌ها و معیارهای بازیابی، و شرایطی که باید برای محدود کردن اشیاء بازگردانده شوند استفاده کرد.
• (فقط GoogleAdsService.Search ) یک page_size برای نشان دادن تعداد اشیاء در یک پاسخ هنگام استفاده از صفحه‌بندی .
• (فقط 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 .