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

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

חשיפה

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

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