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

انواع رویداد

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

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

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

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

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

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

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

تولد

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

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

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

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

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

این 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' باشد، قابل به‌روزرسانی نیست.

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

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

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

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

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

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

رویدادها از Gmail

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

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

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

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

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

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

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

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

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

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

انواع رویدادها را در اسکریپت برنامه‌های گوگل بررسی کنید

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

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

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

با رفتن به script.google.com/create یک اسکریپت ایجاد کنید.
در پنل سمت چپ، کنار Services ، روی a service کلیک کنید.
API تقویم گوگل را انتخاب کنید و روی افزودن کلیک کنید.
پس از فعال‌سازی، 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/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 را فراخوانی کنید.

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

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