الحدود الفاصلة للصفحات

توفّر 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. يتم تجاهل الأحرف المتكرّرة في البنية. القيم orderBy وfoo, bar desc وfoo , bar desc وfoo,bar desc متكافئة. يتم تحديد الحقول الفرعية باستخدام الحرف .، مثل foo.bar أو address.street.

لا يمكن ترتيب الحقول إلا على الحقول الأساسية.

تخطّي النتائج

تحدِّد طُرق العملية المفصَّلة حقلًا عدديًا skip لتخطّي النتائج. تشير قيمة التخطّي إلى عدد الموارد الفردية المطلوب تخطّيها، وليس عدد الصفحات.

على سبيل المثال:

يعرض الطلب الذي لا يحتوي على رمز تعريف للصفحة وقيمة التخطّي 30 صفحة واحدة من النتائج بدءًا من النتيجة 31.

يعرض طلب يتضمّن رمز تعريف صفحة يتوافق مع النتيجة 51 (لأنّه تم عرض أول 50 نتيجة في الصفحة الأولى) وقيمة تخطّي تبلغ 30 صفحة واحدة من النتائج بدءًا من النتيجة 81.

إذا تم تقديم قيمة تخطّي تؤدي إلى نقل المؤشر إلى ما بعد نهاية مجموعة النتائج، يكون الردّ هو 200 OK مع مجموعة نتائج فارغة بدون nextPageToken.

ملاحظة مهمة: يجب عدم استخدام الحقل skip كبديل لميزة الفهرسة. يضمن الرمز المميّز لنظام تقسيم الصفحات أنّ الاستجابة تأتي من مجموعة النتائج الأولية نفسها.