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

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

التقاويم

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

الفعاليات

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

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

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

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

يمكن أن تكون الأحداث أيضًا موقّتة أو طوال اليوم:

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

يجب أن يكون بدء الحدث وانتهاؤه محدّدَين بالوقت أو أن يكونا طوال اليوم. على سبيل المثال، ليس من الصحيح تحديد start.date وend.dateTime.

جهات منظِّمة

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

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

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

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

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

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

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

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

يقارن الجدول التالي معنى العمليات في كلتا الجموعتَين:

العملية	التقاويم	CalendarList
insert	لإنشاء تقويم ثانوي جديد. تتم أيضًا إضافة هذا التقويم تلقائيًا إلى قائمة التقاويم الخاصة بصانع المحتوى.	تُستخدَم هذه السمة لإدراج تقويم حالي في قائمة المستخدم.
delete	لحذف تقويم ثانوي	تزيل تقويمًا من قائمة المستخدم.
get	استرداد البيانات الوصفية للتقويم، مثل العنوان والمنطقة الزمنية	استرداد البيانات الوصفية بالإضافة إلى التخصيص الخاص بالمستخدم مثل اللون أو إلغاء التذكيرات
patch/update	تعديل البيانات الوصفية للتقويم	تعديل سمات التقويم الخاصة بالمستخدم

الأحداث المتكرّرة

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

تُسمى الأحداث متكرّرة إذا كانت تتكرّر وفقًا لجدول زمني محدّد. الأحداث الفردية غير متكرّرة وتقع مرة واحدة فقط.

قاعدة التكرار

يتم تحديد الجدول الزمني لحدث متكرر في جزأين:

• حقلَي البدء والانتهاء (اللذان يحدّدان أول مرّة حدوث، كما لو كان هذا حدثًا فرديًا مستقلاً فقط)

• حقل التكرار (الذي يحدّد كيفية تكرار الحدث بمرور الوقت)

يحتوي حقل التكرار على صفيف من السلاسل التي تمثّل سمة واحدة أو عدة سمات RRULE أو RDATE أو EXDATE كما هو محدّد في RFC 5545.

السمة RRULE هي الأكثر أهمية لأنّها تحدّد قاعدة منتظمة ل تكرار الحدث. وتتألف من عدة مكونات. في ما يلي بعض هذه الشروط:

• ‫FREQ: معدّل تكرار الحدث (مثل DAILY أو WEEKLY). مطلوب.

• ‫INTERVAL: تعمل مع FREQ لتحديد عدد المرات التي يجب فيها تكرار الحدث. على سبيل المثال، يعني FREQ=DAILY;INTERVAL=2 مرة واحدة كل يومَين.

• COUNT: عدد المرات التي يجب تكرار هذا الحدث فيها

  يمكنك استخدام COUNT أو UNTIL لتحديد نهاية تكرار الحدث. ولا تستخدِم كليهما في القاعدة نفسها.

• 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":

بالنسبة إلى الأحداث الفردية، يمكنك تحديد مناطق زمنية مختلفة لوقتَي بدء الفعالية وانتهائها. (يمكن أن يساعد ذلك في الأحداث التي تبدأ وتنتهي في مناطق زمنية مختلفة، مثل السفر). بالنسبة إلى الأحداث المتكررة، راجِع ما يلي.

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

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