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

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

تعرِض 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 لها مدة بقاء محدودة وتنتهي صلاحيتها إذا لم يتم استخدامها خلال فترة قصيرة (حوالى ساعتين). إذا انتهت صلاحية رمز الصفحة، تعرض واجهة برمجة التطبيقات خطأ وعليك بدء طلب بحث جديد.

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

السابق
بث
التالي
التقارير في واجهة المستخدم