עימוד

‫Ad Manager API מספק אוספים של נתונים, בדרך כלל ב-Listmethods. הגודל של האוספים יכול להיות שרירותי, והם מחולקים לדפים בתגובות של ה-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 כתחליף להוספת מספור לדפים. אסימון העימוד מוודא שהתשובה מגיעה מאותה קבוצת תוצאות ראשונית.