انواع رویداد

این صفحه ویژگی eventType و مشخصات انواع رویدادهای موجود در API تقویم گوگل را توضیح می‌دهد.

تقویم گوگل به کاربران امکان می‌دهد رویدادهای عمومی و همچنین رویدادهایی که برای موارد استفاده خاص و با ویژگی‌های سفارشی طراحی شده‌اند را ایجاد کنند.

می‌توانید نوع رویداد را در مکان‌های زیر در API پیدا کنید:

  • همه رویدادها یک eventType برمی‌گردانند.
  • هنگام ایجاد یا به‌روزرسانی منبع رویداد، eventType تنظیم کنید. در صورت تنظیم نشدن، API از 'default' استفاده می‌کند.
  • برای فهرست کردن رویدادهایی با انواع خاص، در فراخوانی events.list eventTypes مشخص کنید. اگر هیچ نوعی مشخص نشود، API تمام انواع رویداد را برمی‌گرداند.
  • برای دریافت به‌روزرسانی‌های مربوط به رویدادهایی با انواع خاص، در فراخوانی events.watch نوع eventTypes مشخص کنید. اگر هیچ نوعی مشخص نشود، درخواست در تمام انواع رویدادها مشترک می‌شود.

رویداد پیش‌فرض

رویدادهایی با نوع رویداد default ایجاد و به عنوان یکی از منابع اصلی API تقویم استفاده می‌شوند. آن‌ها از طیف گسترده‌ای از ویژگی‌ها برای سفارشی‌سازی بیشتر رویداد پشتیبانی می‌کنند.

برای شروع کار با رویدادهای تقویم ، به ایجاد رویدادها مراجعه کنید.

تولد

تولدها رویدادهای ویژه‌ای هستند که تمام روز را در بر می‌گیرند و سالانه تکرار می‌شوند.

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

API تقویم از متدهای events.get ، events.instances و events.list برای خواندن رویدادهای تولد پشتیبانی می‌کند. می‌توانید eventTypes روی 'birthday' تنظیم کنید تا فقط رویدادهای تولد را فهرست کند. اگر هیچ نوعی مشخص نشود، پاسخ، تاریخ‌های تولد را در کنار سایر انواع رویدادها فهرست می‌کند.

در اشیاء Event برگشتی، فیلد birthdayProperties را برای جزئیات بیشتر در مورد این رویداد ویژه بررسی کنید. birthdayProperties دارای فیلدهای زیر است:

  • type : نوع این رویداد ویژه، چه تولد، چه سالگرد یا هر تاریخ مهم دیگری باشد.
  • customTypeName : برچسب مشخص شده توسط کاربر برای این رویداد خاص. اگر type روی 'custom' تنظیم شده باشد، این مقدار پر می‌شود.
  • contact : نام منبع مخاطبی که این رویداد ویژه به آن لینک شده است، در صورت وجود. این منبع دارای فرمت 'people/c12345' است و می‌تواند برای دریافت جزئیات مخاطب از API People استفاده شود.

این API به شما امکان می‌دهد رویدادهای تولد را با استفاده از متد events.insert با مشخصات زیر ایجاد کنید:

  • eventType روی 'birthday' تنظیم شده است.
  • فیلدهای start و end باید یک رویداد تمام روز را تعریف کنند که دقیقاً یک روز را در بر می‌گیرد.
  • مقدار فیلد visibility باید 'private' باشد.
  • مقدار فیلد transparency باید 'transparent' باشد.
  • باید دارای تکرار سالانه باشد، به این معنی که فیلد recurrence باید 'RRULE:FREQ=YEARLY' باشد. رویدادهای تولد که در 29 فوریه قرار می‌گیرند باید دارای قانون تکرار زیر باشند: 'RRULE:FREQ=YEARLY;BYMONTH=2;BYMONTHDAY=-1' .
  • می‌تواند دارای colorId ، summary و reminders باشد.
  • می‌تواند دارای birthdayProperties باشد. در صورت مشخص شدن، type باید 'birthday' باشد و هر دو customTypeName و contact باید خالی باشند.
  • نمی‌تواند هیچ ویژگی رویداد دیگری داشته باشد.

این API به شما امکان می‌دهد colorId ، summary و reminders رویدادهای تولد را با استفاده از متدهای events.update و events.patch به‌روزرسانی کنید. همچنین می‌توانید فیلدهای start و end را برای تغییر تاریخ رویداد به‌روزرسانی کنید. در این حالت، مقادیر جدید باید یک رویداد تمام روز را تعریف کنند که دقیقاً یک روز را در بر می‌گیرد. جزئیات زمان‌بندی یک رویداد تولد در صورتی که رویداد به یک contact مرتبط باشد یا type آن 'self' باشد، قابل به‌روزرسانی نیست.

API تقویم اجازه ایجاد رویدادهای تولد با birthdayProperties سفارشی یا به‌روزرسانی این ویژگی‌ها را نمی‌دهد. تاریخ‌های مهم را می‌توان با People API ویرایش کرد و تغییرات با تقویم همگام‌سازی می‌شوند. به طور مشابه، کاربران می‌توانند تاریخ تولد خود را در پروفایل حساب گوگل خود ویرایش کنند و با تقویم همگام‌سازی می‌شود.

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

این API از عملیات events.import برای رویدادهای تولد پشتیبانی می‌کند؛ با این حال، این رویداد به عنوان یک رویداد پیش‌فرض وارد می‌شود. به عبارت دیگر، eventType برابر 'default' خواهد بود.

این API از متد events.watch برای ثبت تغییرات در رویدادهای تولد در تقویم پشتیبانی می‌کند. می‌توانید eventTypes روی 'birthday' تنظیم کنید تا در به‌روزرسانی‌های رویدادهای تولد ثبت نام کنید. اگر هیچ نوعی مشخص نشود، درخواست در همه انواع رویدادها، از جمله تولدها، ثبت نام می‌کند.

شما می‌توانید رویدادهای تولد را با استفاده از متد events.delete از API تقویم حذف کنید. حذف یک رویداد تولد از تقویم، داده‌های موجود در مخاطبین گوگل یا پروفایل حساب گوگل را تحت تأثیر قرار نمی‌دهد.

تغییر برگزارکننده‌ی رویداد تولد با استفاده از متدهای events.move یا events.update پشتیبانی نمی‌شود.

رویدادها از Gmail

رویدادهایی که به طور خودکار از Gmail ایجاد می‌شوند، نوع رویداد 'fromGmail' دارند.

API تقویم اجازه ایجاد این نوع رویداد را با استفاده از متد events.insert نمی‌دهد.

این API به شما امکان می‌دهد ویژگی‌های توسعه‌یافته‌ی colorId ، reminders ، visibility ، transparency ، status ، attendees ، private و shared را با استفاده از متدهای events.update و events.patch به‌روزرسانی کنید.

این API از متدهای events.get و events.list برای خواندن رویدادها از Gmail پشتیبانی می‌کند. می‌توانید eventTypes روی 'fromGmail' تنظیم کنید تا فقط رویدادهای تولید شده از Gmail را فهرست کند. اگر هیچ نوعی مشخص نشود، رویدادهای Gmail در کنار سایر انواع رویدادها فهرست می‌شوند.

این API از متد events.watch برای ثبت تغییرات در رویدادهای Gmail در تقویم پشتیبانی می‌کند. اگر هیچ نوعی مشخص نشده باشد، درخواست در همه انواع رویدادها، از جمله 'fromGmail' ثبت می‌شود.

شما می‌توانید رویدادها را از Gmail با استفاده از متد events.delete از API تقویم حذف کنید.

تغییر برگزارکننده‌ی یک رویداد از Gmail با استفاده از متدهای events.move یا events.update پشتیبانی نمی‌شود.

زمان تمرکز، خارج از دفتر و محل کار

شما می‌توانید از API تقویم برای ایجاد و مدیریت رویدادهایی که وضعیت کاربران تقویم را نشان می‌دهند، استفاده کنید.

این ویژگی‌ها فقط در تقویم‌های اصلی و برای برخی از کاربران تقویم در دسترس هستند. برای کسب اطلاعات بیشتر ، به مدیریت زمان تمرکز، رویدادهای خارج از دفتر و رویدادهای محل کار مراجعه کنید.

انواع رویدادها را در Apps Script بررسی کنید

Apps Script یک زبان اسکریپت‌نویسی ابری مبتنی بر جاوااسکریپت است که به شما امکان می‌دهد برنامه‌های تجاری بسازید که با Google Workspace ادغام شوند. اسکریپت‌ها در یک ویرایشگر کد مبتنی بر مرورگر توسعه داده می‌شوند و در سرورهای گوگل ذخیره و اجرا می‌شوند. همچنین برای شروع استفاده از Apps Script جهت ارسال درخواست به API تقویم، به بخش شروع سریع Apps Script مراجعه کنید.

دستورالعمل‌های زیر نحوه خواندن و مدیریت رویدادها را با استفاده از API تقویم به عنوان یک سرویس پیشرفته در Apps Script شرح می‌دهند. برای فهرست کاملی از منابع و روش‌های API تقویم، به مستندات مرجع مراجعه کنید.

ایجاد و تنظیم اسکریپت

  1. با رفتن به script.google.com/create یک اسکریپت ایجاد کنید.
  2. در پنل سمت چپ، کنار Services ، روی a service کلیک کنید.
  3. API تقویم را انتخاب کنید و روی افزودن کلیک کنید.
  4. بعد از فعال کردن API، در پنل سمت چپ ظاهر می‌شود. می‌توانید با تایپ کردن Calendar در ویرایشگر، متدها و کلاس‌های موجود در API را فهرست کنید.

(اختیاری) به‌روزرسانی پروژه ابری

هر پروژه Apps Script یک پروژه Cloud مرتبط دارد. اسکریپت شما می‌تواند از پروژه پیش‌فرضی که Apps Script به طور خودکار ایجاد می‌کند استفاده کند. اگر می‌خواهید از یک پروژه Cloud سفارشی استفاده کنید، به بخش «تغییر به یک پروژه Cloud استاندارد متفاوت» مراجعه کنید. پس از تنظیم پروژه Cloud، برای بازگشت به ویرایشگر کد، گزینه Editor در سمت چپ انتخاب کنید.

اضافه کردن کد به اسکریپت

نمونه کد زیر نحوه لیست کردن، خواندن و ایجاد رویدادها با مقادیر eventType مختلف را نشان می‌دهد.

  1. کد زیر را در ویرایشگر کد قرار دهید.

    const CALENDAR_ID = 'CALENDAR_ID' || 'primary';

/** Lists default events. */
function listDefaultEvents() {
  listEvents('default');
}

/** Lists birthday events. */
function listBirthdays() {
  listEvents('birthday');
}

/** Lists events from Gmail. */
function listEventsFromGmail() {
  listEvents('fromGmail');
}

/**
  * Lists events with the given event type. If no type is specified, lists all events.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/list
  */
function listEvents(eventType = undefined) {
  // Query parameters for the list request.
  const optionalArgs = {
    eventTypes: eventType ? [eventType] : undefined,
    singleEvents: true,
    timeMax: '2024-07-30T00:00:00+01:00',
    timeMin: '2024-07-29T00:00:00+01:00',
  }
  try {
    var response = Calendar.Events.list(CALENDAR_ID, optionalArgs);
    response.items.forEach(event => console.log(event));
  } catch (exception) {
    console.log(exception.message);
  }
}

/**
  * Reads the event with the given eventId.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/get
  */
function readEvent() {
  try {
    var response = Calendar.Events.get(CALENDAR_ID, 'EVENT_ID');
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

/** Creates a default event. */
function createDefaultEvent() {
  const event = {
    start: { dateTime: '2024-07-30T10:30:00+01:00'},
    end: { dateTime: '2024-07-30T12:30:00+01:00'},
    description: 'Created from Apps Script.',
    eventType: 'default',
    summary: 'Sample event',
  }
  createEvent(event);
}

/** Creates a birthday event. */
function createBirthday() {
  const event = {
    start: { date: '2024-01-29' },
    end: { date: '2024-01-30' },
    eventType: 'birthday',
    recurrence: ["RRULE:FREQ=YEARLY"],
    summary: "My friend's birthday",
    transparency: "transparent",
    visibility: "private",
  }
  createEvent(event);
}

/**
  * Creates a Calendar event.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/insert
  */
function createEvent(event) {

  try {
    var response = Calendar.Events.insert(event, CALENDAR_ID);
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

    موارد زیر را جایگزین کنید:

    • CALENDAR_ID : آدرس ایمیل تقویم برای بازیابی و ایجاد رویدادها. این ثابت در ابتدا روی 'primary' تنظیم شده است که یک کلمه کلیدی برای دسترسی به تقویم اصلی کاربر وارد شده است. تغییر این مقدار به شما امکان می‌دهد رویدادهای تقویم‌های سایر کاربرانی را که به آنها دسترسی دارید، بخوانید.
    • EVENT_ID : شناسه رویداد. می‌توانید برای بازیابی شناسه‌های رویداد events.list را فراخوانی کنید.

نمونه کد را اجرا کنید

  1. بالای ویرایشگر کد، تابعی را که می‌خواهید اجرا شود از منوی کشویی انتخاب کنید و روی «اجرا» کلیک کنید.
  2. اولین باری که اسکریپت را اجرا می‌کنید، از شما خواسته می‌شود که دسترسی را تأیید کنید. بررسی کنید و به Apps Script اجازه دهید به تقویم شما دسترسی داشته باشد.
  3. شما می‌توانید نتایج اجرای اسکریپت را در گزارش اجرا که در پایین پنجره ظاهر می‌شود، بررسی کنید.