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

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

تقویم‌ها

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

رویدادها

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

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

تقویم گوگل از رویدادهای تکی و تکرارشونده پشتیبانی می‌کند:

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

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

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

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

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

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

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

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

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

تقویم و فهرست تقویم

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

فهرست تقویم (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. رویدادی که از ساعت ۶ صبح تا ۷ صبح هر سه‌شنبه و جمعه اتفاق می‌افتد و از ۱۵ سپتامبر ۲۰۱۵ شروع می‌شود و پس از پنجمین رخداد در ۲۹ سپتامبر متوقف می‌شود:

   ...
   "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. یک رویداد تمام روز که از اول ژوئن ۲۰۱۵ آغاز می‌شود و هر ۳ روز در طول ماه تکرار می‌شود، به جز ۱۰ ژوئن اما شامل ۹ و ۱۱ ژوئن:

   ...
   "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 رویداد منعکس می‌شود).

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

مناطق زمانی

منطقه زمانی، منطقه‌ای را مشخص می‌کند که زمان استاندارد یکسانی را رعایت می‌کند. در 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 یک منطقه زمانی را به رویداد متصل می‌کند، درست مانند زمانی که یک منطقه زمانی رویداد را با استفاده از رابط کاربری تقویم تنظیم می‌کنید :

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

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