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

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

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

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

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

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

درخواست دادن

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

• ‫customer_id
• «زبان پُرسمان Google Ads» 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»، راهنمای «زبان پُرسمان Google Ads» را بررسی کنید.

پردازش پاسخ

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 می‌تواند ویژگی‌ها و سنجه‌های متفاوتی از ردیف دیگر در همان مجموعه نتایج داشته باشد؛ بنابراین ردیف‌ها باید به‌عنوان شیء درنظر گرفته شوند نه ردیف‌های ثابت جدول.

انواع شمارشی UNKNOWN و UNSPECIFIED

منابعی که با مقدار شمارشی UNKNOWN برگردانده می‌شوند در آن نسخه API به‌طور کامل پشتیبانی نمی‌شوند، درحالی‌که UNSPECIFIED نشان می‌دهد که فیلد شمارشی تنظیم نشده است یا در بند 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.