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

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

يتيح 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 مجموعة البيانات بالكامل مؤقتًا، لذا تكون الطلبات اللاحقة أسرع من الطلب الأوّلي.

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

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