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

فیلدهای منابع رویدادها متداول‌ترین داده‌های مرتبط با یک رویداد مانند مکان، زمان شروع و غیره را پوشش می‌دهند، اما برنامه‌ها ممکن است بخواهند ابرداده‌های اضافی را مخصوص مورد استفاده خود ذخیره کنند. Calendar 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. حداکثر اندازه کلید یک ویژگی 44 کاراکتر است و ویژگی‌های دارای کلیدهای طولانی‌تر بی‌صدا حذف می‌شوند.
2. حداکثر اندازه مقدار یک ویژگی 1024 کاراکتر است و خواص با مقادیر طولانی‌تر به‌طور بی‌صدا کوتاه می‌شوند.
3. یک رویداد می‌تواند حداکثر 300 ویژگی داشته باشد که مجموعاً تا 32 کیلوبایت اندازه دارند (اندازه کلید + اندازه مقدار). این 300 ملک شامل دارایی های مشترک و خصوصی، در تمام "کپی ها" رویداد است.