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

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

חשיפה

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

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

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

PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId
 
{
  "extendedProperties": {
    "private": {
      "petsAllowed": "yes"
    }
  }
}

מחיקת נכסים

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

PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId
 
{
  "extendedProperties": {
    "private": {
      "petsAllowed": null
    }
  }
}

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

אפשר לחפש אירועים על סמך הערכים במאפיינים המורחבים שלהם באמצעות בקשת Events.list. מגדירים את השדה privateExtendedProperty או sharedExtendedProperty לאילוץ בפורמט propertyName=value, כדי לחפש מאפיינים פרטיים או משותפים בהתאמה. בדוגמה הבאה מוצגים אירועים עם המאפיין private 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 המאפיינים האלה כוללים מאפיינים משותפים ופרטיים בכל 'העותקים' של האירוע.