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

تشرح هذه الصفحة السمة eventType ومواصفات أنواع الأحداث المتاحة في Google Calendar API.

يتيح "تقويم Google" للمستخدمين إنشاء أحداث عامة، بالإضافة إلى أحداث مصمّمة لحالات استخدام معيّنة وسمات مخصّصة.

يمكنك الاطّلاع على نوع الحدث في المواضع التالية في واجهة برمجة التطبيقات:

• تعرِض جميع الأحداث eventType.
• يمكنك ضبط eventType عند إنشاء مورد حدث أو تعديله. إذا لم يتم ضبطه، تستخدِم واجهة برمجة التطبيقات القيمة 'default'.
• يمكنك تحديد eventTypes في طلب events.list لعرض أحداث من أنواع معيّنة. إذا لم يتم تحديد أي نوع، تعرِض واجهة برمجة التطبيقات جميع أنواع الأحداث.
• يمكنك تحديد eventTypes في طلب events.watch للاشتراك في آخر المستجدات حول أحداث من أنواع معيّنة. إذا لم يتم تحديد أي نوع، يشترك الطلب في جميع أنواع الأحداث.

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

الحدث التلقائي

يتم إنشاء الأحداث التي تحمل نوع الحدث default واستخدامها كأحد الموارد الرئيسية في Calendar API. وهي تتيح مجموعة كبيرة من السمات لتخصيص الحدث بشكل أكبر.

يمكنك الاطّلاع على إنشاء الأحداث لبدء استخدام أحداث "تقويم Google".

تاريخ الميلاد

أعياد الميلاد هي أحداث خاصة تستغرق يومًا كاملاً وتتكرّر سنويًا.

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

تتيح Calendar API الطرق events.get و events.instances و events.list لقراءة أحداث أعياد الميلاد. يمكنك ضبط eventTypes على 'birthday' لعرض أحداث أعياد الميلاد فقط. إذا لم يتم تحديد أي نوع، يعرِض الردّ أعياد الميلاد إلى جانب جميع أنواع الأحداث الأخرى.

في الكائنات Event التي يتم عرضها، يمكنك الاطّلاع على الحقل birthdayProperties لمزيد من التفاصيل حول هذا الحدث الخاص. يحتوي birthdayProperties على الحقول التالية:

• type: نوع هذا الحدث الخاص، سواء كان عيد ميلاد أو ذكرى سنوية أو تاريخًا مهمًا آخر.
• customTypeName: التصنيف الذي يحدّده المستخدم لهذا الحدث الخاص. يتم ملء هذا الحقل إذا تم ضبط type على 'custom'.
• contact: اسم مورد جهة الاتصال المرتبطة بهذا الحدث الخاص، إن وُجدت. يكون هذا بالتنسيق 'people/c12345' ويمكن استخدامه لجلب تفاصيل جهة الاتصال من People API.

تتيح لك واجهة برمجة التطبيقات إنشاء أحداث أعياد الميلاد باستخدام الطريقة events.insert مع المواصفات التالية:

• eventType تم ضبطه على 'birthday'.
• start و end يجب أن يحدّد الحقلان حدثًا يستغرق يومًا كاملاً ويومًا واحدًا فقط.
• يجب أن تكون قيمة الحقل visibility هي 'private'.
• يجب أن تكون قيمة الحقل transparency هي 'transparent'.
• يجب أن يكون الحدث متكرّرًا سنويًا، ما يعني أنّ الحقل recurrence يجب أن يكون 'RRULE:FREQ=YEARLY'. يجب أن تتضمّن أحداث أعياد الميلاد التي تحدث في 29 فبراير قاعدة التكرار التالية: 'RRULE:FREQ=YEARLY;BYMONTH=2;BYMONTHDAY=-1'.
• يمكن أن يتضمّن الحدث colorId و summary و reminders.
• يمكن أن يتضمّن الحدث birthdayProperties. إذا تم تحديدها، type يجب أن يكون 'birthday'، ويجب أن يكون كل من customTypeName و contact فارغَين.
• لا يمكن أن يتضمّن الحدث أي سمات أخرى.

تتيح لك واجهة برمجة التطبيقات تعديل الـ colorId والـ summary والـ reminders لأحداث أعياد الميلاد باستخدام الطريقتَين events.update و events.patch. يمكنك أيضًا تعديل الحقلَين start و end لتغيير تاريخ الحدث. في هذه الحالة، يجب أن تحدّد القيم الجديدة حدثًا يستغرق يومًا كاملاً ويومًا واحدًا فقط. لا يمكن تعديل تفاصيل توقيت حدث عيد الميلاد إذا كان الحدث مرتبطًا بـ contact أو إذا كان type هو 'self'.

لا تسمح Calendar API بإنشاء أحداث أعياد الميلاد باستخدام birthdayProperties مخصّصة أو تعديل هذه السمات. يمكن تعديل التواريخ المهمة باستخدام People API، وتتم مزامنة التغييرات مع تقويم Google. وبالمثل، يمكن للمستخدمين تعديل تاريخ ميلادهم في ملفاتهم الشخصية على حساباتهم على Google، وتتم مزامنته مع "تقويم Google".

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

تتيح واجهة برمجة التطبيقات عملية events.import لأحداث أعياد الميلاد، ولكن يتم استيراد الحدث كحدث تلقائي. بعبارة أخرى، سيكون eventType هو 'default'.

تتيح واجهة برمجة التطبيقات الطريقة events.watch للاشتراك في التغييرات التي تطرأ على أحداث أعياد الميلاد في "تقويم Google" . يمكنك ضبط eventTypes على 'birthday' للاشتراك في آخر المستجدات حول أحداث أعياد الميلاد. إذا لم يتم تحديد أي نوع، يشترك الطلب في جميع أنواع الأحداث، بما في ذلك أعياد الميلاد.

يمكنك حذف أحداث أعياد الميلاد باستخدام الطريقة events.delete في Calendar API. لن يؤثر حذف حدث عيد ميلاد من "تقويم Google" في البيانات على "جهات اتصال Google" أو الملف الشخصي على حساب Google.

لا يمكن تغيير منظِّم حدث عيد ميلاد باستخدام الطريقتَين events.move أو events.update.

أحداث من Gmail

الأحداث التي يتم إنشاؤها تلقائيًا من Gmail لها نوع الحدث 'fromGmail'.

لا تسمح Calendar API بإنشاء هذا النوع من الأحداث باستخدام الـ events.insert.

تتيح لك واجهة برمجة التطبيقات تعديل السمات الممتدة colorId و reminders و visibility و transparency و status و attendees و private و و shared باستخدام الطريقتَين events.update و events.patch.

تتيح واجهة برمجة التطبيقات الطريقتَين events.get و events.list لقراءة الأحداث من Gmail. يمكنك ضبط eventTypes على 'fromGmail' لعرض الأحداث التي تم إنشاؤها من Gmail فقط. إذا لم يتم تحديد أي نوع، يتم عرض الأحداث من Gmail إلى جانب جميع أنواع الأحداث الأخرى.

تتيح واجهة برمجة التطبيقات الطريقة events.watch للاشتراك في التغييرات التي تطرأ على الأحداث من Gmail في "تقويم Google". إذا لم يتم تحديد أي نوع، يشترك الطلب في جميع أنواع الأحداث، بما في ذلك 'fromGmail'.

يمكنك حذف الأحداث من Gmail باستخدام الطريقة events.delete في Calendar API.

لا يمكن تغيير منظِّم حدث من Gmail باستخدام الطريقتَين events.move أو events.update methods is not supported.

وقت التركيز والحالة "خارج المكتب" ومكان العمل

يمكنك استخدام Calendar API لإنشاء الأحداث التي تعرض حالة مستخدمي "تقويم Google" وإدارتها.

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

استكشاف أنواع الأحداث في "برمجة تطبيقات Google"

"برمجة تطبيقات Google هي لغة برمجة نصية مستندة إلى السحابة الإلكترونية تستند إلى JavaScript وتتيح لك إنشاء تطبيقات تجارية تتكامل مع Google Workspace." يتم تطوير النصوص البرمجية في أداة تعديل الرموز المستندة إلى المتصفح، ويتم تخزينها وتشغيلها على خوادم Google. يمكنك أيضًا الاطّلاع على دليل البدء السريع في برمجة تطبيقات Google لبدء استخدام برمجة تطبيقات Google لإرسال طلبات إلى Calendar API.

توضّح التعليمات التالية كيفية قراءة الأحداث وإدارتها باستخدام الـ Calendar API كخدمة متقدّمة في "برمجة تطبيقات Google". للاطّلاع على قائمة كاملة بموارد Calendar API وطُرقها، يمكنك الرجوع إلى المستندات المرجعية.

إنشاء النص البرمجي وإعداده

1. يمكنك إنشاء نص برمجي من خلال الانتقال إلى script.google.com/create.
2. في اللوحة اليمنى بجانب الخدمات ، انقر على إضافة خدمة .
3. اختَر Calendar API وانقر على إضافة.
4. بعد تفعيل واجهة برمجة التطبيقات، ستظهر في اللوحة اليمنى. يمكنك عرض الطُرق والفئات المتاحة في واجهة برمجة التطبيقات من خلال كتابة Calendar في أداة التعديل.

(اختياري) تعديل مشروع Cloud

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

إضافة الرمز البرمجي إلى النص البرمجي

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

1. ألصِق ما يلي في أداة تعديل الرموز.

   const CALENDAR_ID = 'CALENDAR_ID' || 'primary';
   
   /** Lists default events. */
   function listDefaultEvents() {
     listEvents('default');
   }
   
   /** Lists birthday events. */
   function listBirthdays() {
     listEvents('birthday');
   }
   
   /** Lists events from Gmail. */
   function listEventsFromGmail() {
     listEvents('fromGmail');
   }
   
   /**
     * Lists events with the given event type. If no type is specified, lists all events.
     * See https://developers.google.com/workspace/calendar/api/v3/reference/events/list
     */
   function listEvents(eventType = undefined) {
     // Query parameters for the list request.
     const optionalArgs = {
       eventTypes: eventType ? [eventType] : undefined,
       singleEvents: true,
       timeMax: '2024-07-30T00:00:00+01:00',
       timeMin: '2024-07-29T00:00:00+01:00',
     }
     try {
       var response = Calendar.Events.list(CALENDAR_ID, optionalArgs);
       response.items.forEach(event => console.log(event));
     } catch (exception) {
       console.log(exception.message);
     }
   }
   
   /**
     * Reads the event with the given eventId.
     * See https://developers.google.com/workspace/calendar/api/v3/reference/events/get
     */
   function readEvent() {
     try {
       var response = Calendar.Events.get(CALENDAR_ID, 'EVENT_ID');
       console.log(response);
     } catch (exception) {
       console.log(exception.message);
     }
   }
   
   /** Creates a default event. */
   function createDefaultEvent() {
     const event = {
       start: { dateTime: '2024-07-30T10:30:00+01:00'},
       end: { dateTime: '2024-07-30T12:30:00+01:00'},
       description: 'Created from Apps Script.',
       eventType: 'default',
       summary: 'Sample event',
     }
     createEvent(event);
   }
   
   /** Creates a birthday event. */
   function createBirthday() {
     const event = {
       start: { date: '2024-01-29' },
       end: { date: '2024-01-30' },
       eventType: 'birthday',
       recurrence: ["RRULE:FREQ=YEARLY"],
       summary: "My friend's birthday",
       transparency: "transparent",
       visibility: "private",
     }
     createEvent(event);
   }
   
   /**
     * Creates a Calendar event.
     * See https://developers.google.com/workspace/calendar/api/v3/reference/events/insert
     */
   function createEvent(event) {
   
     try {
       var response = Calendar.Events.insert(event, CALENDAR_ID);
       console.log(response);
     } catch (exception) {
       console.log(exception.message);
     }
   }
   

   غيِّر القيم في السلسلة على الشكل التالي:

   • CALENDAR_ID: عنوان البريد الإلكتروني للتقويم الذي تريد استرداد الأحداث منه وإنشاؤها فيه. يتم ضبط هذا الثابت في البداية على 'primary'، وهي كلمة رئيسية للوصول إلى التقويم الأساسي للمستخدم الذي سجّل الدخول. يتيح لك تغيير هذه القيمة قراءة الأحداث في تقاويم المستخدمين الآخرين الذين يمكنك الوصول إليهم.
   • EVENT_ID: معرّف الحدث. يمكنك طلب events.list لاسترداد معرّفات الأحداث.

تشغيل نموذج الرمز البرمجي

1. في أعلى أداة تعديل الرموز، اختَر الدالة التي تريد تشغيلها من القائمة المنسدلة، ثم انقر على تشغيل.
2. في المرة الأولى التي تشغّل فيها النص البرمجي، سيُطلب منك منح الإذن بالوصول. راجِع إذن الوصول إلى تقويمك في "برمجة تطبيقات Google" وامنحه.
3. يمكنك الاطّلاع على نتائج تنفيذ النص البرمجي في سجلّ التنفيذ الذي يظهر في أسفل النافذة.