Events: update

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

الطلب

طلب 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 في للمؤتمرات. القيمة التلقائية هي 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

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

نص الطلب

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

اسم الموقع القيمة الوصف ملاحظات
الخصائص المطلوبة
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" - قبول الضيف الدعوة.
 قابل للكتابة
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.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 قائمة سطور Rالقواعد وEXالقواعد و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 دائمًا إلى إرجاعها.

    تمثّل حالة الإلغاء حالتَين مختلفتَين استنادًا إلى نوع الحدث:

    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" - عمل المستخدم من موقع مخصص.
تم تحديد أي تفاصيل في حقل فرعي للاسم المحدّد، ولكن قد يكون هذا الحقل غير متوفّر إذا كان فارغًا. ويتم تجاهل أي حقول أخرى.

هذا الحقل مطلوب عند إضافة خصائص مكان العمل.

 قابل للكتابة

الرد

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

أمثلة

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

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

جرّب الآن

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