التنقّل بين النتائج

ملاحظة: تمت إزالة الحقل page_size في الإصدار 19 من Google Ads API. يمكنك الاطّلاع على الإشعار. القيمة التلقائية للحقل page_size هي 10,000. لا تحاول ضبط القيمة page_size، لأنّ ذلك سيؤدي إلى ظهور خطأ.

تتيح GoogleAdsService.Search تقسيم البيانات إلى صفحات بحجم ثابت يبلغ 10,000 صف. يتم تقسيم مجموعة نتائج طلب البحث إلى ردود متعددة، يحتوي كل منها على 10,000 عنصر.

على سبيل المثال، ضع في اعتبارك الاستعلام التالي:

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 في الرد. يُرجى العِلم أنّه لا تتم تعبئة next_page_token في الاستجابة التي تحتوي على آخر مجموعة من الصفوف.

تتعامل مكتبات البرامج مع التقسيم إلى صفحات تلقائيًا. ما عليك سوى تكرار الصفوف في الرد. عندما يتم عرض جميع الصفوف في الصفحة الحالية، تسترد مكتبة العميل صفحة جديدة من الصفوف تلقائيًا نيابةً عنك إلى أن يتم استرداد مجموعة البيانات بأكملها. في حال استخدام REST بدلاً من gRPC، يجب تقديم طلب بشكل صريح لكل صفحة جديدة.

تخزّن Google Ads API مؤقتًا مجموعة البيانات بأكملها، لذا تكون الطلبات اللاحقة أسرع من الطلب الأوّلي.

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

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