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

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

خدمات طباعة التقويم

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

فعاليات

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

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

يدعم "تقويم 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 أو UP لتحديد نهاية تكرار الحدث. لا تستخدِم كليهما في القاعدة نفسها.

• 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 لتحديد المنطقة الزمنية.

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

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

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

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

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

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