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

इवेंट रिसॉर्स के फ़ील्ड में, इवेंट से जुड़ा सबसे आम डेटा शामिल होता है. जैसे, जगह और शुरू होने का समय. हालांकि, ऐप्लिकेशन को अपने इस्तेमाल के उदाहरण के लिए, अतिरिक्त मेटाडेटा सेव करने की ज़रूरत पड़ सकती है. 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 फ़ॉर्मैट में किसी कंस्ट्रेंट पर सेट करें. इससे, निजी और शेयर की गई प्रॉपर्टी के हिसाब से खोज की जाती है. यहां दिए गए उदाहरण में, 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 प्रॉपर्टी में, शेयर की गई और निजी प्रॉपर्टी शामिल हैं. ये प्रॉपर्टी, इवेंट की सभी कॉपी में मौजूद होती हैं.