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

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

التقاويم

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

الفعاليات

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

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

يتيح "تقويم 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 هي الأكثر أهمية لأنّها تحدّد قاعدة عادية ل repetire الحدث. وتتألف من عدة مكونات. بعض منها:

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

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

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

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