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

تتيح لغة طلب البحث في "إعلانات Google" تقسيم الصفحات من خلال تحديد page_size في طلبك. سيؤدي ذلك إلى تقسيم مجموعة نتائج طلب البحث إلى عدة استجابات يحتوي كل منها على ما يصل إلى كائنات page_size. إذا لم يتم تحديد page_size، يتم ضبطه تلقائيًا على الحد الأقصى لحجم الصفحة وهو 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 كلمة رئيسية وتم ضبط page_size على 1,000، ستحتوي مجموعة النتائج على 1,000 عنصر GoogleAdsRow في الاستجابة الأولى، بالإضافة إلى next_page_token. لاسترداد الألف صف التالي، ما عليك سوى إرسال الطلب مرة أخرى بحجم الصفحة نفسه، مع تعديل page_token للطلب إلى next_page_token في الاستجابة. يمكن أن تختلف قيمة page_size في الطلبات اللاحقة في كل مرة.

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

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

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