נכסים מורחבים

השדות של משאבי האירועים כוללים את הנתונים הנפוצים ביותר שמשויכים לאירוע, כמו מיקום, שעת התחלה וכו', אבל יכול להיות שאפליקציות ירצו לאחסן מטא-נתונים נוספים שספציפיים לתרחיש לדוגמה שלהן. באמצעות Calendar API אפשר להגדיר צמדי מפתח/ערך מוסתרים באירוע, שנקראים Extended properties. מאפיינים מורחבים מאפשרים לאחסן בקלות נתונים ספציפיים לאפליקציה של אירוע בלי להשתמש במסד נתונים חיצוני.

חשיפה

יש שני סוגים של נכסים מורחבים זמינים: פרטיים ומשותפים. כל המשתתפים באירוע יכולים לראות את הנכסים המשותפים ולערוך אותם, ואילו נכסים פרטיים מוגדרים ב"עותק" מקומי של האירוע אצל כל משתתף. ליתר ביטחון, נכסים פרטיים הם ספציפיים ל-calendarId ול-eventId שבהם נעשה שימוש בבקשה, ואילו נכסים משותפים יוצגו ללא קשר ל-calendarId שנעשה בו שימוש בבקשה.

הוספה ועדכון של נכסים

מאפיינים מורחבים מוגדרים במשאב Events, וכמו שדות אחרים אפשר להגדיר בבקשות insert, update ו-patch. השימוש בבקשות תיקונים היא השיטה המועדפת, כי היא מאפשרת לבצע מניפולציות לגבי מאפיינים מסוימים בלי לשנות מאפיינים אחרים. הוספה של נכס חדש עם אותו מפתח תחליף את כל המאפיינים הקיימים עם אותו המפתח. בדוגמה הבאה מוצגת הגדרה של נכס פרטי:

PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId

{
  "extendedProperties": {
    "private": {
      "petsAllowed": "yes"
    }
  }
}

מחיקת נכסים

כל המאפיינים שלא נכללים בבקשת העדכון יימחקו, אבל כדי לפתור את הבעיה בצורה נכונה, מומלץ לשלוח בקשת תיקון ולהגדיר את הערך כ-null. בדוגמה הבאה מוצג מחיקת נכס פרטי:

PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId

{
  "extendedProperties": {
    "private": {
      "petsAllowed": null
    }
  }
}

מאפייני חיפוש

אפשר לחפש אירועים לפי הערכים בנכסים המורחבים שלהם באמצעות בקשה Events.list. מגדירים את השדה privateExtendedProperty או sharedExtendedProperty בתור אילוץ בפורמט propertyName=value, שמבצע חיפוש לפי נכסים פרטיים ונכסים משותפים, בהתאמה. הדוגמה הבאה מחזירה אירועים עם הנכס הפרטי petsAllowed=yes:

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes

אפשר לחזור על השדות האלה כמה פעמים, והאילוצים מסוג OR מקובצים יחד, כך שאירועים צריכים להתאים רק לאחת מהמגבלות שיוחזרו. בדוגמה הבאה מוצגים אירועים עם הנכס הפרטי petsAllowed=yes או isOutside=yes:

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes
    &privateExtendedProperty=isOutside%3Dyes

שימו לב שמגבלות על נכסים פרטיים ומשותפים מצורפים יחד, ולכן האירועים חייבים להתאים לשתי קבוצות האילוצים כדי שיוחזרו. בדוגמה הבאה מוצגים אירועים עם הנכס הפרטי petsAllowed=yes והנכס הציבורי createdBy=myApp:

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes
    &sharedExtendedProperty=createdBy%3DmyApp

מגבלות

1. הגודל המקסימלי של מפתח נכס הוא 44 תווים, ומאפיינים עם מפתחות ארוכים יותר יוסתרו בשקט.
2. הגודל המקסימלי של ערך מאפיין הוא 1,024 תווים, ומאפיינים עם ערכים ארוכים יותר ייחתכו באופן שקט.
3. אירוע יכול לכלול עד 300 נכסים בגודל כולל של עד 32KB (גודל המפתחות + גודל הערך). 300 הנכסים האלה כוללים נכסים משותפים ופרטיים בכל 'העותקים' של האירוע.