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

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

חשיפה

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

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

מאפיינים מורחבים מוגדרים במשאב Events, וכמו שדות אחרים, אפשר להגדיר אותם בבקשות events.insert, ‏ events.update ו-events.patch. השימוש בבקשות 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, שמבצע חיפוש בנכסים פרטיים ובנכסים משותפים בהתאמה. בדוגמה הבאה מוצגים אירועים עם המאפיין 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 מאפיינים האלה כוללים מאפיינים משותפים ומאפיינים פרטיים, בכל העותקים של האירוע.