يصف هذا الدليل التقاويم والأحداث وعلاقتها ببعضها البعض.
التقاويم
تقويم هي مجموعة من الأحداث ذات الصلة، إلى جانب بيانات وصفية إضافية مثل الملخص والمنطقة الزمنية التلقائية والموقع وما إلى ذلك، إلا أنه يتم تحديد كل تقويم باستخدام معرّف وهو عنوان بريد إلكتروني. يمكن أن يكون للتقاويم عدة مالكين.
فعاليات
حدث هو كائن مرتبط بتاريخ أو نطاق زمني محدد. يتمّ تحديد الأحداث باستخدام معرّف فريد. إلى جانب البداية تاريخ الانتهاء ووقته، وتحتوي الأحداث على بيانات أخرى مثل الملخص والوصف الموقع الجغرافي والحالة والتذكيرات والمرفقات وما إلى ذلك
أنواع الأحداث
يتيح "تقويم 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
.
في ما يلي بعض الأمثلة على الأحداث المتكرّرة:
حدث يبدأ من الساعة 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" هنا.
المناطق الزمنية
تحدد المنطقة الزمنية المنطقة التي تتبع توقيتًا قياسيًا موحدًا. في 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
يؤدي إلى إرفاق منطقة زمنية بالحدث، تمامًا
عند تعيين منطقة زمنية للحدث باستخدام التقويم
واجهة المستخدم:
المنطقة الزمنية للحدث المتكرر
بالنسبة إلى الأحداث المتكرّرة، يجب دائمًا تحديد منطقة زمنية واحدة. وهو مطلوب من أجل زيادة تكرار الحدث.