עימוד

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

היסודות

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

מגדירים את הפרמטר pageSize למספר חיובי, קטן מ-1000. אם לא מגדירים ערך או מגדירים את הפרמטר לאפס, ה-API משתמש בערך ברירת המחדל 50. אם מגדירים את הפרמטר לערך שלילי, ה-API מחזיר את השגיאה INVALID_ARGUMENT.

כדי למצוא את הערך הספציפי של pageSize למשאב, אפשר לעיין במסמכי העזרה של המשאב, למשל AdBreaks.

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

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 כדי לדלג על תוצאות. הערך של skip מתייחס למספר המשאבים הנפרדים שרוצים לדלג עליהם, ולא למספר הדפים.

לדוגמה:

בקשה ללא אסימון דף וערך דילוג של 30 מחזירה דף אחד של תוצאות, החל מהתוצאה ה-31.

בקשה עם אסימון דף שתואם לתוצאה ה-51 (כי 50 התוצאות הראשונות הוצגו בדף הראשון) וערך דילוג של 30 מחזירה דף אחד של תוצאות, החל מהתוצאה ה-81.

אם מציינים ערך דילוג שגורם לסמן לעבור את סוף אוסף התוצאות, התשובה היא 200 OK עם קבוצת תוצאות ריקה ללא nextPageToken.

חשוב: אין להשתמש בשדה skip כתחליף לחלוקה לדפים. אסימון העימוד מבטיח שהתגובה מגיעה מאותה קבוצת תוצאות ראשונית.