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

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

किसको दिखे

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

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

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

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