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