Events: insert

تنشئ هذه السمة حدثًا. جرِّبها الآن.

طلب

طلب HTTP

POST https://www.googleapis.com/calendar/v3/calendars/calendarId/events

المعلمات

اسم المعلَمة القيمة الوصف
مَعلمات المسار
calendarId string معرّف التقويم لاسترداد أرقام تعريف التقويم، استخدِم طريقة calendarList.list. إذا أردت الوصول إلى التقويم الأساسي للمستخدم الذي سجّل الدخول حاليًا، استخدِم الكلمة الرئيسية "primary".
مَعلمات طلب البحث الاختيارية
conferenceDataVersion integer رقم إصدار بيانات المؤتمر المتوافق مع عميل واجهة برمجة التطبيقات. لا تفترض الإصدار 0 إمكانية استخدام بيانات المؤتمر وتتجاهل بيانات المؤتمر في نص الحدث. يتيح الإصدار 1 إمكانية نسخ ConferenceData بالإضافة إلى إنشاء مكالمات فيديو جديدة باستخدام حقل createRequest في conferenceData. القيمة التلقائية هي 0. القيم المقبولة هي من 0 إلى 1، بشكلٍ شامل.
eventLabelVersion integer رقم إصدار ميزة تصنيف الأحداث المتوافق مع عميل واجهة برمجة التطبيقات. لا يفترض الإصدار 0 توفّر دعم لتصنيف الأحداث، ويعالج الحقل colorId لإدارة الألوان. يتيح الإصدار 1 إمكانية استخدام تصنيفات الأحداث، ويعالج eventLabelId في نص الحدث. في هذه الحالة، يتم تجاهل الحقل colorId. القيمة التلقائية هي 0. القيم المقبولة هي من 0 إلى 1، بشكلٍ شامل.
maxAttendees integer الحدّ الأقصى لعدد الضيوف الذين سيتم تضمينهم في الردّ إذا كان هناك عدد أكبر من المشاركين المحدّد، سيتم عرض المشارك فقط. اختياريّ.
sendNotifications boolean تمّ الإيقاف. يُرجى استخدام sendUpdates بدلاً من ذلك.

تحديد ما إذا كان سيتم إرسال إشعارات بشأن إنشاء الحدث الجديد. يُرجى العِلم أنّه قد يتم إرسال بعض الرسائل الإلكترونية حتى إذا ضبطت القيمة على false. القيمة التلقائية هي false.
sendUpdates string تحديد ما إذا كان سيتم إرسال إشعارات بشأن إنشاء الحدث الجديد يُرجى العِلم أنّه قد يستمر إرسال بعض الرسائل الإلكترونية. القيمة التلقائية هي false.

القيم المقبولة هي:
  • "all": يتم إرسال الإشعارات إلى جميع الضيوف.
  • "externalOnly": يتم إرسال الإشعارات إلى المدعوّين الذين لا يستخدمون "تقويم Google" فقط.
  • "none": لا يتم إرسال أي إشعارات.
supportsAttachments boolean تحديد ما إذا كان عميل واجهة برمجة التطبيقات الذي ينفّذ العملية يتيح إرفاق أحداث. اختياريّ. القيمة التلقائية هي False.

التفويض

يتطلّب هذا الطلب الحصول على تفويض باستخدام نطاق واحد على الأقل من النطاقات التالية:

النطاق
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/calendar.app.created
https://www.googleapis.com/auth/calendar.events.owned

لمزيد من المعلومات، يُرجى الاطّلاع على صفحة المصادقة والتفويض.

نص الطلب

في نص الطلب، قدِّم مورد أحداث مع السمات التالية:

اسم السمة القيمة الوصف ملاحظات
السمات المطلوبة
end nested object تمثّل هذه السمة وقت انتهاء الحدث (غير شامل). بالنسبة إلى حدث متكرّر، هذا هو وقت انتهاء النسخة الأولى.
start nested object وقت بدء الحدث (شامل) بالنسبة إلى حدث متكرّر، هذا هو وقت بدء المرة الأولى.
السمات الاختيارية
anyoneCanAddSelf boolean تحديد ما إذا كان بإمكان أي مستخدم دعوة نفسه إلى الحدث (تم إيقاف هذه السمة نهائيًا). اختياريّ. القيمة التلقائية هي False. قابل للكتابة
attachments[].fileUrl string رابط URL للمرفق

لإضافة مرفقات ملفات Google Drive، استخدِم التنسيق نفسه المستخدَم في السمة alternateLink الخاصة بمورد Files في Drive API.

مطلوب عند إضافة مرفق.

 قابل للكتابة
attendees[] list تمثّل هذه السمة المشاركين في الحدث. لمزيد من المعلومات حول جدولة الأحداث مع مستخدمي تقويم آخرين، يمكنك الاطّلاع على دليل الأحداث التي تضم ضيوفًا. يجب أن تستخدم حسابات الخدمة تفويضًا على مستوى النطاق لملء قائمة المشاركين. قابل للكتابة
attendees[].additionalGuests integer عدد الضيوف الإضافيين اختياريّ. القيمة التلقائية هي 0. قابل للكتابة
attendees[].comment string تعليق رد الضيف اختياريّ. قابل للكتابة
attendees[].displayName string تمثّل هذه السمة اسم المشارك، إذا كان ذلك متاحًا. اختياريّ. قابل للكتابة
attendees[].email string عنوان البريد الإلكتروني للمدعوين، إذا كان متاحًا يجب أن يكون هذا الحقل متوفّرًا عند إضافة أحد المشاركين. يجب أن يكون عنوان بريد إلكتروني صالحًا وفقًا RFC5322.

هذه السمة مطلوبة عند إضافة ضيف.

 قابل للكتابة
attendees[].optional boolean توضّح هذه السمة ما إذا كان الضيف اختياريًا. اختياريّ. القيمة التلقائية هي False. قابل للكتابة
attendees[].resource boolean تُستخدَم لتحديد ما إذا كان المشارِك عبارة عن مورد. لا يمكن ضبط هذا الخيار إلا عند إضافة الضيف إلى الحدث للمرة الأولى. ويتم تجاهل التعديلات اللاحقة. اختياريّ. القيمة التلقائية هي False. قابل للكتابة
attendees[].responseStatus string تمثّل هذه السمة حالة ردّ الضيف. القيم المحتمَلة هي:
  • needsAction": لم يستجب المشارِك للدعوة (يُنصح به للأحداث الجديدة).
  • "declined": رفض الضيف الدعوة.
  • tentative": قبل المشارِك الدعوة مبدئيًا.
  • accepted": قبِل المشارِك الدعوة.
 قابل للكتابة
birthdayProperties nested object بيانات أعياد الميلاد أو المناسبات الخاصة يجب استخدامها إذا كانت قيمة eventType هي "birthday". غير قابل للتغيير قابل للكتابة
birthdayProperties.type string نوع عيد الميلاد أو المناسبة الخاصة القيم المحتمَلة هي:
  • ‫"anniversary": ذكرى سنوية غير عيد الميلاد يحتوي دائمًا على contact.
  • ‫"birthday": حدث عيد ميلاد هذه هي القيمة الافتراضية.
  • ‫"custom": تاريخ خاص يتم تحديد تصنيفه بشكل أكبر في الحقل customTypeName. يحتوي دائمًا على contact.
  • ‫"other" - تاريخ خاص لا يندرج ضمن الفئات الأخرى، وليس له تصنيف مخصّص. يحتوي دائمًا على contact.
  • ‫"self": عيد ميلاد مالك التقويم لا يمكن أن يتضمّن contact.
تتيح Calendar API إنشاء أحداث من النوع "birthday" فقط. لا يمكن تغيير النوع بعد إنشاء الحدث.		 قابل للكتابة
colorId string تمثّل هذه السمة لون الحدث. هذا هو رقم التعريف الذي يشير إلى إدخال في القسم event من تعريف الألوان (راجِع نقطة نهاية الألوان). اختياريّ. قابل للكتابة
conferenceData nested object المعلومات المتعلّقة بالمؤتمر، مثل تفاصيل مؤتمر Google Meet لإنشاء تفاصيل مؤتمر جديدة، استخدِم الحقل createRequest. للحفاظ على التغييرات، تذكَّر ضبط مَعلمة الطلب conferenceDataVersion على 1 لجميع طلبات تعديل الأحداث. قابل للكتابة
description string تمثّل هذه السمة وصف الفعالية. يمكن أن يحتوي على HTML. اختياريّ. قابل للكتابة
end.date date التاريخ بالتنسيق "yyyy-mm-dd"، إذا كان الحدث سيستمر طوال اليوم. قابل للكتابة
end.dateTime datetime الوقت، كقيمة مجمّعة للتاريخ والوقت (منسّقة وفقًا RFC3339) يجب تحديد إزاحة المنطقة الزمنية ما لم يتم تحديد منطقة زمنية بشكلٍ صريح في timeZone. قابل للكتابة
end.timeZone string المنطقة الزمنية التي تم تحديد الوقت فيها (يتم تنسيقه كاسم في "قاعدة بيانات المناطق الزمنية IANA"، مثلاً "Europe/Zurich"). بالنسبة إلى الأحداث المتكررة، يكون هذا الحقل مطلوبًا ويحدّد المنطقة الزمنية التي يتم فيها توسيع التكرار. بالنسبة إلى الأحداث الفردية، يكون هذا الحقل اختياريًا ويشير إلى منطقة زمنية مخصّصة لبدء الحدث وانتهائه. قابل للكتابة
eventLabelId string رقم تعريف تصنيف الحدث الذي تمّ تعيينه للحدث. اختياريّ. يشير ذلك إلى رقم تعريف إدخال في السمة labelProperties.eventLabels للتقويم (راجِع نقطة النهاية Calendars.get).

تحلّ هذه السمة محلّ السمة colorId المستندة إلى الفهرس. لضبط هذه السمة أو تغييرها، عليك تحديد eventLabelVersion=1 في مَعلمات طرق الإدراج والاستيراد والتعديل والتصحيح.

سيؤدي ضبط سلسلة فارغة أو عدم ضبط هذا الحقل على الإطلاق إلى إزالة التصنيف الحالي من الحدث.

 قابل للكتابة
eventType string نوع الحدث المحدّد. لا يمكن تعديل هذا الخيار بعد إنشاء الحدث. القيم المحتمَلة هي:
  • ‫"birthday": حدث يستمر طوال اليوم ويتكرر سنويًا.
  • ‫"default": حدث عادي أو لم يتم تحديد نوعه بشكل أكبر
  • ‫"focusTime": حدث وقت التركيز
  • "fromGmail": حدث من Gmail لا يمكن إنشاء هذا النوع من الأحداث.
  • ‫"outOfOffice": حدث بأنّك خارج المكتب
  • ‫"workingLocation": حدث مرتبط بمكان العمل
 قابل للكتابة
extendedProperties.private object السمات الخاصة بنسخة الحدث التي تظهر في هذا التقويم قابل للكتابة
extendedProperties.shared object السمات التي تتم مشاركتها بين نُسخ الحدث في تقاويم الضيوف الآخرين قابل للكتابة
focusTimeProperties nested object بيانات حدث "وقت التركيز" يجب استخدامها إذا كانت قيمة eventType هي focusTime. قابل للكتابة
gadget.display string وضع عرض الأداة تمّ الإيقاف. القيم المحتمَلة هي:
  • "icon": تعرض الأداة هذا الرمز بجانب عنوان الحدث في طريقة عرض التقويم.
  • ‫"chip": يتم عرض الأداة عند النقر على الحدث.
 قابل للكتابة
gadget.height integer تمثّل هذه السمة ارتفاع الأداة بالبكسل. يجب أن يكون الارتفاع عددًا صحيحًا أكبر من 0. اختياريّ. تمّ الإيقاف. قابل للكتابة
gadget.preferences object التفضيلات. قابل للكتابة
gadget.title string عنوان الأداة تمّ الإيقاف. قابل للكتابة
gadget.type string نوع الأداة تمّ الإيقاف. قابل للكتابة
gadget.width integer تمثّل هذه السمة عرض الأداة بالبكسل. يجب أن يكون العرض عددًا صحيحًا أكبر من 0. اختياريّ. تمّ الإيقاف. قابل للكتابة
guestsCanInviteOthers boolean تُستخدَم لتحديد ما إذا كان بإمكان الضيوف الآخرين غير المنظِّم دعوة مستخدمين آخرين إلى الحدث. اختياريّ. القيمة التلقائية هي True. قابل للكتابة
guestsCanModify boolean تحديد ما إذا كان بإمكان المشاركين الآخرين غير المنظِّم تعديل الحدث اختياريّ. القيمة التلقائية هي False. قابل للكتابة
guestsCanSeeOtherGuests boolean تحديد ما إذا كان بإمكان الضيوف الآخرين غير المنظِّم الاطّلاع على قائمة الضيوف في الحدث اختياريّ. القيمة التلقائية هي True. قابل للكتابة
id string معرّف مبهم للحدث. عند إنشاء أحداث جديدة لمرة واحدة أو متكرّرة، يمكنك تحديد معرّفاتها. يجب أن تتّبع المعرّفات المقدَّمة القواعد التالية:
  • الأحرف المسموح بها في المعرّف هي تلك المستخدَمة في ترميز base32hex، أي الأحرف الصغيرة من a إلى v والأرقام من 0 إلى 9، راجِع القسم 3.1.2 في RFC2938
  • يجب أن يتراوح طول المعرّف بين 5 و1024 حرفًا
  • يجب أن يكون المعرّف فريدًا لكل تقويم
بسبب الطبيعة الموزّعة عالميًا للنظام، لا يمكننا ضمان رصد تعارضات أرقام التعريف في وقت إنشاء الحدث. للحدّ من مخاطر التعارضات، ننصحك باستخدام خوارزمية UUID ثابتة، مثل تلك الموضّحة في RFC4122.

إذا لم تحدّد معرّفًا، سيتم إنشاؤه تلقائيًا بواسطة الخادم.

يُرجى العِلم أنّ icalUID وid ليسا متطابقَين ويجب تقديم أحدهما فقط عند إنشاء الحدث. أحد الاختلافات في دلالاتها هو أنّه في الأحداث المتكرّرة، يكون لكل تكرار لحدث واحد id مختلف، بينما تشترك جميعها في icalUID نفسه.

 قابل للكتابة
location string الموقع الجغرافي للحدث كنص حر اختياريّ. قابل للكتابة
originalStartTime.date date التاريخ بالتنسيق "yyyy-mm-dd"، إذا كان الحدث سيستمر طوال اليوم. قابل للكتابة
originalStartTime.dateTime datetime الوقت، كقيمة مجمّعة للتاريخ والوقت (منسّقة وفقًا RFC3339) يجب تحديد إزاحة المنطقة الزمنية ما لم يتم تحديد منطقة زمنية بشكلٍ صريح في timeZone. قابل للكتابة
originalStartTime.timeZone string المنطقة الزمنية التي تم تحديد الوقت فيها (يتم تنسيقه كاسم في "قاعدة بيانات المناطق الزمنية IANA"، مثلاً "Europe/Zurich"). بالنسبة إلى الأحداث المتكررة، يكون هذا الحقل مطلوبًا ويحدّد المنطقة الزمنية التي يتم فيها توسيع التكرار. بالنسبة إلى الأحداث الفردية، يكون هذا الحقل اختياريًا ويشير إلى منطقة زمنية مخصّصة لبدء الحدث وانتهائه. قابل للكتابة
outOfOfficeProperties nested object بيانات حدث "خارج المكتب" يجب استخدامها إذا كانت قيمة eventType هي outOfOffice. قابل للكتابة
recurrence[] list قائمة بأسطر RRULE وEXRULE وRDATE وEXDATE لحدث متكرّر، كما هو محدّد في RFC5545. يُرجى العِلم أنّه لا يُسمح باستخدام سطور DTSTART وDTEND في هذا الحقل، بل يتم تحديد وقتَي بدء الفعالية وانتهائها في الحقلَين start وend. يتم حذف هذا الحقل للأحداث الفردية أو مثيلات الأحداث المتكررة. قابل للكتابة
reminders.overrides[] list إذا لم يستخدم الحدث التذكيرات التلقائية، سيتم عرض التذكيرات الخاصة بالحدث، أو سيتم الإشارة إلى عدم ضبط أي تذكيرات لهذا الحدث في حال عدم ضبطها. الحدّ الأقصى لعدد التذكيرات التي يمكن تجاهلها هو 5. قابل للكتابة
reminders.overrides[].method string الطريقة التي يستخدمها هذا التذكير. القيم المحتمَلة هي:
  • email: يتم إرسال التذكيرات عبر البريد الإلكتروني.
  • "popup": يتم إرسال التذكيرات من خلال نافذة منبثقة في واجهة المستخدم.

يجب توفيرها عند إضافة تذكير.

 قابل للكتابة
reminders.overrides[].minutes integer عدد الدقائق قبل بدء الحدث عندما يجب أن يتم تشغيل التذكير. تتراوح القيم الصالحة بين 0 و40320 (4 أسابيع بالدقائق).

يجب توفيرها عند إضافة تذكير.

 قابل للكتابة
reminders.useDefault boolean تُستخدَم لتحديد ما إذا كانت التذكيرات التلقائية للتقويم تنطبق على الحدث. قابل للكتابة
sequence integer الرقم التسلسلي وفقًا لتنسيق iCalendar قابل للكتابة
source.title string تمثّل هذه السمة عنوان المستند المصدر، مثل عنوان صفحة ويب أو موضوع رسالة إلكترونية. قابل للكتابة
source.url string تمثّل هذه السمة عنوان URL للمصدر الذي يشير إلى أحد الموارد. يجب أن يكون مخطّط URL هو HTTP أو HTTPS. قابل للكتابة
start.date date التاريخ بالتنسيق "yyyy-mm-dd"، إذا كان الحدث سيستمر طوال اليوم. قابل للكتابة
start.dateTime datetime الوقت، كقيمة مجمّعة للتاريخ والوقت (منسّقة وفقًا RFC3339) يجب تحديد إزاحة المنطقة الزمنية ما لم يتم تحديد منطقة زمنية بشكلٍ صريح في timeZone. قابل للكتابة
start.timeZone string المنطقة الزمنية التي تم تحديد الوقت فيها (يتم تنسيقه كاسم في "قاعدة بيانات المناطق الزمنية IANA"، مثلاً "Europe/Zurich"). بالنسبة إلى الأحداث المتكررة، يكون هذا الحقل مطلوبًا ويحدّد المنطقة الزمنية التي يتم فيها توسيع التكرار. بالنسبة إلى الأحداث الفردية، يكون هذا الحقل اختياريًا ويشير إلى منطقة زمنية مخصّصة لبدء الحدث وانتهائه. قابل للكتابة
status string تمثّل هذه السمة حالة الحدث. اختياريّ. القيم المحتمَلة هي:
  • ‫"confirmed": تم تأكيد الحدث. هذه هي الحالة التلقائية.
  • ‫"tentative": تم تأكيد الحدث مبدئيًا.
  • ‫"cancelled": تم إلغاء الحدث (حذفه). لا تعرض طريقة القائمة الأحداث الملغاة إلا عند المزامنة التدريجية (عند تحديد syncToken أو updatedMin) أو إذا تم ضبط العلامة showDeleted على true. تعرض الطريقة get هذه القيم دائمًا.

    تمثّل الحالة "تم إلغاؤه" حالتين مختلفتين حسب نوع الحدث:

    1. تشير الاستثناءات الملغاة لحدث متكرّر لم يتم إلغاؤه إلى أنّه يجب ألا يتم عرض هذه النسخة للمستخدم بعد الآن. على العملاء تخزين هذه الأحداث طوال مدة الحدث المتكرّر الرئيسي.

      يتم ضمان ملء الحقول id وrecurringEventId وoriginalStartTime فقط في الاستثناءات الملغاة. قد تكون الحقول الأخرى فارغة.

    2. تمثّل جميع الأحداث الملغاة الأخرى الأحداث المحذوفة. على العملاء إزالة النُسخ التي تمت مزامنتها على أجهزتهم. وستختفي هذه الأحداث الملغاة في النهاية، لذا لا تعتمد على توفّرها إلى أجل غير مسمى.

      يتم ضمان ملء الحقل id فقط في الأحداث المحذوفة.

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

    إذا غيّر حدث ما منظّمه (على سبيل المثال، من خلال عملية النقل) ولم يكن المنظّم الأصلي في قائمة المشاركين، سيؤدي ذلك إلى إلغاء الحدث الذي سيتم فيه ملء الحقل id فقط.

قابل للكتابة
summary string تمثل هذه الخاصية عنوان الفعالية. قابل للكتابة
transparency string تحديد ما إذا كان الحدث يحظر الوقت في التقويم اختياريّ. القيم المحتمَلة هي:
  • ‫"opaque" - القيمة التلقائية يؤدي الحدث إلى حظر الوقت في التقويم. هذا الإعداد مكافئ لضبط حالة التوفّر على مشغول في واجهة مستخدم "تقويم Google".
  • "transparent": لا يحجز الحدث وقتًا في التقويم. هذا الإعداد مكافئ لضبط حالة التوفّر على متاح في واجهة مستخدم "تقويم Google".
 قابل للكتابة
visibility string تمثّل هذه السمة مستوى رؤية الحدث. اختياريّ. القيم المحتمَلة هي:
  • ‫"default": يستخدم مستوى الرؤية التلقائي للأحداث في التقويم. هذه هي القيمة الافتراضية.
  • "public": الحدث متاح للجميع ويمكن لجميع قارئي التقويم الاطّلاع على تفاصيله.
  • ‫"private": الحدث خاص ويمكن للمشاركين فيه فقط الاطّلاع على تفاصيله.
  • ‫"confidential": الحدث خاص. يتم توفير هذه القيمة لأسباب تتعلق بالتوافق.
 قابل للكتابة
workingLocationProperties nested object بيانات أحداث مكان العمل قابل للكتابة
workingLocationProperties.customLocation object تحدّد هذه السمة ما إذا كان المستخدم يعمل من موقع جغرافي مخصّص. قابل للكتابة
workingLocationProperties.customLocation.label string تصنيف إضافي اختياري لتقديم معلومات إضافية قابل للكتابة
workingLocationProperties.homeOffice any value في حال توفّره، يحدّد ما إذا كان المستخدم يعمل من المنزل. قابل للكتابة
workingLocationProperties.officeLocation object في حال توفّر هذه السمة، تحدّد أنّ المستخدم يعمل من مكتب. قابل للكتابة
workingLocationProperties.officeLocation.buildingId string معرّف مبنى اختياري يجب أن يشير ذلك إلى معرّف مبنى في قاعدة بيانات "الموارد" الخاصة بالمؤسسة. قابل للكتابة
workingLocationProperties.officeLocation.deskId string معرّف اختياري للمكتب قابل للكتابة
workingLocationProperties.officeLocation.floorId string معرّف اختياري للطابق قابل للكتابة
workingLocationProperties.officeLocation.floorSectionId string معرّف اختياري لقسم الطابق قابل للكتابة
workingLocationProperties.officeLocation.label string اسم المكتب المعروض في إصدارَي "تقويم Google" على الويب والأجهزة الجوّالة ننصحك بالرجوع إلى اسم مبنى في قاعدة بيانات "الموارد" الخاصة بالمؤسسة. قابل للكتابة
workingLocationProperties.type string تمثّل هذه السمة نوع مكان العمل. القيم المحتمَلة هي:
  • ‫"homeOffice": يشير إلى أنّ المستخدم يعمل من المنزل.
  • "officeLocation": يعمل المستخدم من مكتب.
  • ‫"customLocation": يعمل المستخدم من موقع جغرافي مخصّص.
يتم تحديد أي تفاصيل في حقل فرعي للاسم المحدّد، ولكن قد يكون هذا الحقل غير متوفّر إذا كان فارغًا. ويتم تجاهل أي حقول أخرى.

مطلوبة عند إضافة سمات مكان العمل.

 قابل للكتابة

الردّ

في حال نجاح هذا الإجراء، سيعرض مورد "الأحداث" في نص الاستجابة.

جرِّبها الآن.

استخدِم "مستكشف واجهات برمجة التطبيقات" أدناه لطلب هذه الطريقة من خلال البيانات المباشرة والاطّلاع على الردّ.