تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

فعاليات

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

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

يتيح "تقويم 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.

في ما يلي بعض الأمثلة على الأحداث المتكرّرة:

حدث يبدأ من الساعة 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"
],
…
```
حدث يستمر طوال اليوم يبدأ في 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":

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

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