توفّر 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
.