توفّر واجهة برمجة تطبيقات REST في "مدير الإعلانات" مجموعات من البيانات، وأكثرها شيوعًا في قسم "القائمة" الطرق. يمكن أن تكون المجموعات مختلفة الحجم بشكل عشوائي ويتم تقسيمها إلى صفحات في واجهة برمجة التطبيقات. الردود.
الأساسيات
يحدّد حقل طلب الرسائل للمجموعات عددًا اختياريًا من الحقول pageSize بهدف
تحديد الحد الأقصى لعدد النتائج المراد عرضها.
إذا لم يتم ضبط pageSize أو كانت 0، يتم استخدام القيمة التلقائية التي تبلغ 50.
إذا تجاوز pageSize الحدّ الأقصى لحجم الصفحة وهو 1000، تفرض واجهة برمجة التطبيقات
لحجم الصفحة إلى 1000.
تؤدّي القيم السلبية إلى الخطأ INVALID_ARGUMENT.
قد تعرض واجهة برمجة التطبيقات نتائج أقل من العدد المطلوب (بما في ذلك صفر).
النتائج)، حتى لو لم يكن في نهاية المجموعة. يتيح لك استخدام
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 إلى إرجاع صفحة واحدة من النتائج بدءًا من النتيجة الحادية والثلاثين.
يشير هذا المصطلح إلى طلب يتضمّن رمزًا مميّزًا للصفحة يقابل النتيجة الحادية والخمسين (لأنّ النتيجة الأولى تم عرض 50 نتيجة على الصفحة الأولى) وكانت قيمة التخطي 30 تُرجع صفحة واحدة من النتائج تبدأ بالنتيجة 81.
إذا تم توفير قيمة تخطي تتسبب في نقل المؤشر بعد نهاية
مجموعة من النتائج، يكون الرد 200 OK مع مجموعة نتائج فارغة بدون
nextPageToken