تمت ترجمة هذه الصفحة بواسطة 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" هنا.

المناطق الزمنية

تحدد المنطقة الزمنية المنطقة التي تتبع توقيتًا قياسيًا موحدًا. في 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 يؤدي إلى إرفاق منطقة زمنية بالحدث، تمامًا عند تعيين منطقة زمنية للحدث باستخدام التقويم واجهة المستخدم:

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

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