التقاويم والأحداث

يوضّح هذا الدليل التقاويم والأحداث وعلاقتها ببعضها البعض.

التقاويم

التقويم هو مجموعة من الأحداث ذات الصلة، بالإضافة إلى بيانات وصفية إضافية مثل الملخّص والمنطقة الزمنية التلقائية والموقع الجغرافي وما إلى ذلك. يتم تحديد كل تقويم بمعرّف وهو عنوان بريد إلكتروني. يمكن أن يكون للتقاويم عدة مالكين.

الفعاليات

الحدث هو عنصر مرتبط بنطاق زمني أو تاريخ محدّد. يتم تحديد الأحداث من خلال رقم تعريف فريد. بالإضافة إلى تاريخ ووقت البدء والانتهاء، تحتوي الأحداث على بيانات أخرى، مثل الملخّص والوصف والموقع الجغرافي والحالة والتذكيرات والمرفقات وما إلى ذلك.

أنواع الأحداث

يتوافق "تقويم Google" مع الأحداث الفردية والمتكررة:

• يمثّل الحدث الواحد حالة فريدة.
• يحدّد الحدث المتكرّر عدة تكرارات.

يمكن أن تكون الأحداث أيضًا محدّدة بوقت أو على مدار اليوم:

• يحدث الحدث المحدّد بوقت بين نقطتين زمنيتين محدّدتين. تستخدم الأحداث المحدّدة المدة الحقلين start.dateTime وend.dateTime لتحديد وقت وقوعها.
• يمتد حدث اليوم الكامل ليوم كامل أو سلسلة متتالية من الأيام. تستخدم أحداث اليوم الكامل الحقلَين start.date وend.date لتحديد وقت حدوثها. يُرجى العِلم أنّ حقل المنطقة الزمنية ليس له أهمية بالنسبة إلى الأحداث التي تستغرق يومًا كاملاً.

جهات منظِّمة

تتضمّن الأحداث منظّمًا واحدًا وهو التقويم الذي يحتوي على النسخة الرئيسية من الحدث. يمكن أن تتضمّن الأحداث أيضًا ضيوفًا متعدّدين. يكون الضيف عادةً هو التقويم الأساسي لمستخدم تمت دعوته.

يوضّح المخطّط البياني التالي العلاقة المفاهيمية بين التقاويم والأحداث والعناصر الأخرى ذات الصلة:

التقاويم الأساسية والتقاويم الأخرى

التقويم الأساسي هو نوع خاص من التقاويم المرتبطة بحساب مستخدم واحد. يتم إنشاء هذا التقويم تلقائيًا لكل حساب مستخدم جديد، ويتطابق رقم تعريفه عادةً مع عنوان البريد الإلكتروني الأساسي للمستخدم. وطالما أنّ الحساب متوفّر، لا يمكن حذف تقويمه الأساسي أو إلغاء ملكية المستخدم له. ومع ذلك، سيظل بإمكانك مشاركته مع مستخدمين آخرين.

بالإضافة إلى التقويم الأساسي، يمكنك إنشاء أي عدد من التقاويم الأخرى بشكل صريح، ويمكن تعديل هذه التقاويم وحذفها ومشاركتها بين عدة مستخدمين.

التقويم وقائمة التقويم

تمثّل مجموعة التقاويم جميع التقاويم الحالية. ويمكن استخدامها لإنشاء التقاويم وحذفها. يمكنك أيضًا استرداد أو ضبط خصائص عامة تتم مشاركتها بين جميع المستخدمين الذين يمكنهم الوصول إلى تقويم. على سبيل المثال، عنوان التقويم والمنطقة الزمنية التلقائية هما من الخصائص العامة.

CalendarList هي مجموعة من جميع إدخالات التقويم التي أضافها المستخدم إلى قائمته (تظهر في اللوحة اليمنى من واجهة المستخدم على الويب). يمكنك استخدامها لإضافة تقاويم حالية إلى قائمة المستخدمين أو إزالتها منها. يمكنك أيضًا استخدامها لاسترداد وضبط قيم خصائص التقويم الخاصة بالمستخدم، مثل التذكيرات التلقائية. مثال آخر هو لون المقدّمة، إذ يمكن أن يضبط مستخدمون مختلفون ألوانًا مختلفة للتقويم نفسه.

يقارن الجدول التالي بين معنى العمليات للمجموعتين:

العملية	التقاويم	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. حدث يستمر ليوم كامل ويبدأ في 1 يونيو 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 لتحديد المنطقة الزمنية.

يمكنك أيضًا تحديد أوقات الأحداث بالتوقيت العالمي المنسّق إذا كنت تفضّل ذلك:

• حدِّد الوقت بالتوقيت العالمي المنسّق: 2017-01-25T14:00:00Z أو استخدِم معادلة صفر 2017-01-25T14:00:00+0000.

يكون التمثيل الداخلي لوقت الحدث هو نفسه في كل هذه الحالات، ولكن ضبط الحقل timeZone يؤدي إلى إرفاق منطقة زمنية بالحدث، تمامًا كما يحدث عند ضبط منطقة زمنية للحدث باستخدام واجهة مستخدم "تقويم Google":

المنطقة الزمنية للحدث المتكرّر

بالنسبة إلى الأحداث المتكرّرة، يجب دائمًا تحديد منطقة زمنية واحدة. وهي مطلوبة لتوسيع تكرارات الحدث.