درحال بازیابی اشیاء

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

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

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

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

درباره صفحه‌بندی درمقابل جاری‌سازی بیشتر بدانید.

درخواست دادن

GoogleAdsService.SearchStream انتظار SearchGoogleAdsStreamRequest دارد، و GoogleAdsService.Search انتظار SearchGoogleAdsRequest دارد. هر دو نوع درخواست شامل موارد زیر است:

• یک customer_id
• یک Google Ads Query Language query که نشان می‌دهد کدام منبع را جستجو کنید، ویژگی‌ها، بخش‌ها، و سنجه‌ها را بازیابی کنید، و شرایطی که باید برای محدود کردن اشیاء برگردانده‌شده استفاده شود

بسته به روش، درخواست از فیلدهای مختص روش نیز پشتیبانی می‌کند:

• SearchGoogleAdsStreamRequest (فقط SearchStream):
  • summary_row_setting اختیاری برای درخواست ردیف خلاصه حاوی سنجه‌های انبوهشی
• SearchGoogleAdsRequest (فقط Search):
  • page_token اختیاری برای بازیابی دسته بعدی نتایج هنگام استفاده از صفحه‌بندی (page_size روی ۱۰٬۰۰۰ ردیف ثابت است؛ تنظیم page_size در درخواست باعث ایجاد خطای RequestError.PAGE_SIZE_NOT_SUPPORTED می‌شود)
  • پیام اختیاری search_settings برای پیکربندی return_summary_row، return_total_results_count، و omit_results
  • یک بولی validate_only اختیاری برای اعتبارسنجی پُرسمان بدون اجرای آن

برای اطلاعات بیشتر درباره Google Ads Query Language، به راهنمای Google Ads Query Language مراجعه کنید.

پردازش پاسخ

GoogleAdsService فهرستی از اشیاء GoogleAdsRow (درون دسته‌های جاری‌شده SearchGoogleAdsStreamResponse یا در SearchGoogleAdsResponse صفحه‌بندی‌شده) را برمی‌گرداند.

هر GoogleAdsRow نشان‌دهنده شیئی است که توسط پُرسمان برگردانده شده است و از مجموعه‌ای از مشخصه‌ها تشکیل شده است که براساس فیلدهای درخواست‌شده در عبارت SELECT پُر شده‌اند. مشخصه‌هایی که در عبارت SELECT گنجانده نشده‌اند، در اشیاء GoogleAdsRow در پاسخ پر نمی‌شوند.

برای مثال، اگرچه ad_group_criterion دارای مشخصه status است، فیلد status مشخصه ad_group_criterion ردیف در پاسخ به پُرسمانی که عبارت SELECT شامل ad_group_criterion.status نیست، پر نمی‌شود. به‌طور مشابه، اگر عبارت SELECT شامل هیچ فیلدی از منبع campaign نباشد، مشخصه campaign ردیف پر نمی‌شود.

هر GoogleAdsRow می‌تواند مشخصه‌ها و سنجه‌های متفاوتی نسبت به ردیف دیگر در همان مجموعه نتایج داشته باشد؛ بنابراین، ردیف‌ها باید به‌عنوان اشیاء درنظر گرفته شوند نه ردیف‌های ثابت یک جدول.

انواع شمارشی «ناشناخته» و «نامشخص»

منابعی که با مقدار enum UNKNOWN برگردانده می‌شوند، به‌طور کامل در آن نسخه API پشتیبانی نمی‌شوند، درحالی‌که UNSPECIFIED نشان می‌دهد که فیلد enum تنظیم نشده یا در عبارت SELECT درخواست نشده است. منابعی که مقدار شمارشی UNKNOWN دارند ممکن است ازطریق میاناهای دیگر مثل میانای کاربری Google Ads ایجاد شده باشند. وقتی منبعی از نوع UNKNOWN باشد، می‌توانید سنجه‌ها را انتخاب کنید، اما نمی‌توانید منبع را ازطریق میانای برنامه‌سازی کاربردی تغییر دهید. نمونه‌ای از این مورد، نوع آگهی یا پویشی است که در میانای کاربر دردسترس است اما در نسخه API که از آن پُرسمان می‌کنید پشتیبانی نمی‌شود.

در اینجا چند نکته برای درنظر گرفتن ارائه شده است:

• منبعی با نوع UNKNOWN می‌تواند در نسخه API جدیدتری پشتیبانی شود یا برای همیشه UNKNOWN باقی بماند.
• اشیاء جدید با نوع UNKNOWN ممکن است هرزمانی ظاهر شوند. این اشیاء با نسخه‌های قدیمی سازگار هستند زیرا مقدار شمارشی UNKNOWN در هر شمارش در API وجود دارد. منابع با UNKNOWN برگردانده می‌شوند تا نمای دقیقی از سنجه‌های عملکرد کلی حسابتان داشته باشید.
• UNKNOWN منابع می‌توانند سنجه‌های دقیقی داشته باشند که به آن‌ها پیوست شده است و قابل‌پرس‌وجو هستند.
• منابع UNKNOWN معمولاً به‌طور کامل در میانای کاربری Google Ads قابل‌مشاهده هستند.
• منابع UNKNOWN معمولاً نمی‌توانند ازطریق میانای برنامه‌سازی کاربردی تغییر کنند.

تقسیم بندی

پاسخ حاوی یک GoogleAdsRow برای هر ترکیب از موارد زیر است:

• نمونه‌ای از منبع اصلی مشخص‌شده در عبارت FROM
• مقدار هر فیلد segments انتخاب‌شده

برای مثال، پاسخ برای پرسمانی که 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.