बढ़ाई गई प्रॉपर्टी

इवेंट रिसॉर्स के फ़ील्ड में, किसी इवेंट से जुड़ा सबसे सामान्य डेटा शामिल होता है. जैसे, जगह, शुरू होने का समय वगैरह. हालांकि, ऐप्लिकेशन अपने इस्तेमाल के उदाहरण के हिसाब से, ज़्यादा मेटाडेटा स्टोर करना चाह सकते हैं. Calendar API की मदद से, किसी इवेंट के साथ छिपे हुए की-वैल्यू पेयर सेट किए जा सकते हैं. इन्हें एक्सटेंड की गई प्रॉपर्टी कहा जाता है. एक्सटेंडेड प्रॉपर्टी की मदद से, किसी इवेंट के लिए ऐप्लिकेशन से जुड़ा डेटा आसानी से सेव किया जा सकता है. इसके लिए, किसी बाहरी डेटाबेस का इस्तेमाल करने की ज़रूरत नहीं होती.

किसको दिखे

एक्सटेंडेड प्रॉपर्टी दो तरह की होती हैं: निजी और शेयर की गई. शेयर की गई प्रॉपर्टी, इवेंट में शामिल सभी लोगों को दिखती हैं और वे उनमें बदलाव कर सकते हैं. वहीं, निजी प्रॉपर्टी, इवेंट में शामिल किसी एक व्यक्ति की स्थानीय "कॉपी" पर सेट होती हैं. ज़्यादा जानकारी के लिए, बता दें कि निजी प्रॉपर्टी, अनुरोध में इस्तेमाल किए गए calendarId और eventId के हिसाब से होती हैं. वहीं, शेयर की गई प्रॉपर्टी, अनुरोध में इस्तेमाल किए गए calendarId के बावजूद दिखेंगी.

प्रॉपर्टी जोड़ना और अपडेट करना

एक्सटेंडेड प्रॉपर्टी, इवेंट रिसॉर्स पर सेट की जाती हैं. साथ ही, अन्य फ़ील्ड की तरह ही इन्हें शामिल करें, अपडेट करें, और पैच करें अनुरोधों में सेट किया जा सकता है. पैच अनुरोधों का इस्तेमाल करना सबसे सही तरीका है, क्योंकि इससे कुछ प्रॉपर्टी में बदलाव किए जा सकते हैं और कुछ को बिना छुए छोड़ा जा सकता है. एक ही कुंजी वाली नई प्रॉपर्टी जोड़ने पर, उसी कुंजी वाली सभी मौजूदा प्रॉपर्टी बदल जाएंगी. यहां दिए गए उदाहरण में, निजी प्रॉपर्टी सेट करने का तरीका बताया गया है:

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

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

प्रॉपर्टी मिटाना

अपडेट के अनुरोध में शामिल नहीं की गई किसी भी प्रॉपर्टी को मिटा दिया जाएगा. हालांकि, वैल्यू को शून्य पर सेट करने के लिए, पैच का अनुरोध करना बेहतर तरीका है. यहां दिए गए उदाहरण में, किसी निजी प्रॉपर्टी को मिटाने का तरीका बताया गया है:

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

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

खोज प्रॉपर्टी

Events.list अनुरोध का इस्तेमाल करके, इवेंट की एक्सटेंड की गई प्रॉपर्टी की वैल्यू के आधार पर इवेंट खोजे जा सकते हैं. propertyName=value फ़ॉर्मैट में, privateExtendedProperty या sharedExtendedProperty फ़ील्ड को किसी शर्त के तौर पर सेट करें. इससे निजी और शेयर की गई प्रॉपर्टी के हिसाब से खोज की जाती है. यहां दिया गया उदाहरण, निजी प्रॉपर्टी 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 प्रॉपर्टी हो सकती हैं. इनका कुल साइज़ 32 केबी (कुंजियों का साइज़ + वैल्यू का साइज़) तक हो सकता है. इन 300 प्रॉपर्टी में, इवेंट की सभी "कॉपी" में मौजूद शेयर की गई और निजी प्रॉपर्टी शामिल हैं.