این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

انواع رویداد

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

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

نوع رویداد را می توان در مکان های زیر در API کشف کرد:

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

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

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

برای شروع کار با رویدادهای Google Calendar، به ایجاد رویدادها مراجعه کنید.

تولد

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

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

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

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

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

API امکان ایجاد رویدادهای تولد را با استفاده از روش 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 رویدادهای تولد را با استفاده از روش های update و patch می دهد. فیلدهای start و end نیز می توانند برای تغییر تاریخ رویداد به روز شوند. در این مورد، مقادیر جدید باید یک رویداد تمام روز را تعریف کنند که دقیقاً یک روز را در بر می گیرد. اگر رویداد به یک contact پیوند داده شده باشد، یا type آن 'self' باشد، جزئیات زمان رویداد تولد را نمی توان به روز کرد.

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

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

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

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

رویدادهای تولد را می توان با استفاده از روش delete Google Calendar API حذف کرد. حذف یک رویداد تولد از Google Calendar بر داده‌های Google Contacts یا نمایه حساب Google تأثیری نمی‌گذارد.

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

رویدادها از جیمیل

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

Google Calendar API اجازه ایجاد این نوع رویداد را با استفاده از روش insert نمی دهد.

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

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

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

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

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

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

Google Calendar API را می توان برای ایجاد و مدیریت رویدادهایی که وضعیت کاربران Google Calendar را نشان می دهد استفاده کرد.

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

انواع رویدادها را در Google Apps Script کاوش کنید

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

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

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

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

(اختیاری) پروژه Google Cloud را به روز کنید

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

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

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

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

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/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/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/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 : شناسه رویداد. برای بازیابی شناسه رویداد می‌توانید با فهرست رویدادها تماس بگیرید.

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

در بالای ویرایشگر کد، تابع مورد نظر را از منوی کشویی انتخاب کنید و روی Run کلیک کنید.
در اولین اجرا، از شما می خواهد که دسترسی را مجاز کنید. مرور کنید و به Apps Script اجازه دهید به تقویم شما دسترسی داشته باشد.
می توانید نتایج اجرای اسکریپت را در Execution Log که در پایین پنجره ظاهر می شود، بررسی کنید.