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	شماره نسخه داده‌های کنفرانس پشتیبانی‌شده توسط کلاینت API. نسخه 0 فرض می‌کند که از داده‌های کنفرانس پشتیبانی نمی‌شود و داده‌های کنفرانس را در بدنه رویداد نادیده می‌گیرد. نسخه 1 پشتیبانی از کپی کردن ConferenceData و همچنین ایجاد کنفرانس‌های جدید با استفاده از فیلد createRequest از conferenceData را فعال می‌کند. مقدار پیش‌فرض 0 است. مقادیر قابل قبول 0 تا 1 هستند.
maxAttendees	integer	حداکثر تعداد شرکت‌کنندگانی که باید در پاسخ لحاظ شوند. اگر تعداد شرکت‌کنندگان از تعداد مشخص‌شده بیشتر باشد، فقط نام شرکت‌کننده برگردانده می‌شود. اختیاری.
sendNotifications	boolean	منسوخ شده. لطفاً به جای آن از sendUpdates استفاده کنید. اینکه آیا اعلان‌هایی درباره به‌روزرسانی رویداد (مثلاً تغییرات توضیحات و غیره) ارسال شود یا خیر. توجه داشته باشید که حتی اگر مقدار را روی false تنظیم کنید، ممکن است برخی از ایمیل‌ها همچنان ارسال شوند. مقدار پیش‌فرض false است.
sendUpdates	string	مهمانانی که باید در مورد به‌روزرسانی رویداد (مثلاً تغییر عنوان و غیره) اعلان دریافت کنند. مقادیر قابل قبول عبارتند از: « all »: اعلان‌ها برای همه مهمانان ارسال می‌شوند. « externalOnly »: اعلان‌ها فقط برای مهمانانی که تقویم گوگل ندارند ارسال می‌شوند. « none »: هیچ اعلانی ارسال نمی‌شود. برای وظایف انتقال تقویم، به جای آن از متد Events.import استفاده کنید.
supportsAttachments	boolean	اینکه آیا کلاینت API که عملیات را انجام می‌دهد از پیوست‌های رویداد پشتیبانی می‌کند یا خیر. اختیاری. پیش‌فرض 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 به فایل پیوست. برای افزودن پیوست‌های فایل گوگل درایو، از همان فرمتی که در ویژگی alternateLink از منبع Files در Drive API وجود دارد، استفاده کنید. هنگام اضافه کردن پیوست الزامی است.	قابل نوشتن
attendees[]	list	شرکت‌کنندگان در رویداد. برای اطلاعات بیشتر در مورد زمان‌بندی رویدادها با سایر کاربران تقویم، به راهنمای « رویدادها با شرکت‌کنندگان» مراجعه کنید. حساب‌های سرویس برای پر کردن لیست شرکت‌کنندگان باید از تفویض اختیار در سطح دامنه استفاده کنند.	قابل نوشتن
attendees[]. additionalGuests	integer	تعداد مهمانان اضافی. اختیاری. مقدار پیش‌فرض ۰ است.	قابل نوشتن
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 تنظیم مجدد شود و رویدادی را در تقویم خود نبینند، مگر اینکه پاسخ خود را در ایمیل دعوت‌نامه تغییر دهند. علاوه بر این، اگر بیش از ۲۰۰ مهمان به رویداد دعوت شوند، وضعیت پاسخ به مهمانان ارسال نمی‌شود.	قابل نوشتن
attendeesOmitted	boolean	آیا شرکت‌کنندگان از نمایش رویداد حذف شده‌اند یا خیر. هنگام بازیابی یک رویداد، این ممکن است به دلیل محدودیتی باشد که توسط پارامتر پرس‌وجوی maxAttendee مشخص شده است. هنگام به‌روزرسانی یک رویداد، می‌توان از این مورد فقط برای به‌روزرسانی پاسخ شرکت‌کننده استفاده کرد. اختیاری. مقدار پیش‌فرض False است.	قابل نوشتن
colorId	string	رنگ رویداد. این یک شناسه است که به ورودی در بخش event تعریف رنگ‌ها اشاره می‌کند (به نقطه پایانی رنگ‌ها مراجعه کنید). اختیاری.	قابل نوشتن
conferenceData	nested object	اطلاعات مربوط به کنفرانس، مانند جزئیات یک کنفرانس Google Meet. برای ایجاد جزئیات جدید کنفرانس، از فیلد createRequest استفاده کنید. برای حفظ تغییرات خود، به یاد داشته باشید که پارامتر درخواست conferenceDataVersion را برای همه درخواست‌های اصلاح رویداد روی 1 تنظیم کنید. هشدار: استفاده مجدد از داده‌های کنفرانس Google Meet در رویدادهای مختلف می‌تواند باعث ایجاد مشکلات دسترسی و افشای جزئیات جلسه برای کاربران ناخواسته شود. برای اطمینان از حفظ حریم خصوصی جلسه، همیشه با استفاده از فیلد createRequest برای هر رویداد یک کنفرانس منحصر به فرد ایجاد کنید.	قابل نوشتن
description	string	شرح رویداد. می‌تواند شامل HTML باشد. اختیاری.	قابل نوشتن
end. date	date	تاریخ، با فرمت "yyyy-mm-dd"، اگر این رویداد تمام روز باشد.	قابل نوشتن
end. dateTime	datetime	زمان، به عنوان یک مقدار ترکیبی تاریخ-زمان (طبق RFC3339 قالب‌بندی شده). انحراف منطقه زمانی مورد نیاز است، مگر اینکه منطقه زمانی به صراحت در timeZone مشخص شده باشد.	قابل نوشتن
end. timeZone	string	منطقه زمانی که زمان در آن مشخص شده است. (به صورت نام پایگاه داده منطقه زمانی IANA قالب‌بندی می‌شود، مثلاً "اروپا/زوریخ".) برای رویدادهای تکرارشونده، این فیلد الزامی است و منطقه زمانی را که تکرار در آن گسترش می‌یابد، مشخص می‌کند. برای رویدادهای تکی، این فیلد اختیاری است و یک منطقه زمانی سفارشی برای شروع/پایان رویداد را نشان می‌دهد.	قابل نوشتن
extendedProperties. private	object	Properties that are private to the copy of the event that appears on this calendar.	قابل نوشتن
extendedProperties. shared	object	ویژگی‌هایی که بین کپی‌های رویداد در تقویم‌های سایر شرکت‌کنندگان به اشتراک گذاشته می‌شوند.	قابل نوشتن
focusTimeProperties	nested object	داده‌های رویداد زمان تمرکز. اگر eventType focusTime باشد، استفاده می‌شود.	قابل نوشتن
gadget. display	string	حالت نمایش گجت. منسوخ شده. مقادیر ممکن عبارتند از: « icon » - این ابزارک در نمای تقویم، کنار عنوان رویداد نمایش داده می‌شود. « chip » - گجت هنگام کلیک روی رویداد نمایش داده می‌شود.	قابل نوشتن
gadget. height	integer	ارتفاع ابزارک بر حسب پیکسل. ارتفاع باید یک عدد صحیح بزرگتر از ۰ باشد. اختیاری. منسوخ شده.	قابل نوشتن
gadget. iconLink	string	آدرس اینترنتی (URL) آیکون ابزارک. طرح نشانی اینترنتی (URL) باید HTTPS باشد. منسوخ شده است.	قابل نوشتن
gadget. link	string	آدرس اینترنتی (URL) ابزارک. طرح URL باید HTTPS باشد. منسوخ شده است.	قابل نوشتن
gadget. preferences	object	ترجیحات	قابل نوشتن
gadget. title	string	عنوان گجت. منسوخ شده.	قابل نوشتن
gadget. type	string	نوع گجت. منسوخ شده.	قابل نوشتن
gadget. width	integer	عرض ابزارک بر حسب پیکسل. عرض باید عدد صحیحی بزرگتر از ۰ باشد. اختیاری. منسوخ شده.	قابل نوشتن
guestsCanInviteOthers	boolean	اینکه آیا شرکت‌کنندگان غیر از برگزارکننده می‌توانند دیگران را به رویداد دعوت کنند یا خیر. اختیاری. پیش‌فرض True است.	قابل نوشتن
guestsCanModify	boolean	اینکه آیا شرکت‌کنندگان غیر از برگزارکننده می‌توانند رویداد را تغییر دهند یا خیر. اختیاری. مقدار پیش‌فرض False است.	قابل نوشتن
guestsCanSeeOtherGuests	boolean	اینکه آیا شرکت‌کنندگانی غیر از برگزارکننده می‌توانند شرکت‌کنندگان رویداد را ببینند یا خیر. اختیاری. مقدار پیش‌فرض درست است.	قابل نوشتن
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	اگر رویداد از یادآوری‌های پیش‌فرض استفاده نکند، این فهرست یادآوری‌های مختص به رویداد را نمایش می‌دهد، یا اگر تنظیم نشده باشد، نشان می‌دهد که هیچ یادآوری برای این رویداد تنظیم نشده است. حداکثر تعداد یادآوری‌های لغو شده ۵ است.	قابل نوشتن
reminders.overrides[]. method	string	روشی که این یادآوری استفاده می‌کند. مقادیر ممکن عبارتند از: « email » - یادآوری‌ها از طریق ایمیل ارسال می‌شوند. « popup » - یادآوری‌ها از طریق یک پنجره بازشو در رابط کاربری ارسال می‌شوند. هنگام اضافه کردن یادآوری الزامی است.	قابل نوشتن
reminders.overrides[]. minutes	integer	تعداد دقایق قبل از شروع رویداد که یادآوری باید فعال شود. مقادیر معتبر بین ۰ تا ۴۰۳۲۰ (۴ هفته به دقیقه) هستند. هنگام اضافه کردن یادآوری الزامی است.	قابل نوشتن
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 » - مقدار پیش‌فرض. این رویداد زمان را در تقویم مسدود می‌کند. این معادل تنظیم «به من نشان بده به عنوان مشغول» در رابط کاربری تقویم است. « transparent » - این رویداد زمان را در تقویم مسدود نمی‌کند. این معادل تنظیم «به من نشان بده به عنوان موجود در رابط کاربری تقویم» است.	قابل نوشتن
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	نام دفتر که در کلاینت‌های تقویم وب و موبایل نمایش داده می‌شود. توصیه می‌کنیم نام ساختمان را در پایگاه داده منابع سازمان ذکر کنید.	writable
workingLocationProperties. type	string	نوع محل کار. مقادیر ممکن عبارتند از: « homeOffice » - کاربر در خانه مشغول به کار است. « officeLocation » - کاربر در حال کار از یک دفتر است. « customLocation » - کاربر از یک مکان سفارشی کار می‌کند. هر جزئیاتی در یک فیلد فرعی با نام مشخص شده مشخص می‌شود، اما اگر این فیلد خالی باشد، ممکن است وجود نداشته باشد. هر فیلد دیگری نادیده گرفته می‌شود. هنگام افزودن ویژگی‌های محل کار الزامی است.	قابل نوشتن

پاسخ

در صورت موفقیت، این متد یک منبع رویدادها (Events resource) را در بدنه پاسخ برمی‌گرداند.

امتحانش کن!

از API Explorer زیر برای فراخوانی این متد روی داده‌های زنده و مشاهده پاسخ استفاده کنید.