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

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