توفّر Ad Manager API مجموعات من البيانات، غالبًا في طرق List. يمكن أن تكون المجموعات بأي حجم ويتم تقسيمها إلى صفحات في استجابات واجهة برمجة التطبيقات.
الأساسيات
تحدّد رسائل طلبات المجموعات حقل pageSize اختياريًا من نوع عدد صحيح لتحديد الحدّ الأقصى لعدد النتائج المطلوب عرضها.
اضبط المَعلمة pageSize على رقم موجب أقل من 1000. إذا لم تضبط أي قيمة أو ضبطت المَعلمة على صفر، تستخدم واجهة برمجة التطبيقات قيمة تلقائية هي 50. إذا ضبطت المَعلمة على قيمة سالبة، تعرض واجهة برمجة التطبيقات خطأ INVALID_ARGUMENT.
يُرجى الرجوع إلى مستندات مرجع المورد، مثل
AdBreaks,
للحصول على قيمة pageSize خاصة بمورد معيّن.
قد تعرض واجهة برمجة التطبيقات عددًا أقل من النتائج المطلوبة (بما في ذلك عدم عرض أي نتائج)، حتى إذا لم تكن في نهاية المجموعة. استخدِم حقل nextPageToken لتحديد ما إذا كانت هناك نتائج إضافية في المجموعة.
تحدّد رسائل استجابة المجموعات حقل nextPageToken من نوع سلسلة، ويمكن استخدامه لاسترداد الصفحة التالية. يكون حقل nextPageToken فارغًا عند الوصول إلى نهاية المجموعة. هذه هي الطريقة الوحيدة لتحديد ما إذا كنت قد وصلت إلى نهاية مجموعة.
تحدّد رسائل طلبات المجموعات حقل pageToken اختياريًا من نوع سلسلة للانتقال إلى الصفحة التالية في المجموعة. يُسمح بإجراء تغييرات على pageSize في طلب الصفحات اللاحقة. يجب أن تكون جميع الوسيطات الأخرى متطابقة، وإذا كانت أي وسيطات مختلفة، تعرض واجهة برمجة التطبيقات خطأ INVALID_ARGUMENT.
مثال
cURL
الطلب الأوّلي
curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500
{
"adUnits": [ ... ],
"nextPageToken": "eCGwAcs6hUerggzd2DGv"
}
طلب الصفحة التالية
curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500&pageToken=eCGwAcs6hUerggzd2DGv
{
"adUnits": [ ... ]
}
إجمالي الحجم
توفّر رسائل استجابة المجموعات حقل totalSize من نوع عدد صحيح يمثّل العدد الإجمالي للكيانات بعد تطبيق الفلترة. لا تتم تعبئة هذا الحقل إلا عند طلبه في قناع الحقل.
GET https://admanager.googleapis.com/v1/networks/123456/adUnits?$fields=adUnits,nextPageToken,totalSize
ترتيب النتائج
تحدّد رسائل طلبات المجموعات حقل orderBy من نوع سلسلة لتحديد ترتيب الفرز.
يجب أن تكون القيم قائمة بالحقول مفصولة بفواصل. على سبيل المثال: foo,bar. ترتيب الفرز التلقائي هو تصاعدي. لتحديد ترتيب تنازلي لحقل،
أضِف اللاحقة desc، على سبيل المثال: foo desc, bar. يتم تجاهل أحرف المسافة الزائدة في البنية. تكون القيم foo, bar desc وfoo , bar desc وfoo,bar desc في orderBy متساوية. يتم تحديد الحقول الفرعية
باستخدام الحرف .، مثل foo.bar أو address.street.
لا يتوفّر الترتيب إلا في الحقول الأساسية.
تخطّي النتائج
تحدّد طرق العملية المقسّمة إلى صفحات حقل skip من نوع عدد صحيح لتخطّي النتائج. تشير قيمة التخطّي إلى عدد الموارد الفردية التي يجب تخطّيها، وليس عدد الصفحات.
على سبيل المثال:
يعرض طلب بدون رمز مميّز للصفحة وقيمة تخطّي تبلغ 30 صفحة واحدة من النتائج تبدأ بالنتيجة 31.
يعرض طلب يتضمّن رمزًا مميّزًا للصفحة يتوافق مع النتيجة 51 (لأنّه تم عرض أول 50 نتيجة في الصفحة الأولى) وقيمة تخطّي تبلغ 30 صفحة واحدة من النتائج تبدأ بالنتيجة 81.
إذا تم تقديم قيمة تخطّي تؤدي إلى انتقال المؤشر إلى ما بعد نهاية مجموعة النتائج، تكون الاستجابة 200 OK مع مجموعة نتائج فارغة بدون nextPageToken.