ویژگی های توسعه یافته

فیلدهای منابع رویدادها، رایج‌ترین داده‌های مرتبط با یک رویداد، مانند مکان، زمان شروع و غیره را پوشش می‌دهند، اما برنامه‌ها ممکن است بخواهند فراداده‌های اضافی مختص به مورد استفاده خود را ذخیره کنند. API تقویم امکان تنظیم جفت‌های کلید-مقدار پنهان با یک رویداد را فراهم می‌کند که به آنها ویژگی‌های توسعه‌یافته می‌گویند. ویژگی‌های توسعه‌یافته، ذخیره داده‌های خاص برنامه برای یک رویداد را بدون نیاز به استفاده از یک پایگاه داده خارجی آسان می‌کنند.

قابلیت مشاهده

دو نوع ویژگی توسعه‌یافته وجود دارد: خصوصی و اشتراکی. ویژگی‌های اشتراکی توسط همه شرکت‌کنندگان در یک رویداد قابل مشاهده و ویرایش هستند، در حالی که ویژگی‌های خصوصی روی "کپی" محلی یک شرکت‌کننده از رویداد تنظیم می‌شوند. به طور دقیق‌تر، ویژگی‌های خصوصی مختص calendarId و eventId استفاده شده در درخواست هستند، در حالی که ویژگی‌های مشترک صرف نظر از calendarId استفاده شده در درخواست نمایش داده می‌شوند.

افزودن و به‌روزرسانی ویژگی‌ها

ویژگی‌های توسعه‌یافته روی منبع رویدادها تنظیم می‌شوند و مانند سایر فیلدها می‌توانند در درخواست‌های درج ، به‌روزرسانی و وصله تنظیم شوند. استفاده از درخواست‌های وصله روش ارجح است، زیرا به شما امکان می‌دهد برخی از ویژگی‌ها را دستکاری کنید در حالی که برخی دیگر دست نخورده باقی می‌مانند. اضافه کردن یک ویژگی جدید با همان کلید، هر ویژگی موجود با همان کلید را بازنویسی می‌کند. مثال زیر تنظیم یک ویژگی خصوصی را نشان می‌دهد:

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. حداکثر اندازه کلید یک ویژگی ۴۴ کاراکتر است و ویژگی‌هایی که کلیدهای طولانی‌تری دارند، بی‌صدا حذف می‌شوند.
2. حداکثر اندازه مقدار یک ویژگی ۱۰۲۴ کاراکتر است و ویژگی‌هایی که مقادیر طولانی‌تری دارند، به صورت بی‌صدا کوتاه می‌شوند.
3. یک رویداد می‌تواند تا ۳۰۰ ویژگی (property) با حجم کلی حداکثر ۳۲ کیلوبایت (اندازه کلیدها + اندازه مقدار) داشته باشد. این ۳۰۰ ویژگی شامل ویژگی‌های مشترک و خصوصی در تمام «کپی‌های» رویداد می‌شوند.