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.
maxAttendees	integer	الحد الأقصى لعدد الضيوف المطلوب تضمينهم في الردّ إذا كان هناك أكثر من العدد المحدّد من الضيوف، يتم عرض المشارك فقط. اختياريّ.
sendNotifications	boolean	تمّ الإيقاف. يُرجى استخدام sendUpdates بدلاً من ذلك. يحدد هذا الخيار ما إذا كان سيتم إرسال إشعارات بشأن إنشاء الحدث الجديد. يُرجى العِلم أنّه قد يستمر إرسال بعض الرسائل الإلكترونية حتى إذا ضبطت القيمة على false. القيمة التلقائية هي false.
sendUpdates	string	ما إذا كان سيتم إرسال إشعارات بشأن إنشاء الحدث الجديد يُرجى العِلم أنّه قد يستمر إرسال بعض الرسائل الإلكترونية. القيمة التلقائية هي false. القِيَم المقبولة هي: "all": يتم إرسال الإشعارات إلى جميع الضيوف. "externalOnly": يتم إرسال الإشعارات إلى المدعوين غير المستخدمين لـ "تقويم Google" فقط. "none": لا يتم إرسال أي إشعارات. تحذير: يمكن أن يؤدي استخدام القيمة none إلى عواقب سلبية كبيرة، بما في ذلك عدم مزامنة الأحداث مع التقاويم الخارجية أو فقدان الأحداث بالكامل لبعض المستخدمين. بالنسبة إلى مهام نقل بيانات التقويم، ننصحك باستخدام الطريقة events.import بدلاً من ذلك.
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" - قبِل الحاضر الدعوة. تحذير: في حال إضافة حدث باستخدام القيم declined أو tentative أو accepted، قد تتم إعادة ضبط ردّ الضيوف الذين تم ضبط إعداد "إضافة دعوات إلى تقويمي" لديهم على "بعد الردّ على الدعوة في الرسالة الإلكترونية" أو "فقط إذا كان المُرسِل معروفًا" على needsAction ولن يظهر لهم الحدث في تقويمهم ما لم يغيّروا ردّهم في الرسالة الإلكترونية لدعوة الحدث. بالإضافة إلى ذلك، إذا تمّت دعوة أكثر من 200 مدعو إلى الحدث، لن يتمّ نشر حالة الردّ إلى المدعوين.	قابلة للكتابة
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") بالنسبة إلى الأحداث المتكرّرة، يكون هذا الحقل مطلوبًا ويحدّد المنطقة الزمنية التي يتم فيها توسيع نطاق التكرار. بالنسبة إلى الأحداث الفردية، يكون هذا الحقل اختياريًا ويشير إلى منطقة زمنية مخصّصة لبدء/انتهاء الحدث.	قابلة للكتابة
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.iconLink	string	عنوان URL لرمز الأداة يجب أن يكون مخطّط عنوان URL هو HTTPS. تمّ الإيقاف.	قابلة للكتابة
gadget.link	string	عنوان URL الخاص بالتطبيق المصغّر يجب أن يكون مخطّط عنوان URL هو HTTPS. تمّ الإيقاف.	قابلة للكتابة
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": تم إلغاء الحدث (تم حذفه). لا تعرض طريقة list الأحداث المُلغاة إلا عند إجراء مزامنة تدريجية (عند تحديد syncToken أو updatedMin) أو إذا تم ضبط العلامة showDeleted على true. وتُرجع الطريقة get هذه القيم دائمًا. تمثّل الحالة "تم إلغاؤها" حالتَين مختلفتَين استنادًا إلى نوع الحدث: تشير الاستثناءات المُلغاة لحدث متكرّر لم يتم إلغاؤه إلى أنّه يجب عدم عرض هذه النسخة للمستخدم بعد الآن. على العملاء تخزين هذه الأحداث طوال مدة الحدث المتكرّر الرئيسي. لا يمكن ضمان أن تحتوي الاستثناءات المُلغاة إلا على قيم لحقول id وrecurringEventId وoriginalStartTime. قد تكون الحقول الأخرى فارغة. وجميع الأحداث الأخرى المُلغاة تمثّل أحداثًا محذوفة. على العملاء إزالة النُسخ التي تمت مزامنتها على الجهاز. ستتم إزالة هذه الأحداث المُلغاة في النهاية، لذا لا تعتمد على توفّرها إلى أجل غير مسمى. لا يمكن ضمان تعبئة الحقل 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" - يعمل المستخدم من موقع مخصّص. يتم تحديد أي تفاصيل في حقل فرعي للاسم المحدّد، ولكن قد لا يكون هذا الحقل متوفّرًا إذا كان فارغًا. ويتم تجاهل أي حقول أخرى. مطلوب عند إضافة سمات مكان العمل.	قابلة للكتابة

الردّ

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

جرّب الآن

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