חלוקה לדפים

ה-API ל-REST של Ad Manager מספק אוספים של נתונים, בדרך כלל ב-List שיטות. אפשר להגדיר גודל שרירותי של אוספים ולחלק אותם ב-API תשובות מדויקות.

היסודות

הודעות של בקשות לאוספים מגדירות שדה אופציונלי של מספר שלם pageSize כדי לציין את המספר המקסימלי של תוצאות שיחזרו.

אם המדיניות pageSize לא מוגדרת או לא מוגדרת, המערכת תשתמש בערך ברירת המחדל של 50. אם ה-pageSize חורג מגודל הדף המקסימלי שהוא 1,000, ה-API אילוץ גודל הדף ל-1,000. ערכים שליליים מובילים לשגיאה INVALID_ARGUMENT.

ה-API עשוי להחזיר פחות תוצאות מהמספר המבוקש (כולל אפס גם אם לא בסוף האוסף. להשתמש בנוכחות של nextPageToken כדי לקבוע אם יש תוצאות נוספות האוסף 'עדכונים'.

הודעות תגובה לאוספים מגדירות מחרוזת בשדה nextPageToken, אפשר להשתמש בה כדי לאחזר את הדף הבא. השדה nextPageToken ריק כאשר סוף האוסף הוא הגעת. זו הדרך היחידה לקבוע אם הגעתם לסוף האוסף 'עדכונים'.

בקשות להודעות לקולקציות מגדירות מחרוזת אופציונלית בשדה pageToken כדי להתקדם לדף הבא באוסף. מותר לבצע שינויים ב-pageSize בבקשה לדפים הבאים. כל שאר הארגומנטים חייבים להיות זהים; אם הארגומנטים שונים, ה-API מחזירה שגיאה מסוג 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 שמייצג המספר הכולל של הישויות אחרי הפעלת הסינון. בשדה הזה בלבד יאוכלס כשנשלחת בקשה field mask.

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 כתחליף החלוקה לדפים. אסימון החלוקה לדפים מבטיח שהתשובה תהיה מאותה האות וזה התוצאות.