تقویم & مناسبت ها

این راهنما تقویم ها، رویدادها و رابطه آنها را با یکدیگر شرح می دهد.

تقویم ها

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

رویدادها

رویداد یک شیء مرتبط با یک محدوده زمانی یا تاریخ خاص است. رویدادها با یک شناسه منحصر به فرد شناسایی می شوند. علاوه بر تاریخ شروع و پایان، رویدادها حاوی داده‌های دیگری مانند خلاصه، توضیحات، مکان، وضعیت، یادآوری‌ها، پیوست‌ها و غیره هستند.

انواع رویدادها

Google Calendar از رویدادهای منفرد و تکراری پشتیبانی می کند:

• یک رویداد واحد نشان دهنده یک رخداد منحصر به فرد است.
• یک رویداد تکرار شونده چندین رخداد را تعریف می کند.

رویدادها همچنین ممکن است زمان بندی شده یا تمام روز باشند:

• یک رویداد زمان بندی شده بین دو نقطه خاص در زمان رخ می دهد. رویدادهای زمان‌دار از فیلدهای start.dateTime و end.dateTime برای تعیین زمان وقوع استفاده می‌کنند.
• یک رویداد تمام روز یک روز کامل یا مجموعه ای از روزهای متوالی را در بر می گیرد. رویدادهای تمام روز از فیلدهای start.date و end.date برای تعیین زمان وقوع استفاده می کنند. توجه داشته باشید که قسمت منطقه زمانی برای رویدادهای تمام روز اهمیتی ندارد.

برگزارکنندگان

رویدادها یک سازمان دهنده دارند که تقویم حاوی نسخه اصلی رویداد است. رویدادها همچنین می توانند چندین شرکت کننده داشته باشند. یک شرکت کننده معمولاً تقویم اصلی یک کاربر دعوت شده است.

نمودار زیر رابطه مفهومی بین تقویم‌ها، رویدادها و سایر عناصر مرتبط را نشان می‌دهد:

تقویم های اصلی و سایر تقویم ها

تقویم اولیه ، نوع خاصی از تقویم است که با یک حساب کاربری منفرد مرتبط است. این تقویم به طور خودکار برای هر حساب کاربری جدید ایجاد می شود و شناسه آن معمولاً با آدرس ایمیل اصلی کاربر مطابقت دارد. تا زمانی که حساب وجود داشته باشد، تقویم اصلی آن هرگز نمی تواند توسط کاربر حذف شود یا از مالکیت آن خارج شود. با این حال، هنوز هم می توان آن را با سایر کاربران به اشتراک گذاشت.

علاوه بر تقویم اصلی، می توانید به صراحت هر تعداد تقویم دیگر ایجاد کنید. این تقویم ها را می توان تغییر داد، حذف کرد و بین کاربران متعددی به اشتراک گذاشت.

تقویم و لیست تقویم

مجموعه تقویم ها همه تقویم های موجود را نشان می دهد. می توان از آن برای ایجاد و حذف تقویم استفاده کرد. همچنین می‌توانید ویژگی‌های جهانی را که در بین همه کاربران با دسترسی به تقویم به اشتراک گذاشته شده است، بازیابی یا تنظیم کنید. برای مثال، عنوان تقویم و منطقه زمانی پیش‌فرض، ویژگی‌های جهانی هستند.

CalendarList مجموعه ای از تمام ورودی های تقویم است که کاربر به لیست خود اضافه کرده است (در پانل سمت چپ رابط کاربری وب نشان داده شده است). می توانید از آن برای افزودن و حذف تقویم های موجود به/از لیست کاربران استفاده کنید. شما همچنین از آن برای بازیابی و تنظیم مقادیر ویژگی های تقویم خاص کاربر، مانند یادآورهای پیش فرض استفاده می کنید. مثال دیگر رنگ پیش زمینه است، زیرا کاربران مختلف می توانند رنگ های مختلفی را برای یک تقویم تنظیم کنند.

جدول زیر معنای عملیات را برای دو مجموعه مقایسه می کند:

عملیات	تقویم ها	فهرست تقویم
insert	یک تقویم ثانویه جدید ایجاد می کند. به طور پیش فرض، این تقویم نیز به لیست تقویم سازندگان اضافه می شود.	یک تقویم موجود را در لیست کاربر درج می کند.
delete	یک تقویم ثانویه را حذف می کند.	یک تقویم را از لیست کاربر حذف می کند.
get	فراداده های تقویم مانند عنوان، منطقه زمانی را بازیابی می کند.	فراداده به اضافه سفارشی سازی خاص کاربر مانند یادآوری رنگ یا لغو را بازیابی می کند.
patch / update	متادیتای تقویم را اصلاح می کند.	ویژگی های تقویم خاص کاربر را تغییر می دهد.

رویدادهای تکراری

برخی از رویدادها چندین بار در یک برنامه منظم رخ می دهند، مانند جلسات هفتگی، تولدها و تعطیلات. به غیر از داشتن زمان شروع و پایان متفاوت، این رویدادهای تکراری اغلب یکسان هستند.

رویدادها در صورتی تکرار شونده نامیده می شوند که طبق یک برنامه زمان بندی مشخص تکرار شوند. رویدادهای مجرد تکراری نیستند و فقط یک بار اتفاق می‌افتند.

قانون عود

برنامه زمانی یک رویداد تکراری در دو بخش تعریف شده است:

• فیلدهای شروع و پایان آن (که اولین رخداد را تعریف می کنند، گویی این فقط یک رویداد مجزا است)، و

• فیلد تکرار آن (که نحوه تکرار رویداد را در طول زمان مشخص می کند).

فیلد تکرار شامل آرایه‌ای از رشته‌ها است که نشان‌دهنده یک یا چند ویژگی RRULE ، RDATE یا EXDATE است که در RFC 5545 تعریف شده است.

ویژگی RRULE مهمترین است زیرا یک قانون منظم برای تکرار رویداد تعریف می کند. از چندین جزء تشکیل شده است. برخی از آنها عبارتند از:

• FREQ - دفعاتی که رویداد باید با آن تکرار شود (مانند DAILY یا WEEKLY ). مورد نیاز.

• INTERVAL - با FREQ کار می کند تا مشخص کند که رویداد چقدر باید تکرار شود. مثلا FREQ=DAILY;INTERVAL=2 یعنی هر دو روز یک بار.

• COUNT — تعداد دفعاتی که این رویداد باید تکرار شود.

• UNTIL - تاریخ یا تاریخ زمانی که رویداد باید تا آن زمان تکرار شود (شامل).

• BYDAY - روزهایی از هفته که رویداد باید در آنها تکرار شود ( SU ، MO ، TU ، و غیره). سایر اجزای مشابه عبارتند از BYMONTH ، BYYEARDAY ، و BYHOUR .

ویژگی RDATE تاریخ ها یا تاریخ-زمان های بیشتری را مشخص می کند که در آن رویداد باید رخ دهد. به عنوان مثال، RDATE;VALUE=DATE:19970101,19970120 . از این برای اضافه کردن رخدادهای اضافی که توسط RRULE پوشش داده نشده اند استفاده کنید.

ویژگی EXDATE مشابه RDATE است، اما تاریخ یا زمان‌هایی را مشخص می‌کند که رویداد نباید رخ دهد. یعنی آن اتفاقات باید کنار گذاشته شود. این باید به یک نمونه معتبر ایجاد شده توسط قانون تکرار اشاره کند.

EXDATE و RDATE می توانند یک منطقه زمانی داشته باشند و باید تاریخ (نه تاریخ-زمان) رویدادهای تمام روز باشند.

هر یک از ویژگی ها ممکن است چندین بار در فیلد بازگشت رخ دهد. تکرار به عنوان اتحاد همه قوانین RRULE و RDATE ، منهای آنهایی که توسط همه قوانین EXDATE حذف شده اند، تعریف می شود.

در اینجا چند نمونه از رویدادهای مکرر آورده شده است:

1. رویدادی که از ساعت 6 صبح تا 7 صبح هر سه‌شنبه و جمعه از 15 سپتامبر 2015 شروع می‌شود و پس از وقوع پنجم در 29 سپتامبر متوقف می‌شود:

   ...
   "start": {
    "dateTime": "2015-09-15T06:00:00+02:00",
    "timeZone": "Europe/Zurich"
   },
   "end": {
    "dateTime": "2015-09-15T07:00:00+02:00",
    "timeZone": "Europe/Zurich"
   },
   "recurrence": [
    "RRULE:FREQ=WEEKLY;COUNT=5;BYDAY=TU,FR"
   ],
   …
   

2. رویدادی تمام روز که از اول ژوئن 2015 شروع می‌شود و هر 3 روز یک‌بار در طول ماه تکرار می‌شود، به استثنای 10 ژوئن، اما شامل 9 و 11 ژوئن:

   ...
   "start": {
    "date": "2015-06-01"
   },
   "end": {
    "date": "2015-06-02"
   },
   "recurrence": [
    "EXDATE;VALUE=DATE:20150610",
    "RDATE;VALUE=DATE:20150609,20150611",
    "RRULE:FREQ=DAILY;UNTIL=20150628;INTERVAL=3"
   ],
   …
   

موارد و استثنائات

یک رویداد تکرار شونده از چندین نمونه تشکیل شده است: رخدادهای خاص آن در زمان های مختلف. این موارد خود به عنوان رویداد عمل می کنند.

اصلاحات تکرارشونده رویداد می‌تواند بر کل رویداد تکرارشونده (و همه نمونه‌های آن) یا فقط بر نمونه‌های فردی تأثیر بگذارد. مواردی که با رویداد تکرار شونده والدشان متفاوت است، استثنا نامیده می شوند.

برای مثال، یک استثنا ممکن است خلاصه متفاوتی داشته باشد، زمان شروع متفاوتی داشته باشد، یا شرکت‌کنندگان اضافی فقط به آن نمونه دعوت شده باشند. همچنین می‌توانید یک نمونه را به طور کامل بدون حذف رویداد تکرارشونده لغو کنید (لغوهای نمونه در status رویداد منعکس می‌شوند).

نمونه‌هایی از نحوه کار با رویدادها و نمونه‌های تکرارشونده از طریق Google Calendar API را می‌توانید در اینجا پیدا کنید.

مناطق زمانی

منطقه زمانی منطقه ای را مشخص می کند که یک زمان استاندارد یکنواخت را رعایت می کند. در Google Calendar API، مناطق زمانی را با استفاده از شناسه‌های منطقه زمانی IANA مشخص می‌کنید.

می توانید منطقه زمانی را برای تقویم ها و رویدادها تنظیم کنید. بخش های زیر اثرات این تنظیمات را شرح می دهند.

منطقه زمانی تقویم

منطقه زمانی تقویم نیز به عنوان منطقه زمانی پیش‌فرض شناخته می‌شود زیرا پیامدهای آن برای نتایج پرس و جو دارد. منطقه زمانی تقویم بر نحوه تفسیر یا ارائه مقادیر زمانی توسط متدهای events.get() ، events.list() و events.instances() تاثیر می گذارد.

نتیجه پرس و جو تبدیل منطقه زمانی

نتایج متدهای get() ، list() و instances() در منطقه زمانی که در پارامتر timeZone مشخص کرده‌اید برگردانده می‌شوند. اگر این پارامتر را حذف کنید، این روش ها همه از منطقه زمانی تقویم به عنوان پیش فرض استفاده می کنند.

تطبیق رویدادهای تمام روز با جستارهای زمانی

متدهای list() و instances() به شما امکان می دهند فیلترهای زمان شروع و پایان را مشخص کنید، با روشی که نمونه هایی را که در محدوده مشخص شده قرار می گیرند برمی گرداند. منطقه زمانی تقویم برای محاسبه زمان شروع و پایان رویدادهای تمام روز استفاده می شود تا مشخص شود که آیا آنها در مشخصات فیلتر قرار دارند یا خیر.

منطقه زمانی رویداد

نمونه‌های رویداد دارای زمان شروع و پایان هستند. مشخصات این زمان ها ممکن است شامل منطقه زمانی باشد. شما می توانید منطقه زمانی را به چند روش مشخص کنید. موارد زیر همگی زمان را مشخص می کنند:

• یک افست منطقه زمانی را در قسمت dateTime اضافه کنید، برای مثال 2017-01-25T09:00:00-0500 .
• زمانی را بدون افست مشخص کنید، برای مثال 2017-01-25T09:00:00 ، فیلد timeZone خالی بگذارید (این به طور ضمنی از منطقه زمانی پیش‌فرض استفاده می‌کند).
• زمان را بدون افست مشخص کنید، برای مثال 2017-01-25T09:00:00 ، اما از قسمت timeZone برای تعیین منطقه زمانی استفاده کنید.

در صورت تمایل می توانید زمان رویداد را در UTC نیز مشخص کنید:

• زمان را در UTC مشخص کنید: 2017-01-25T14:00:00Z یا از یک افست صفر 2017-01-25T14:00:00+0000 استفاده کنید.

نمایش داخلی زمان رویداد در همه این موارد یکسان است، اما تنظیم فیلد timeZone یک منطقه زمانی را به رویداد متصل می‌کند، درست مانند زمانی که یک منطقه زمانی رویداد را با استفاده از Calendar UI تنظیم می‌کنید :

منطقه زمانی رویداد تکرارشونده

برای رویدادهای تکرار شونده همیشه باید یک منطقه زمانی مشخص شود. به منظور گسترش عود رویداد مورد نیاز است.