نتایج صفحه به صفحه

شما می‌توانید به جای دانلود یکجای کل مجموعه نتایج، نتایج بازیابی شده با GoogleAdsService.Search را مرور کنید. برای مرور کلی گزارش‌دهی با Google Ads API، به بخش «مرور کلی گزارش‌دهی» مراجعه کنید.

Search صفحات ثابت تا سقف ۱۰۰۰۰ ردیف را برمی‌گرداند. تنظیم page_size در SearchGoogleAdsRequest منسوخ شده است و خطای RequestError.PAGE_SIZE_NOT_SUPPORTED را برمی‌گرداند.

نمونه کوئری و صفحه بندی

پرس‌وجوی زیر را در نظر بگیرید:

SELECT
  ad_group.id,
  ad_group_criterion.type,
  ad_group_criterion.criterion_id,
  ad_group_criterion.keyword.text,
  ad_group_criterion.keyword.match_type
FROM ad_group_criterion
WHERE ad_group_criterion.type = KEYWORD

اگر حساب کاربری شما شامل ۵۰،۰۰۰ کلمه کلیدی باشد، مجموعه نتایج شامل ۱۰،۰۰۰ شیء GoogleAdsRow در اولین پاسخ، به همراه یک next_page_token خواهد بود.

برای بازیابی ۱۰،۰۰۰ ردیف بعدی، درخواست را دوباره ارسال کنید، اما page_token درخواست را به next_page_token پاسخ به‌روزرسانی کنید:

{
  "query": "SELECT ad_group.id, ad_group_criterion.type, ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type FROM ad_group_criterion WHERE ad_group_criterion.type = KEYWORD",
  "pageToken": "CN3q9...example_token..."
}

توجه داشته باشید که next_page_token در پاسخی که شامل آخرین دسته از ردیف‌ها است، پر نمی‌شود.

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

ذخیره سازی و انقضای توکن صفحه

API گوگل ادز به صورت داخلی مجموعه داده‌ها را ذخیره می‌کند تا درخواست‌های بعدی برای صفحات سریع‌تر از درخواست اولیه باشند. توجه داشته باشید که مقادیر next_page_token مدت زمان محدودی برای حیات (TTL) دارند و اگر در مدت کوتاهی (حدود دو ساعت) استفاده نشوند، منقضی می‌شوند. اگر توکن یک صفحه منقضی شود، API خطایی را برمی‌گرداند و شما باید یک کوئری جدید شروع کنید.

درخواست شما باید در درخواست‌های بعدی یکسان باقی بماند تا از داده‌های ذخیره‌شده بهره‌مند شوید. درخواست‌های صفحه‌بندی‌شده‌ی بعدی، به عنوان عملیات اضافی در سهمیه عملیات روزانه شما برای دسترسی به Explorer و دسترسی پایه محسوب نمی‌شوند. اگر درخواست متفاوت باشد و همراه با همان نشانه صفحه ارسال شود، خطا برگردانده می‌شود.