مستندات n8n
74+ نود
📅

گوگل کلندر

Google Calendar

مدیریت رویدادها، قرار ملاقات و تقویم با Google Calendar

ابزارهای کاری
متوسط
۰ بازدید
n8n 1.0+

نمای کلی

نود 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. 1به [Google Cloud Console](https://console.cloud.google.com/) بروید
  2. 2پروژه جدید بسازید یا پروژه موجود را انتخاب کنید
  3. 3به APIs & Services > Library بروید
  4. 4"Google Calendar API" را جستجو و Enable کنید

#### مرحله 2: تنظیم OAuth Consent Screen

  1. 1APIs & Services > OAuth consent screen
  2. 2User Type: External
  3. 3اطلاعات اپلیکیشن را پر کنید
  4. 4Scopes مورد نیاز اضافه کنید:
  • https://www.googleapis.com/auth/calendar (دسترسی کامل خواندن و نوشتن)
  • https://www.googleapis.com/auth/calendar.events (فقط رویدادها)
  • https://www.googleapis.com/auth/calendar.readonly (فقط خواندن)
  1. 1Test Users اضافه کنید

#### مرحله 3: ایجاد OAuth Credentials

  1. 1APIs & Services > Credentials
  2. 2Create Credentials > OAuth client ID
  3. 3Application type: Web application
  4. 4Authorized redirect URIs:
  • https://your-n8n.com/rest/oauth2-credential/callback
  1. 1Client ID و Client Secret را کپی کنید

#### مرحله 4: تنظیم در n8n

  1. 1Credentials > Google Calendar OAuth2 API
  2. 2Client ID و Client Secret وارد کنید
  3. 3Connect my account بزنید
  4. 4با اکانت Google وارد شوید و دسترسی‌ها را تایید کنید

روش 2: Service Account (برای سرور به سرور)

  1. 1Google Cloud Console > IAM & Admin > Service Accounts
  2. 2Service Account جدید بسازید
  3. 3JSON Key فایل دانلود کنید
  4. 4تقویم مورد نظر را با ایمیل Service Account به اشتراک بگذارید
  5. 5در n8n: Service Account JSON وارد کنید

نکات امنیتی:

  • حداقل Scope لازم را انتخاب کنید
  • Client Secret را به اشتراک نگذارید
  • در Production از Service Account استفاده کنید

عملیات‌های موجود

1

createEvent

ایجاد رویداد جدید در تقویم با تنظیم زمان، شرکت‌کنندگان و یادآوری

2

getEvent

دریافت جزئیات کامل یک رویداد با شناسه آن

3

updateEvent

ویرایش اطلاعات رویداد موجود (عنوان، زمان، شرکت‌کنندگان و...)

4

deleteEvent

حذف یک رویداد از تقویم

5

listEvents

دریافت لیست رویدادها با فیلترهای زمانی و جستجو

6

moveEvent

انتقال رویداد از یک تقویم به تقویم دیگر

7

quickAddEvent

ایجاد رویداد با متن طبیعی (مثل: "جلسه تیم فردا ساعت 10 صبح")

8

getCalendar

دریافت جزئیات یک تقویم خاص

9

listCalendars

دریافت لیست تمام تقویم‌های کاربر

10

createCalendar

ایجاد تقویم جدید

11

clearCalendar

حذف تمام رویدادهای یک تقویم

12

getFreeBusy

بررسی وضعیت Free/Busy یک یا چند تقویم در بازه زمانی

13

addAttendee

افزودن شرکت‌کننده جدید به رویداد موجود

14

setReminder

تنظیم یا تغییر یادآوری‌های سفارشی برای رویداد

کاربردهای متداول

1. زمان‌بندی خودکار جلسات تیمی

ایجاد جلسه Standup روزانه:

code
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. یادآوری تولدها و سالگردها

اعلان خودکار مناسبت‌ها:

code
Google Calendar Trigger (رویداد تولد شروع شد)
  → Set (استخراج نام و تاریخ)
  → Telegram (sendMessage)
    Text: "امروز تولد {{$json.summary}} است!"
  → Gmail (ارسال ایمیل تبریک)

3. ایجاد خودکار Standup برای تیم

ثبت جلسه تکراری هفتگی:

code
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. سیستم رزرو و نوبت‌دهی

بررسی وقت آزاد و ثبت قرار:

code
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

مدیریت خودکار شیفت‌های کاری:

code
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. تقویم انتشار محتوا

برنامه‌ریزی انتشار پست‌ها:

code
Google Calendar Trigger (رویداد "انتشار:" شروع شد)
  → Code (استخراج اطلاعات پست)
  → WordPress (انتشار پست)
  → Telegram (اطلاع‌رسانی به کانال)
  → Google Calendar (updateEvent)
    ColorId: 10 (سبز = منتشر شده)

7. یادآوری سررسید فاکتورها

هشدار قبل از موعد پرداخت:

code
MySQL (فاکتورهای پرداخت نشده)
  → Loop
    → Google Calendar (createEvent)
      Summary: "سررسید فاکتور #{{$json.invoiceId}}"
      Start: {{$json.dueDate}}
      Reminders: [
        {method: email, minutes: 1440},
        {method: popup, minutes: 60}
      ]
      ColorId: 11 (قرمز = مهم)

8. ردیابی Milestone پروژه

ثبت خودکار مایلستون‌ها:

code
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 وقت‌های آزاد:

code
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 و تقویم‌های دیگر:

code
Google Calendar Trigger (رویداد جدید/تغییر یافته)
  → IF (رویداد جدید)
    → Outlook Calendar (ایجاد رویداد)
  → IF (رویداد تغییر کرده)
    → Outlook Calendar (به‌روزرسانی)
  → IF (رویداد حذف شده)
    → Outlook Calendar (حذف)

نکات حرفه‌ای

نکات حرفه‌ای

  1. 1مدیریت Timezone با فرمت IANA: همیشه از فرمت استاندارد استفاده کنید:
code
Asia/Tehran    → ایران
   Europe/London  → لندن
   America/New_York → نیویورک
   UTC            → جهانی
  1. 1رویدادهای تکراری با RRULE: ساخت قوانین تکرار:
code
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. 1ایجاد لینک Google Meet: اضافه کردن ویدیوکنفرانس:
json
{
     "conferenceData": {
       "createRequest": {
         "requestId": "unique-id-123",
         "conferenceSolutionKey": {"type": "hangoutsMeet"}
       }
     },
     "conferenceDataVersion": 1
   }
  1. 1Extended Properties برای متادیتا: ذخیره داده سفارشی:
json
{
     "extendedProperties": {
       "private": {"source": "n8n", "workflowId": "123"},
       "shared": {"category": "meeting"}
     }
   }
  1. 1ColorId برای دسته‌بندی بصری: شماره رنگ‌ها:
code
1: آبی کمرنگ (Lavender)
   2: سبز (Sage)
   3: بنفش (Grape)
   4: صورتی (Flamingo)
   5: زرد (Banana)
   6: نارنجی (Tangerine)
   7: فیروزه‌ای (Peacock)
   8: خاکستری (Graphite)
   9: آبی (Blueberry)
   10: سبز تیره (Basil)
   11: قرمز (Tomato)
  1. 1**استفاده از calendarId 'primary'**: برای تقویم پیش‌فرض کاربر همیشه از primary استفاده کنید، نیازی به شناسه واقعی نیست.
  1. 1وضعیت پاسخ شرکت‌کنندگان (Attendee Response Status):
code
needsAction → هنوز پاسخ نداده
   accepted    → پذیرفته
   declined    → رد کرده
   tentative   → شاید
  1. 1**Override یادآوری پیش‌فرض**: وقتی useDefault: false تنظیم کنید، یادآوری‌های پیش‌فرض تقویم اعمال نمی‌شوند:
json
{
     "reminders": {
       "useDefault": false,
       "overrides": [
         {"method": "email", "minutes": 1440},
         {"method": "popup", "minutes": 30}
       ]
     }
   }
  1. 1**فرمت رویداد تمام‌روز (All-Day)**: به جای dateTime از date استفاده کنید:
json
{
     "start": {"date": "2024-03-21"},
     "end": {"date": "2024-03-22"}
   }

توجه: تاریخ پایان یک روز بعد از آخرین روز رویداد است.

  1. 1Quick Add با زبان طبیعی: Google متن را خودکار Parse می‌کند:
code
"Meeting with Ali tomorrow at 3pm for 1 hour"
    "Team lunch every Friday at 12:30"
    "Doctor appointment on March 15 at 10am"
  1. 1پیوست فایل به رویداد (Event Attachments):
json
{
      "attachments": [{
        "fileUrl": "https://drive.google.com/file/d/FILE_ID",
        "title": "صورتجلسه",
        "mimeType": "application/pdf"
      }]
    }

نکته: برای پیوست، supportsAttachments: true باید ارسال شود.

  1. 1شناسه تقویم مشترک: برای تقویم‌های Shared از ایمیل‌شان استفاده کنید:
code
team-calendar@group.calendar.google.com
    fa.iranian#holiday@group.v.calendar.google.com (تقویم تعطیلات ایران)
  1. 1Watch برای Push Notifications: به جای Polling از Watch استفاده کنید:
code
POST /calendars/primary/events/watch
    {
      "id": "unique-channel-id",
      "type": "web_hook",
      "address": "https://your-n8n.com/webhook/calendar"
    }

Watch هر 7 روز باید تمدید شود.

  1. 1maxResults و Pagination: برای لیست‌های بزرگ:
code
maxResults: 100 (حداکثر 2500)
    nextPageToken → در درخواست بعدی pageToken قرار دهید
  1. 1Sync Token برای همگام‌سازی تدریجی: فقط تغییرات جدید را دریافت کنید:
code
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 یکتا استفاده کنید
  • قبل از ایجاد، بررسی کنید آیا رویداد از قبل وجود دارد
  • از upsert logic استفاده کنید: ابتدا 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 منقضی می‌شود
اشتراک‌گذاری:

آیا این مستندات مفید بود؟