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

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

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

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

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

يتم عرض جميع الأحداث مع eventType.
يجب ضبط eventType عند إنشاء مورد حدث أو تعديله. في حال عدم ضبطها، سيتم استخدام النوع 'default'.
يمكن تحديد eventTypes في طلب Events:list لعرض قائمة بأحداث من أنواع معيّنة. في حال عدم تحديد نوع، سيتم عرض جميع أنواع الأحداث.
يمكن تحديد eventTypes في طلب Events:watch للاشتراك في تلقّي إشعارات بشأن أحداث من أنواع معيّنة. في حال عدم تحديد أي نوع، سيؤدي الطلب إلى الاشتراك في جميع أنواع الأحداث.

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

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

راجِع مقالة إنشاء أحداث لبدء العمل مع أحداث "تقويم Google".

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

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

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

تتيح واجهة برمجة تطبيقات "تقويم Google" استخدام الطرق get وinstances وlist لقراءة أحداث أعياد الميلاد. يمكن ضبط eventTypes على 'birthday' لعرض أحداث أعياد الميلاد فقط. في حال عدم تحديد نوع، سيتم إدراج أعياد الميلاد بجانب جميع أنواع الأحداث الأخرى.

في عناصر Event التي تم إرجاعها، افحص الحقل birthdayProperties للحصول على مزيد من التفاصيل حول هذا الحدث الخاص. يحتوي birthdayProperties على الحقول التالية:

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

تتيح واجهة برمجة التطبيقات إنشاء أحداث أعياد الميلاد باستخدام طريقة 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 لأحداث أعياد الميلاد باستخدام الطريقتَين update وpatch. يمكن أيضًا تعديل الحقلَين start وend لتغيير تاريخ الحدث. في هذه الحالة، يجب أن تحدّد القيم الجديدة حدثًا يستمر ليوم كامل ويستغرق يومًا واحدًا بالضبط. لا يمكن تعديل تفاصيل توقيت حدث عيد ميلاد إذا كان الحدث مرتبطًا contact أو إذا كان type هو 'self'.

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

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

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

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

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

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

أحداث من Gmail

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

لا تتيح Google Calendar API إنشاء هذا النوع من الأحداث باستخدام الطريقة insert.

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

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

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

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

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

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

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

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

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

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

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

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

أنشئ نصًا برمجيًا من خلال الانتقال إلى script.google.com/create.
في اللوحة اليمنى بجانب الخدمات، انقر على "إضافة خدمة" .
اختَر Google Calendar API وانقر على إضافة.
بعد تفعيل واجهة برمجة التطبيقات، ستظهر في اللوحة اليمنى. يمكن إدراج الطرق والفئات المتاحة في واجهة برمجة التطبيقات باستخدام الكلمة الرئيسية Calendar في المحرّر.

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

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

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

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

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

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 لاسترداد معرّفات الأحداث.

تشغيل عيّنة التعليمات البرمجية

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