ב-API ל-REST של Ad Manager נעשה שימוש במסכות של שדות לצורך קריאה וכתיבה חלקיות. מי יכול לשפר את הביצועים על ידי הגבלת כמות הנתונים שמועברים. מסכות שדה מיוצגים על ידי רשימה של שמות שדות שמופרדים בפסיקים. לדוגמה:
startTime,endTime,targeting.geoTargeting
קריאת מסכות
מסכות קריאה קובעות אילו שדות יופיעו בתגובת API. אפשר להגדיר קריאת המסכה בבקשה שלכם בשתי דרכים:
פרמטר השאילתה
fields:curl https://admanager.googleapis.com/v1/networks/123456/adUnits?fields=adUnits,nextPageToken,totalSizeכותרת ה-HTTP
X-Goog-FieldMask:curl -H "X-Goog-FieldMask: adUnits,nextPageToken,totalSize" \ https://admanager.googleapis.com/v1/networks/123456/adUnits
מסכות קריאה שמוגדרות כברירת מחדל
חלק משיטות ה-API כוללות אנונימיזציה של שדות כברירת מחדל לשדות יקרים
כדי לחזור אליה. דוגמה לכך היא שיטות רשימה. כברירת מחדל, הם לא כוללים
totalSize
השדה הזה.
חובה לבקש במפורש את השדות האלה במסכת השדות לפי שם או לפי
באמצעות התו הכללי לחיפוש *.
עדכון המסכות
עדכון המסכות קובעות אילו שדות ישתנו בעדכון (PATCH)
בקשה. כשמוגדרת מסכת עדכון, רק השדות במסכה יעודכנו
ללא קשר לשדות שהוגדרו בגוף הבקשה.
מסכות עדכון מוגדרות כפרמטרים של שאילתות. לדוגמה:
curl -X PATCH https://admanager.googleapis.com/v1/networks/1234/order/4567?updateMask=displayName
מעבר שדה
מסכות שדות יכולות לציין שדות בתוך ישות באמצעות התו . עבור
חצייה. זהו אותו תחביר שמשמש
מסננים.
מסכות של שדות תמיד הן יחסיות לאובייקט התגובה. לדוגמה, לבצע מסכה עבור
קריאה של LineItem עשויה לכלול את primaryGoal.units. המסכה המתאימה
לכרטיס מוצר
LineItems היא lineItems.primaryGoal.units.
אפשר לציין שדה שלם או אחד משדות המשנה שלו. שתי השיטות
הערכים primaryGoal ו-primaryGoal.units תקינים.
הכלל הזה חל גם על שדות חוזרים. אנונימיזציה של שדות מסוג LineItem
השדה creativePlaceholders.size חוקי וכולל רק את השדה size
בכל CreativePlaceholder.
תווים כלליים לחיפוש
במסכות של שדות יש תמיכה בתו *, שמציין את כל השדות בהודעה.
הדוגמאות הבאות ממחישות שימוש בתווים כלליים לחיפוש במהלך רישום
Orders. לשיטה הזו יש מסכת קריאה שמוגדרת כברירת מחדל
לא לכלול את השדה total_size.
| דוגמה | משמעות |
|---|---|
* |
כולל את כל השדות, כולל total_size |
orders |
כולל רק את השדה orders ואת כל שדות המשנה שלו |
orders.* |
כולל רק את השדה orders ואת כל שדות המשנה שלו |
שדות לא חוקיים
אם מסכת שדות מתייחסת לערך שלא קיים, ה-API יגיב
עם שגיאה INVALID_ARGUMENT.