گوگل کلندر
Google Calendar
مدیریت رویدادها، قرار ملاقات و تقویم با Google Calendar
نمای کلی
نود Google Calendar ابزاری قدرتمند برای مدیریت خودکار تقویم و رویدادها در n8n است.
قابلیتهای کلیدی:
- ایجاد، خواندن، ویرایش و حذف رویدادها (Events CRUD)
- پشتیبانی از رویدادهای تکراری (Recurring Events) با RRULE
- مدیریت شرکتکنندگان (Attendees) و ارسال دعوتنامه
- تنظیم یادآوری (Reminders) ایمیلی و اعلانی
- اشتراکگذاری و مدیریت تقویمها
- بررسی وضعیت آزاد/مشغول (Free/Busy Check)
- پشتیبانی کامل از Timezone با فرمت IANA
- رنگبندی رویدادها (Color Coding) برای دستهبندی بصری
- ایجاد خودکار لینک Google Meet (Conference Data)
- پشتیبانی از رویدادهای تمامروز (All-Day Events)
قابلیتهای Trigger:
- اجرا هنگام ایجاد رویداد جدید (Event Created)
- اجرا هنگام بهروزرسانی رویداد (Event Updated)
- اجرا هنگام شروع رویداد (Event Started)
- فیلتر بر اساس تقویم خاص
کاربردها:
- زمانبندی خودکار جلسات تیمی
- سیستم رزرو و نوبتدهی آنلاین
- همگامسازی تقویم بین پلتفرمها
- اعلان هوشمند قبل از رویدادها
- مدیریت شیفتهای کاری و On-Call
- تقویم انتشار محتوا
- ردیابی Milestoneهای پروژه
احراز هویت
احراز هویت Google Calendar
روش 1: OAuth2 (توصیه میشود)
#### مرحله 1: ایجاد پروژه در Google Cloud Console
- 1به [Google Cloud Console](https://console.cloud.google.com/) بروید
- 2پروژه جدید بسازید یا پروژه موجود را انتخاب کنید
- 3به APIs & Services > Library بروید
- 4"Google Calendar API" را جستجو و Enable کنید
#### مرحله 2: تنظیم OAuth Consent Screen
- 1APIs & Services > OAuth consent screen
- 2User Type: External
- 3اطلاعات اپلیکیشن را پر کنید
- 4Scopes مورد نیاز اضافه کنید:
https://www.googleapis.com/auth/calendar(دسترسی کامل خواندن و نوشتن)https://www.googleapis.com/auth/calendar.events(فقط رویدادها)https://www.googleapis.com/auth/calendar.readonly(فقط خواندن)
- 1Test Users اضافه کنید
#### مرحله 3: ایجاد OAuth Credentials
- 1APIs & Services > Credentials
- 2Create Credentials > OAuth client ID
- 3Application type: Web application
- 4Authorized redirect URIs:
https://your-n8n.com/rest/oauth2-credential/callback
- 1Client ID و Client Secret را کپی کنید
#### مرحله 4: تنظیم در n8n
- 1Credentials > Google Calendar OAuth2 API
- 2Client ID و Client Secret وارد کنید
- 3Connect my account بزنید
- 4با اکانت Google وارد شوید و دسترسیها را تایید کنید
روش 2: Service Account (برای سرور به سرور)
- 1Google Cloud Console > IAM & Admin > Service Accounts
- 2Service Account جدید بسازید
- 3JSON Key فایل دانلود کنید
- 4تقویم مورد نظر را با ایمیل Service Account به اشتراک بگذارید
- 5در n8n: Service Account JSON وارد کنید
نکات امنیتی:
- حداقل Scope لازم را انتخاب کنید
- Client Secret را به اشتراک نگذارید
- در Production از Service Account استفاده کنید
عملیاتهای موجود
createEvent
ایجاد رویداد جدید در تقویم با تنظیم زمان، شرکتکنندگان و یادآوری
getEvent
دریافت جزئیات کامل یک رویداد با شناسه آن
updateEvent
ویرایش اطلاعات رویداد موجود (عنوان، زمان، شرکتکنندگان و...)
deleteEvent
حذف یک رویداد از تقویم
listEvents
دریافت لیست رویدادها با فیلترهای زمانی و جستجو
moveEvent
انتقال رویداد از یک تقویم به تقویم دیگر
quickAddEvent
ایجاد رویداد با متن طبیعی (مثل: "جلسه تیم فردا ساعت 10 صبح")
getCalendar
دریافت جزئیات یک تقویم خاص
listCalendars
دریافت لیست تمام تقویمهای کاربر
createCalendar
ایجاد تقویم جدید
clearCalendar
حذف تمام رویدادهای یک تقویم
getFreeBusy
بررسی وضعیت Free/Busy یک یا چند تقویم در بازه زمانی
addAttendee
افزودن شرکتکننده جدید به رویداد موجود
setReminder
تنظیم یا تغییر یادآوریهای سفارشی برای رویداد
کاربردهای متداول
1. زمانبندی خودکار جلسات تیمی
ایجاد جلسه Standup روزانه:
Schedule (هر روز هفته ساعت 9 صبح)
→ Google Calendar (createEvent)
CalendarId: primary
Summary: "جلسه Standup روزانه"
Start: {{$now.plus({hours: 1}).toISO()}}
End: {{$now.plus({hours: 1, minutes: 30}).toISO()}}
TimeZone: Asia/Tehran
Attendees: ["dev1@company.com", "dev2@company.com"]
ConferenceData: Google Meet
Reminders: [{method: popup, minutes: 10}]2. یادآوری تولدها و سالگردها
اعلان خودکار مناسبتها:
Google Calendar Trigger (رویداد تولد شروع شد)
→ Set (استخراج نام و تاریخ)
→ Telegram (sendMessage)
Text: "امروز تولد {{$json.summary}} است!"
→ Gmail (ارسال ایمیل تبریک)3. ایجاد خودکار Standup برای تیم
ثبت جلسه تکراری هفتگی:
Webhook (درخواست ایجاد جلسه تکراری)
→ Google Calendar (createEvent)
Summary: "Sprint Planning"
Recurrence: ["RRULE:FREQ=WEEKLY;BYDAY=SA;COUNT=12"]
Attendees: {{$json.teamEmails}}
ConferenceData: createRequest (Google Meet)
→ Telegram (ارسال لینک Meet به گروه)4. سیستم رزرو و نوبتدهی
بررسی وقت آزاد و ثبت قرار:
Webhook (درخواست رزرو)
→ Google Calendar (getFreeBusy)
TimeMin: {{$json.requestedTime}}
TimeMax: {{$json.requestedTime + 1hour}}
→ IF (آزاد است)
→ Google Calendar (createEvent)
Summary: "نوبت: {{$json.clientName}}"
Attendees: [{{$json.clientEmail}}]
→ Telegram (تایید رزرو)
→ Else
→ Respond (زمان مشغول، پیشنهاد زمان دیگر)5. زمانبندی شیفت و On-Call
مدیریت خودکار شیفتهای کاری:
Schedule (اول هر هفته)
→ MySQL (لیست شیفتها)
→ Loop
→ Google Calendar (createEvent)
Summary: "شیفت: {{$json.employeeName}}"
Start: {{$json.shiftStart}}
End: {{$json.shiftEnd}}
ColorId: {{$json.shiftType === 'night' ? '11' : '9'}}
Reminders: [{method: popup, minutes: 60}]6. تقویم انتشار محتوا
برنامهریزی انتشار پستها:
Google Calendar Trigger (رویداد "انتشار:" شروع شد)
→ Code (استخراج اطلاعات پست)
→ WordPress (انتشار پست)
→ Telegram (اطلاعرسانی به کانال)
→ Google Calendar (updateEvent)
ColorId: 10 (سبز = منتشر شده)7. یادآوری سررسید فاکتورها
هشدار قبل از موعد پرداخت:
MySQL (فاکتورهای پرداخت نشده)
→ Loop
→ Google Calendar (createEvent)
Summary: "سررسید فاکتور #{{$json.invoiceId}}"
Start: {{$json.dueDate}}
Reminders: [
{method: email, minutes: 1440},
{method: popup, minutes: 60}
]
ColorId: 11 (قرمز = مهم)8. ردیابی Milestone پروژه
ثبت خودکار مایلستونها:
Webhook (milestone ایجاد شد در Jira/Trello)
→ Google Calendar (createEvent)
Summary: "Milestone: {{$json.name}}"
Description: "پروژه: {{$json.project}}\nوضعیت: {{$json.status}}"
Start: {{$json.deadline}} (All-Day Event)
ColorId: 5 (زرد)
→ Telegram (اعلان به تیم)9. بررسی وقت آزاد برای قرار ملاقات
API وقتهای آزاد:
Webhook (درخواست وقت آزاد)
→ Google Calendar (getFreeBusy)
TimeMin: {{$json.date}}T08:00:00
TimeMax: {{$json.date}}T18:00:00
Items: ["primary", "work@company.com"]
→ Code (محاسبه بازههای آزاد)
→ Respond to Webhook (لیست وقتهای خالی)10. همگامسازی تقویمها
Sync بین Google Calendar و تقویمهای دیگر:
Google Calendar Trigger (رویداد جدید/تغییر یافته)
→ IF (رویداد جدید)
→ Outlook Calendar (ایجاد رویداد)
→ IF (رویداد تغییر کرده)
→ Outlook Calendar (بهروزرسانی)
→ IF (رویداد حذف شده)
→ Outlook Calendar (حذف)نکات حرفهای
نکات حرفهای
- 1مدیریت Timezone با فرمت IANA: همیشه از فرمت استاندارد استفاده کنید:
Asia/Tehran → ایران
Europe/London → لندن
America/New_York → نیویورک
UTC → جهانی- 1رویدادهای تکراری با RRULE: ساخت قوانین تکرار:
RRULE:FREQ=DAILY;COUNT=30 → 30 روز متوالی
RRULE:FREQ=WEEKLY;BYDAY=SA,MO → هر شنبه و دوشنبه
RRULE:FREQ=MONTHLY;BYMONTHDAY=1 → اول هر ماه
RRULE:FREQ=YEARLY;BYMONTH=3;BYMONTHDAY=21 → نوروز
RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=TU → هر دو هفته سهشنبه- 1ایجاد لینک Google Meet: اضافه کردن ویدیوکنفرانس:
{
"conferenceData": {
"createRequest": {
"requestId": "unique-id-123",
"conferenceSolutionKey": {"type": "hangoutsMeet"}
}
},
"conferenceDataVersion": 1
}- 1Extended Properties برای متادیتا: ذخیره داده سفارشی:
{
"extendedProperties": {
"private": {"source": "n8n", "workflowId": "123"},
"shared": {"category": "meeting"}
}
}- 1ColorId برای دستهبندی بصری: شماره رنگها:
1: آبی کمرنگ (Lavender)
2: سبز (Sage)
3: بنفش (Grape)
4: صورتی (Flamingo)
5: زرد (Banana)
6: نارنجی (Tangerine)
7: فیروزهای (Peacock)
8: خاکستری (Graphite)
9: آبی (Blueberry)
10: سبز تیره (Basil)
11: قرمز (Tomato)- 1**استفاده از calendarId 'primary'**: برای تقویم پیشفرض کاربر همیشه از
primaryاستفاده کنید، نیازی به شناسه واقعی نیست.
- 1وضعیت پاسخ شرکتکنندگان (Attendee Response Status):
needsAction → هنوز پاسخ نداده
accepted → پذیرفته
declined → رد کرده
tentative → شاید- 1**Override یادآوری پیشفرض**: وقتی
useDefault: falseتنظیم کنید، یادآوریهای پیشفرض تقویم اعمال نمیشوند:
{
"reminders": {
"useDefault": false,
"overrides": [
{"method": "email", "minutes": 1440},
{"method": "popup", "minutes": 30}
]
}
}- 1**فرمت رویداد تمامروز (All-Day)**: به جای
dateTimeازdateاستفاده کنید:
{
"start": {"date": "2024-03-21"},
"end": {"date": "2024-03-22"}
}توجه: تاریخ پایان یک روز بعد از آخرین روز رویداد است.
- 1Quick Add با زبان طبیعی: Google متن را خودکار Parse میکند:
"Meeting with Ali tomorrow at 3pm for 1 hour"
"Team lunch every Friday at 12:30"
"Doctor appointment on March 15 at 10am"- 1پیوست فایل به رویداد (Event Attachments):
{
"attachments": [{
"fileUrl": "https://drive.google.com/file/d/FILE_ID",
"title": "صورتجلسه",
"mimeType": "application/pdf"
}]
}نکته: برای پیوست، supportsAttachments: true باید ارسال شود.
- 1شناسه تقویم مشترک: برای تقویمهای Shared از ایمیلشان استفاده کنید:
team-calendar@group.calendar.google.com
fa.iranian#holiday@group.v.calendar.google.com (تقویم تعطیلات ایران)- 1Watch برای Push Notifications: به جای Polling از Watch استفاده کنید:
POST /calendars/primary/events/watch
{
"id": "unique-channel-id",
"type": "web_hook",
"address": "https://your-n8n.com/webhook/calendar"
}Watch هر 7 روز باید تمدید شود.
- 1maxResults و Pagination: برای لیستهای بزرگ:
maxResults: 100 (حداکثر 2500)
nextPageToken → در درخواست بعدی pageToken قرار دهید- 1Sync Token برای همگامسازی تدریجی: فقط تغییرات جدید را دریافت کنید:
1. listEvents → syncToken دریافت کنید
2. درخواست بعدی: syncToken ارسال کنید
3. فقط رویدادهای تغییر یافته برمیگردد
4. اگر syncToken منقضی شد (410 Gone)، Full Sync کنیدرفع مشکلات
خطاهای رایج و راهحلها
1. خطای 403 - Insufficient Permissions
علت: دسترسی کافی به تقویم یا Calendar API ندارید
راهحل
- مطمئن شوید Calendar API در Google Cloud Console فعال است
- Scope مناسب انتخاب کنید:
calendarبرای خواندن و نوشتن - اگر تقویم مشترک است، مطمئن شوید دسترسی ویرایش دارید
- Credential را حذف و دوباره Connect کنید
2. خطای 404 - Calendar/Event Not Found
علت: شناسه تقویم یا رویداد اشتباه است
راهحل
- از
primaryبرای تقویم پیشفرض استفاده کنید - Event ID را از خروجی listEvents یا createEvent بگیرید
- اگر Service Account است، تقویم را با ایمیل آن Share کنید
- بررسی کنید رویداد قبلاً حذف نشده باشد
3. خطای 409 - Conflict (Already Exists)
علت: تلاش برای ایجاد رویداد تکراری با ID یکسان
راهحل
- از Event ID یکتا استفاده کنید
- قبل از ایجاد، بررسی کنید آیا رویداد از قبل وجود دارد
- از
upsertlogic استفاده کنید: ابتدا GET، سپس CREATE یا UPDATE
4. خطای Rate Limit (429)
علت: تعداد درخواستها از حد مجاز بیشتر شده
راهحل
- محدودیت: 1,000,000 درخواست در روز (پروژه)
- بین درخواستها Wait اضافه کنید
- از Batch درخواستها استفاده کنید
- Exponential Backoff برای Retry
- از
syncTokenبرای کاهش درخواستها استفاده کنید
5. مشکلات Timezone
علت: عدم تطابق منطقه زمانی بین رویداد و تقویم
راهحل
- همیشه
timeZoneرا صریحاً مشخص کنید - از فرمت IANA استفاده کنید:
Asia/Tehran - برای UTC از
Zدر انتهای ISO 8601 استفاده کنید - زمان شروع و پایان را در یک Timezone بفرستید
dateTimeبرای رویداد ساعتی،dateبرای تمامروز
6. مشکلات ویرایش رویدادهای تکراری
علت: رویداد تکراری Instance و Series متفاوت دارد
راهحل
- برای ویرایش یک نمونه: از Event ID آن Instance استفاده کنید
- برای ویرایش کل سری: از Recurring Event ID اصلی استفاده کنید
- Instance ID فرمت:
eventId_20240101T090000Z singleEvents: trueدر listEvents برای دیدن همه نمونهها
7. مشکل ارسال اعلان به شرکتکنندگان
علت: تنظیمات sendUpdates اشتباه
راهحل
sendUpdates: allبرای اعلان به همهsendUpdates: externalOnlyفقط افراد خارج سازمانsendUpdates: noneبدون اعلان- مطمئن شوید ایمیل شرکتکنندگان معتبر است
8. خطای OAuth Token Refresh
علت: توکن منقضی شده یا Revoke شده
راهحل
- Credential را Disconnect و مجدداً Connect کنید
- بررسی کنید Google Cloud Console > OAuth consent screen فعال باشد
- Test Users (در حالت Testing) منقضی نشده باشد
- اگر حالت Production نیست، هر 7 روز Token منقضی میشود
