تصفُّح النتائج

يمكنك تصفّح النتائج التي تم استرجاعها باستخدام GoogleAdsService.Search بدلاً من تنزيل مجموعة النتائج بأكملها في وقت واحد. للحصول على نظرة عامة حول إعداد التقارير باستخدام Google Ads API، اطّلِع على نظرة عامة حول إعداد التقارير.

تعرض Search صفحات ثابتة تحتوي على ما يصل إلى 10,000 صف. تم إيقاف الإعداد 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

إذا كان حسابك يحتوي على 50,000 كلمة رئيسية، ستتضمّن مجموعة النتائج 10,000 عنصر GoogleAdsRow في الردّ الأول، بالإضافة إلى next_page_token.

لاسترداد الـ 10,000 صف التالية، أرسِل الطلب مرة أخرى، ولكن عدِّل 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، عليك تقديم طلب بشكل صريح لكل صفحة جديدة.

التخزين المؤقت وانتهاء صلاحية الرمز المميز للصفحة

تخزّن Google Ads API مجموعة البيانات مؤقتًا داخليًا حتى تكون طلبات الصفحات اللاحقة أسرع من الطلب الأوّلي. يُرجى العِلم أنّ قيم next_page_token لها مدة بقاء محدودة وتنتهي صلاحيتها إذا لم يتم استخدامها خلال فترة قصيرة (حوالي ساعتين). إذا انتهت صلاحية رمز مميّز للصفحة، ستعرض واجهة برمجة التطبيقات رسالة خطأ، وعليك بدء طلب بحث جديد.

يجب أن يظل طلب البحث مطابقًا في الطلبات اللاحقة للاستفادة من البيانات المخزّنة مؤقتًا. لا يتم احتساب الطلبات اللاحقة المقسّمة إلى صفحات كعمليات إضافية ضمن حصة العمليات اليومية المخصّصة لإذن الوصول إلى Explorer وإذن الوصول الأساسي. إذا كان الاستعلام مختلفًا وتم إرساله مع الرمز المميز للصفحة نفسه، سيتم عرض رسالة خطأ.