Events: update

ملاحظة: يتطلب هذا الإجراء تفويضًا.

تعديل حدث لا تتوافق هذه الطريقة مع دلالات التصحيح، وتعمل دائمًا على تعديل مورد الحدث بالكامل. لإجراء تعديل جزئي، عليك تنفيذ get متبوعًا بـ update باستخدام علامات etags لضمان التماسك. جرِّب ذلك الآن أو اطّلِع على مثال.

الطلب

طلب HTTP

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

المعلمات

اسم المعلَمة	القيمة	الوصف
مَعلمات المسار
calendarId	string	معرّف التقويم لاسترداد أرقام تعريف التقاويم، يمكنك استدعاء الطريقة calendarList.list. إذا كنت تريد الوصول إلى التقويم الأساسي للمستخدم الذي سجّل الدخول حاليًا، استخدِم الكلمة الرئيسية "primary".
eventId	string	معرّف الحدث
مَعلمات طلب البحث الاختيارية
alwaysIncludeEmail	boolean	تم إيقافها نهائيًا ويتم تجاهلها. سيتم دائمًا عرض قيمة في حقل email للمُنظِّم وصنّاع المحتوى والحضور، حتى إذا لم يتوفّر عنوان بريد إلكتروني حقيقي (أي سيتم تقديم قيمة تم إنشاؤها ولا تعمل).
conferenceDataVersion	integer	رقم إصدار بيانات المؤتمر المتوافقة مع برنامج تشغيل واجهة برمجة التطبيقات يفترض الإصدار 0 عدم توفّر بيانات المؤتمر ويتجاهل بيانات المؤتمر في نص الحدث. يتيح الإصدار 1 إمكانية نسخ ConferenceData بالإضافة إلى إنشاء مكالمات فيديو جديدة باستخدام حقل createRequest في conferenceData. القيمة التلقائية هي 0. القيم المقبولة هي من 0 إلى 1.
maxAttendees	integer	الحد الأقصى لعدد الضيوف المطلوب تضمينه في الردّ إذا كان هناك أكثر من العدد المحدّد من الضيوف، يتم عرض المشارك فقط. اختياريّ.
sendNotifications	boolean	تمّ الإيقاف. يُرجى استخدام sendUpdates بدلاً من ذلك. يحدد هذا الخيار ما إذا كان سيتم إرسال إشعارات بشأن تعديل الحدث (على سبيل المثال، تغييرات الوصف وما إلى ذلك). يُرجى العِلم أنّه قد يستمر إرسال بعض الرسائل الإلكترونية حتى إذا ضبطت القيمة على false. القيمة التلقائية هي false.
sendUpdates	string	الضيوف الذين يجب أن يتلقّوا إشعارات بشأن تعديل الحدث (مثل تغييرات العنوان وما إلى ذلك) القِيَم المقبولة هي: "all": يتم إرسال الإشعارات إلى جميع المدعوين. "externalOnly": يتم إرسال الإشعارات إلى المدعوين غير المستخدمين لـ "تقويم Google" فقط. "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 مدعو إلى الحدث، لن يتمّ نشر حالة الردّ إلى المدعوين.	قابلة للكتابة
attendeesOmitted	boolean	ما إذا كان قد تم حذف الضيوف من تمثيل الحدث عند استرداد حدث، قد يرجع ذلك إلى قيد محدّد من خلال مَعلمة طلب البحث maxAttendee. عند تعديل حدث، يمكن استخدام هذا الحقل لتعديل ردّ المشارك فقط. اختياريّ. القيمة التلقائية هي False.	قابلة للكتابة
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"، مثل "أوروبا/زيورخ") بالنسبة إلى الأحداث المتكرّرة، يكون هذا الحقل مطلوبًا ويحدّد المنطقة الزمنية التي يتم فيها توسيع نطاق التكرار. بالنسبة إلى الأحداث الفردية، يكون هذا الحقل اختياريًا ويشير إلى منطقة زمنية مخصّصة لبدء/انتهاء الحدث.	قابلة للكتابة
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.	قابلة للكتابة
location	string	الموقع الجغرافي للحدث بتنسيق نصي حر اختياريّ.	قابلة للكتابة
originalStartTime.date	date	التاريخ بالتنسيق "yyyy-mm-dd"، إذا كان هذا الحدث سيستمر طوال اليوم	قابلة للكتابة
originalStartTime.dateTime	datetime	الوقت، كقيمة تاريخ ووقت مجمّعة (منسّقة وفقًا لـ RFC3339) يجب تحديد توقيت المنطقة الزمنية ما لم يتم تحديد منطقة زمنية صراحةً في timeZone.	قابلة للكتابة
originalStartTime.timeZone	string	المنطقة الزمنية التي تم تحديد الوقت فيها (يكون التنسيق على هيئة اسم في "قاعدة بيانات المناطق الزمنية IANA"، مثل "أوروبا/زيورخ") بالنسبة إلى الأحداث المتكرّرة، يكون هذا الحقل مطلوبًا ويحدّد المنطقة الزمنية التي يتم فيها توسيع نطاق التكرار. بالنسبة إلى الأحداث الفردية، يكون هذا الحقل اختياريًا ويشير إلى منطقة زمنية مخصّصة لبدء/انتهاء الحدث.	قابلة للكتابة
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"، مثل "أوروبا/زيورخ") بالنسبة إلى الأحداث المتكرّرة، يكون هذا الحقل مطلوبًا ويحدّد المنطقة الزمنية التي يتم فيها توسيع نطاق التكرار. بالنسبة إلى الأحداث الفردية، يكون هذا الحقل اختياريًا ويشير إلى منطقة زمنية مخصّصة لبدء/انتهاء الحدث.	قابلة للكتابة
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" - يعمل المستخدم من موقع مخصّص. يتم تحديد أي تفاصيل في حقل فرعي للاسم المحدّد، ولكن قد لا يكون هذا الحقل متوفّرًا إذا كان فارغًا. ويتم تجاهل أي حقول أخرى. مطلوب عند إضافة سمات مكان العمل.	قابلة للكتابة

الردّ

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

أمثلة

ملاحظة: إنّ الأمثلة المرتبطة بالرموز والمتوفرة لهذه الطريقة لا تمثّل كل لغات البرمجة المتوافقة (يُرجى مراجعة صفحة مكتبات البرامج للاطّلاع على قائمة باللغات المتوافقة).

Java

يستخدم مكتبة برامج Java.

import com.google.api.services.calendar.Calendar;
import com.google.api.services.calendar.model.Event;

// ...

// Initialize Calendar service with valid OAuth credentials
Calendar service = new Calendar.Builder(httpTransport, jsonFactory, credentials)
    .setApplicationName("applicationName").build();

// Retrieve the event from the API
Event event = service.events().get("primary", "eventId").execute();

// Make a change
event.setSummary("Appointment at Somewhere");

// Update the event
Event updatedEvent = service.events().update("primary", event.getId(), event).execute();

System.out.println(updatedEvent.getUpdated());

Python

يستخدم مكتبة برامج Python.

# First retrieve the event from the API.
event = service.events().get(calendarId='primary', eventId='eventId').execute()

event['summary'] = 'Appointment at Somewhere'

updated_event = service.events().update(calendarId='primary', eventId=event['id'], body=event).execute()

# Print the updated date.
print updated_event['updated']

PHP

يستخدم مكتبة برامج PHP.

// First retrieve the event from the API.
$event = $service->events->get('primary', 'eventId');

$event->setSummary('Appointment at Somewhere');

$updatedEvent = $service->events->update('primary', $event->getId(), $event);

// Print the updated date.
echo $updatedEvent->getUpdated();

Ruby

يستخدم مكتبة عملاء Ruby.

event = client.get_event('primary', 'eventId')
event.summary = 'Appointment at Somewhere'
result = client.update_event('primary', event.id, event)
print result.updated

جرّب الآن

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