Events: import

توجه: نیاز به مجوز دارد.

یک رویداد را وارد می‌کند. این عملیات برای اضافه کردن یک کپی خصوصی از یک رویداد موجود به تقویم استفاده می‌شود. فقط رویدادهایی که eventType آنها default ، می‌توانند وارد شوند.

رفتار منسوخ‌شده: اگر یک رویداد غیر default وارد شود، نوع آن به default تغییر می‌کند و هرگونه ویژگی مختص به نوع رویداد که ممکن است داشته باشد، حذف می‌شود.

همین الان امتحانش کن .

درخواست

درخواست HTTP

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

پارامترها

نام پارامتر	ارزش	توضیحات
پارامترهای مسیر
calendarId	string	شناسه تقویم. برای بازیابی شناسه‌های تقویم، متد calendarList.list را فراخوانی کنید. اگر می‌خواهید به تقویم اصلی کاربر فعلی وارد شده دسترسی پیدا کنید، از کلمه کلیدی " primary " استفاده کنید.
پارامترهای پرس و جو اختیاری
conferenceDataVersion	integer	شماره نسخه داده‌های کنفرانس پشتیبانی‌شده توسط کلاینت API. نسخه 0 فرض می‌کند که از داده‌های کنفرانس پشتیبانی نمی‌شود و داده‌های کنفرانس را در بدنه رویداد نادیده می‌گیرد. نسخه 1 پشتیبانی از کپی کردن ConferenceData و همچنین ایجاد کنفرانس‌های جدید با استفاده از فیلد createRequest از conferenceData را فعال می‌کند. مقدار پیش‌فرض 0 است. مقادیر قابل قبول 0 تا 1 هستند.
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	زمان پایان (منحصراً) رویداد. برای یک رویداد تکرارشونده، این زمان پایان اولین نمونه است.
iCalUID	string	شناسه منحصر به فرد رویداد همانطور که در RFC5545 تعریف شده است. این شناسه برای شناسایی منحصر به فرد رویدادها در سیستم‌های تقویمی استفاده می‌شود و باید هنگام وارد کردن رویدادها از طریق روش import ارائه شود. توجه داشته باشید که iCalUID و id یکسان نیستند و فقط یکی از آنها باید در زمان ایجاد رویداد ارائه شود. یک تفاوت در معنای آنها این است که در رویدادهای تکرارشونده، همه رویدادهای یک رویداد id های متفاوتی دارند در حالی که همه آنها iCalUID های یکسانی دارند. برای بازیابی یک رویداد با استفاده از iCalUID آن، متد events.list را با استفاده از پارامتر iCalUID فراخوانی کنید. برای بازیابی یک رویداد با استفاده از id آن، متد events.get را فراخوانی کنید.
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	ویژگی‌هایی که برای کپی رویدادی که در این تقویم نمایش داده می‌شود، خصوصی هستند.	قابل نوشتن
extendedProperties. shared	object	ویژگی‌هایی که بین کپی‌های رویداد در تقویم‌های سایر شرکت‌کنندگان به اشتراک گذاشته می‌شوند.	قابل نوشتن
focusTimeProperties	nested object	داده‌های رویداد زمان تمرکز. اگر eventType focusTime باشد، استفاده می‌شود.	writable
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	موقعیت جغرافیایی رویداد به صورت متن آزاد. اختیاری.	قابل نوشتن
organizer	object	برگزارکننده رویداد. اگر برگزارکننده خود نیز یکی از شرکت‌کنندگان باشد، این موضوع با یک ورودی جداگانه در attendees با فیلد organizer که روی True تنظیم شده است، نشان داده می‌شود. برای تغییر برگزارکننده، از عملیات جابجایی استفاده کنید. فقط خواندنی، به جز هنگام وارد کردن یک رویداد.	قابل نوشتن
organizer. displayName	string	نام برگزارکننده، در صورت وجود.	قابل نوشتن
organizer. email	string	آدرس ایمیل برگزارکننده، در صورت وجود. این آدرس باید مطابق با RFC5322 معتبر باشد.	قابل نوشتن
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	Title of the source; for example a title of a web page or an email subject.	قابل نوشتن
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 » - این رویداد خصوصی است. این مقدار به دلایل سازگاری ارائه شده است.	قابل نوشتن

پاسخ

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

امتحانش کن!

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