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

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

تقویم ها

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

رویدادها

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

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

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 تنظیم می‌کنید :

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

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

،

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

تقویم ها

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

رویدادها

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

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

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 تنظیم می‌کنید :

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

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

،

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

تقویم ها

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

رویدادها

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

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

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 تنظیم می‌کنید :

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

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

،

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

تقویم ها

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

رویدادها

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

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

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

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

مناطق زمانی

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

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

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

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

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

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

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

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