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

برنامه ای را تصور کنید که به کاربران کمک می کند بهترین مسیرهای پیاده روی را پیدا کنند. با افزودن برنامه پیاده روی به عنوان یک رویداد تقویمی، کاربران کمک زیادی در سازماندهی خود به خود دریافت می کنند. Google Calendar به آنها کمک می کند تا برنامه را به اشتراک بگذارند و آن را به آنها یادآوری می کند تا بتوانند بدون استرس آماده شوند. همچنین، به لطف ادغام یکپارچه محصولات Google، Google Now آنها را در مورد زمان خروج پینگ می کند و Google Maps آنها را به موقع به محل جلسه هدایت می کند.

این مقاله نحوه ایجاد رویدادهای تقویم و افزودن آنها به تقویم کاربران خود را توضیح می دهد.

یک رویداد اضافه کنید

برای ایجاد یک رویداد، متد events.insert() را فراخوانی کنید که حداقل این پارامترها را ارائه می دهد:

• calendarId شناسه تقویم است و می‌تواند آدرس ایمیل تقویمی باشد که روی آن رویداد ایجاد می‌شود یا یک کلمه کلیدی ویژه 'primary' که از تقویم اولیه کاربر وارد شده استفاده می‌کند. اگر آدرس ایمیل تقویمی را که می‌خواهید استفاده کنید نمی‌دانید، می‌توانید آن را در تنظیمات تقویم در رابط کاربری وب Google Calendar (در بخش «آدرس تقویم») بررسی کنید یا می‌توانید آن را در نتیجه calendarList.list() .
• event رویدادی است برای ایجاد با تمام جزئیات لازم مانند شروع و پایان. تنها دو قسمت مورد نیاز زمان start و end است. برای مجموعه کامل فیلدهای رویداد به مرجع event مراجعه کنید.
  با استفاده از فیلدهای start.dateTime و end.dateTime رویدادهای زمان بندی شده را مشخص کنید. برای رویدادهای تمام روز، به جای آن از start.date و end.date استفاده کنید.

برای ایجاد موفقیت آمیز رویدادها، باید:

• محدوده OAuth خود را روی https://www.googleapis.com/auth/calendar تنظیم کنید تا دسترسی ویرایش به تقویم کاربر داشته باشید.
• مطمئن شوید که کاربر احراز هویت شده با calendarId که ارائه کرده‌اید، به تقویم دسترسی دارد (برای مثال با فراخوانی calendarList.get() برای calendarId و بررسی accessRole ).

ابرداده رویداد را اضافه کنید

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

محل

افزودن آدرس به فیلد موقعیت مکانی ویژگی هایی مانند

"زمان ترک" یا نمایش یک نقشه با جهت.

شناسه رویداد

هنگام ایجاد یک رویداد، می توانید انتخاب کنید که شناسه رویداد خود را ایجاد کنید

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

شرکت کنندگان

رویدادی که ایجاد می‌کنید در همه تقویم‌های اصلی Google ظاهر می‌شود

شرکت کنندگانی که با همان شناسه رویداد وارد کردید. اگر sendNotifications را در درخواست درج true تنظیم کنید، شرکت‌کنندگان همچنین یک اعلان ایمیلی برای رویداد شما دریافت خواهند کرد. برای اطلاعات بیشتر، رویدادها را با راهنمای چند شرکت کننده ببینید.

مثال‌های زیر ایجاد یک رویداد و تنظیم ابرداده آن را نشان می‌دهند:

برو

// Refer to the Go quickstart on how to setup the environment:
// https://developers.google.com/calendar/quickstart/go
// Change the scope to calendar.CalendarScope and delete any stored credentials.

event := &calendar.Event{
  Summary: "Google I/O 2015",
  Location: "800 Howard St., San Francisco, CA 94103",
  Description: "A chance to hear more about Google's developer products.",
  Start: &calendar.EventDateTime{
    DateTime: "2015-05-28T09:00:00-07:00",
    TimeZone: "America/Los_Angeles",
  },
  End: &calendar.EventDateTime{
    DateTime: "2015-05-28T17:00:00-07:00",
    TimeZone: "America/Los_Angeles",
  },
  Recurrence: []string{"RRULE:FREQ=DAILY;COUNT=2"},
  Attendees: []*calendar.EventAttendee{
    &calendar.EventAttendee{Email:"[e-mail]"},
    &calendar.EventAttendee{Email:"[e-mail]"},
  },
}

calendarId := "primary"
event, err = srv.Events.Insert(calendarId, event).Do()
if err != nil {
  log.Fatalf("Unable to create event. %v\n", err)
}
fmt.Printf("Event created: %s\n", event.HtmlLink)

جاوا

// Refer to the Java quickstart on how to setup the environment:
// https://developers.google.com/calendar/quickstart/java
// Change the scope to CalendarScopes.CALENDAR and delete any stored
// credentials.

Event event = new Event()
    .setSummary("Google I/O 2015")
    .setLocation("800 Howard St., San Francisco, CA 94103")
    .setDescription("A chance to hear more about Google's developer products.");

DateTime startDateTime = new DateTime("2015-05-28T09:00:00-07:00");
EventDateTime start = new EventDateTime()
    .setDateTime(startDateTime)
    .setTimeZone("America/Los_Angeles");
event.setStart(start);

DateTime endDateTime = new DateTime("2015-05-28T17:00:00-07:00");
EventDateTime end = new EventDateTime()
    .setDateTime(endDateTime)
    .setTimeZone("America/Los_Angeles");
event.setEnd(end);

String[] recurrence = new String[] {"RRULE:FREQ=DAILY;COUNT=2"};
event.setRecurrence(Arrays.asList(recurrence));

EventAttendee[] attendees = new EventAttendee[] {
    new EventAttendee().setEmail("[e-mail]"),
    new EventAttendee().setEmail("[e-mail]"),
};
event.setAttendees(Arrays.asList(attendees));

EventReminder[] reminderOverrides = new EventReminder[] {
    new EventReminder().setMethod("email").setMinutes(24 * 60),
    new EventReminder().setMethod("popup").setMinutes(10),
};
Event.Reminders reminders = new Event.Reminders()
    .setUseDefault(false)
    .setOverrides(Arrays.asList(reminderOverrides));
event.setReminders(reminders);

String calendarId = "primary";
event = service.events().insert(calendarId, event).execute();
System.out.printf("Event created: %s\n", event.getHtmlLink());

جاوا اسکریپت

// Refer to the JavaScript quickstart on how to setup the environment:
// https://developers.google.com/calendar/quickstart/js
// Change the scope to 'https://www.googleapis.com/auth/calendar' and delete any
// stored credentials.

const event = {
  'summary': 'Google I/O 2015',
  'location': '800 Howard St., San Francisco, CA 94103',
  'description': 'A chance to hear more about Google\'s developer products.',
  'start': {
    'dateTime': '2015-05-28T09:00:00-07:00',
    'timeZone': 'America/Los_Angeles'
  },
  'end': {
    'dateTime': '2015-05-28T17:00:00-07:00',
    'timeZone': 'America/Los_Angeles'
  },
  'recurrence': [
    'RRULE:FREQ=DAILY;COUNT=2'
  ],
  'attendees': [
    {'email': '[e-mail]'},
    {'email': '[e-mail]'}
  ],
  'reminders': {
    'useDefault': false,
    'overrides': [
      {'method': 'email', 'minutes': 24 * 60},
      {'method': 'popup', 'minutes': 10}
    ]
  }
};

const request = gapi.client.calendar.events.insert({
  'calendarId': 'primary',
  'resource': event
});

request.execute(function(event) {
  appendPre('Event created: ' + event.htmlLink);
});

Node.js

// Refer to the Node.js quickstart on how to setup the environment:
// https://developers.google.com/calendar/quickstart/node
// Change the scope to 'https://www.googleapis.com/auth/calendar' and delete any
// stored credentials.

const event = {
  'summary': 'Google I/O 2015',
  'location': '800 Howard St., San Francisco, CA 94103',
  'description': 'A chance to hear more about Google\'s developer products.',
  'start': {
    'dateTime': '2015-05-28T09:00:00-07:00',
    'timeZone': 'America/Los_Angeles',
  },
  'end': {
    'dateTime': '2015-05-28T17:00:00-07:00',
    'timeZone': 'America/Los_Angeles',
  },
  'recurrence': [
    'RRULE:FREQ=DAILY;COUNT=2'
  ],
  'attendees': [
    {'email': '[e-mail]'},
    {'email': '[e-mail]'},
  ],
  'reminders': {
    'useDefault': false,
    'overrides': [
      {'method': 'email', 'minutes': 24 * 60},
      {'method': 'popup', 'minutes': 10},
    ],
  },
};

calendar.events.insert({
  auth: auth,
  calendarId: 'primary',
  resource: event,
}, function(err, event) {
  if (err) {
    console.log('There was an error contacting the Calendar service: ' + err);
    return;
  }
  console.log('Event created: %s', event.htmlLink);
});

PHP

$event = new Google_Service_Calendar_Event(array(
  'summary' => 'Google I/O 2015',
  'location' => '800 Howard St., San Francisco, CA 94103',
  'description' => 'A chance to hear more about Google\'s developer products.',
  'start' => array(
    'dateTime' => '2015-05-28T09:00:00-07:00',
    'timeZone' => 'America/Los_Angeles',
  ),
  'end' => array(
    'dateTime' => '2015-05-28T17:00:00-07:00',
    'timeZone' => 'America/Los_Angeles',
  ),
  'recurrence' => array(
    'RRULE:FREQ=DAILY;COUNT=2'
  ),
  'attendees' => array(
    array('email' => '[e-mail]'),
    array('email' => '[e-mail]'),
  ),
  'reminders' => array(
    'useDefault' => FALSE,
    'overrides' => array(
      array('method' => 'email', 'minutes' => 24 * 60),
      array('method' => 'popup', 'minutes' => 10),
    ),
  ),
));

$calendarId = 'primary';
$event = $service->events->insert($calendarId, $event);
printf('Event created: %s\n', $event->htmlLink);

پایتون

# Refer to the Python quickstart on how to setup the environment:
# https://developers.google.com/calendar/quickstart/python
# Change the scope to 'https://www.googleapis.com/auth/calendar' and delete any
# stored credentials.

event = {
  'summary': 'Google I/O 2015',
  'location': '800 Howard St., San Francisco, CA 94103',
  'description': 'A chance to hear more about Google\'s developer products.',
  'start': {
    'dateTime': '2015-05-28T09:00:00-07:00',
    'timeZone': 'America/Los_Angeles',
  },
  'end': {
    'dateTime': '2015-05-28T17:00:00-07:00',
    'timeZone': 'America/Los_Angeles',
  },
  'recurrence': [
    'RRULE:FREQ=DAILY;COUNT=2'
  ],
  'attendees': [
    {'email': '[e-mail]'},
    {'email': '[e-mail]'},
  ],
  'reminders': {
    'useDefault': False,
    'overrides': [
      {'method': 'email', 'minutes': 24 * 60},
      {'method': 'popup', 'minutes': 10},
    ],
  },
}

event = service.events().insert(calendarId='primary', body=event).execute()
print 'Event created: %s' % (event.get('htmlLink'))

روبی

event = Google::Apis::CalendarV3::Event.new(
  summary: 'Google I/O 2015',
  location: '800 Howard St., San Francisco, CA 94103',
  description: 'A chance to hear more about Google\'s developer products.',
  start: Google::Apis::CalendarV3::EventDateTime.new(
    date_time: '2015-05-28T09:00:00-07:00',
    time_zone: 'America/Los_Angeles'
  ),
  end: Google::Apis::CalendarV3::EventDateTime.new(
    date_time: '2015-05-28T17:00:00-07:00',
    time_zone: 'America/Los_Angeles'
  ),
  recurrence: [
    'RRULE:FREQ=DAILY;COUNT=2'
  ],
  attendees: [
    Google::Apis::CalendarV3::EventAttendee.new(
      email: '[e-mail]'
    ),
    Google::Apis::CalendarV3::EventAttendee.new(
      email: '[e-mail]'
    )
  ],
  reminders: Google::Apis::CalendarV3::Event::Reminders.new(
    use_default: false,
    overrides: [
      Google::Apis::CalendarV3::EventReminder.new(
        reminder_method: 'email',
        minutes: 24 * 60
      ),
      Google::Apis::CalendarV3::EventReminder.new(
        reminder_method: 'popup',
        minutes: 10
      )
    ]
  )
)

result = client.insert_event('primary', event)
puts "Event created: #{result.html_link}"

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

می‌توانید فایل‌های Google Drive مانند یادداشت‌های جلسه در Docs، بودجه‌ها در کاربرگ‌نگار، ارائه‌ها در اسلایدنگار یا هر فایل مرتبط Google Drive دیگر را به رویدادهای تقویم خود پیوست کنید. هنگام ایجاد یک رویداد با events.insert() یا بعد از آن به عنوان بخشی از یک به روز رسانی مانند events.patch() می توانید پیوست را اضافه کنید.

دو بخش پیوست کردن یک فایل Google Drive به یک رویداد عبارتند از:

1. آدرس فایل alternateLink ، title و mimeType از منبع Drive API Files ، معمولاً با روش files.get() دریافت کنید.
2. با فیلدهای attachments تنظیم شده در بدنه درخواست و پارامتر supportsAttachments که روی true تنظیم شده است، یک رویداد ایجاد یا به روز کنید.

مثال کد زیر نحوه به روز رسانی یک رویداد موجود برای افزودن یک پیوست را نشان می دهد:

جاوا

public static void addAttachment(Calendar calendarService, Drive driveService, String calendarId,
    String eventId, String fileId) throws IOException {
  File file = driveService.files().get(fileId).execute();
  Event event = calendarService.events().get(calendarId, eventId).execute();

  List<EventAttachment> attachments = event.getAttachments();
  if (attachments == null) {
    attachments = new ArrayList<EventAttachment>();
  }
  attachments.add(new EventAttachment()
      .setFileUrl(file.getAlternateLink())
      .setMimeType(file.getMimeType())
      .setTitle(file.getTitle()));

  Event changes = new Event()
      .setAttachments(attachments);
  calendarService.events().patch(calendarId, eventId, changes)
      .setSupportsAttachments(true)
      .execute();
}

PHP

function addAttachment($calendarService, $driveService, $calendarId, $eventId, $fileId) {
  $file = $driveService->files->get($fileId);
  $event = $calendarService->events->get($calendarId, $eventId);
  $attachments = $event->attachments;

  $attachments[] = array(
    'fileUrl' => $file->alternateLink,
    'mimeType' => $file->mimeType,
    'title' => $file->title
  );
  $changes = new Google_Service_Calendar_Event(array(
    'attachments' => $attachments
  ));

  $calendarService->events->patch($calendarId, $eventId, $changes, array(
    'supportsAttachments' => TRUE
  ));
}

پایتون

def add_attachment(calendarService, driveService, calendarId, eventId, fileId):
    file = driveService.files().get(fileId=fileId).execute()
    event = calendarService.events().get(calendarId=calendarId,
                                         eventId=eventId).execute()

    attachments = event.get('attachments', [])
    attachments.append({
        'fileUrl': file['alternateLink'],
        'mimeType': file['mimeType'],
        'title': file['title']
    })

    changes = {
        'attachments': attachments
    }
    calendarService.events().patch(calendarId=calendarId, eventId=eventId,
                                   body=changes,
                                   supportsAttachments=True).execute()

مهم: باید قبل از فعال کردن پارامتر supportsAttachments برای تغییرات رویداد، هنگام افزودن پشتیبانی پیوست‌ها به برنامه موجود خود که رویدادها را به صورت محلی ذخیره می‌کند، همه رویدادها را همگام‌سازی کامل انجام دهید. اگر ابتدا همگام‌سازی را انجام ندهید، ممکن است ناخواسته پیوست‌های موجود را از رویدادهای کاربر حذف کنید.

کنفرانس های ویدئویی و تلفنی را به رویدادها اضافه کنید

می‌توانید رویدادها را با کنفرانس‌های Hangouts و Google Meet مرتبط کنید تا به کاربران خود اجازه دهید از راه دور از طریق تماس تلفنی یا تماس ویدیویی ملاقات کنند.

از فیلد conferenceData می توان برای خواندن، کپی و پاک کردن جزئیات کنفرانس موجود استفاده کرد. همچنین می توان از آن برای درخواست تولید کنفرانس های جدید استفاده کرد. برای اجازه ایجاد و اصلاح جزئیات کنفرانس، پارامتر درخواست conferenceDataVersion را روی 1 تنظیم کنید.

همانطور که با conferenceData.conferenceSolution.key.type مشخص شده است، در حال حاضر سه نوع conferenceData پشتیبانی می شود:

1. Hangouts برای مشتریان ( eventHangout )
2. Hangouts کلاسیک برای کاربران Google Workspace (منسوخ شده؛ eventNamedHangout )
3. Google Meet ( hangoutsMeet )

می‌توانید با نگاه کردن به conferenceProperties.allowedConferenceSolutionTypes در calendars و مجموعه‌های calendarList ، یاد بگیرید که کدام نوع کنفرانس برای هر تقویم مشخصی از یک کاربر پشتیبانی می‌شود. همچنین می‌توانید با بررسی تنظیمات autoAddHangouts در مجموعه settings ، متوجه شوید که آیا کاربر ترجیح می‌دهد Hangouts برای همه رویدادهای تازه ایجاد شده‌اش ایجاد شود یا خیر.

علاوه بر type ، conferenceSolution name و فیلدهای iconUri را نیز ارائه می دهد که می توانید از آنها برای نمایش راه حل کنفرانس مانند شکل زیر استفاده کنید:

جاوا اسکریپت

const solution = event.conferenceData.conferenceSolution;

const content = document.getElementById("content");
const text = document.createTextNode("Join " + solution.name);
const icon = document.createElement("img");
icon.src = solution.iconUri;

content.appendChild(icon);
content.appendChild(text);

شما می توانید با ارائه یک createRequest با یک requestId ایجاد شده جدید که می تواند یک string تصادفی باشد، یک کنفرانس جدید برای یک رویداد ایجاد کنید. کنفرانس ها به صورت ناهمزمان ایجاد می شوند، اما همیشه می توانید وضعیت درخواست خود را بررسی کنید تا به کاربران خود اطلاع دهید که چه اتفاقی می افتد.

به عنوان مثال، برای درخواست تولید کنفرانس برای یک رویداد موجود:

جاوا اسکریپت

const eventPatch = {
  conferenceData: {
    createRequest: {requestId: "7qxalsvy0e"}
  }
};

gapi.client.calendar.events.patch({
  calendarId: "primary",
  eventId: "7cbh8rpc10lrc0ckih9tafss99",
  resource: eventPatch,
  sendNotifications: true,
  conferenceDataVersion: 1
}).execute(function(event) {
  console.log("Conference created for event: %s", event.htmlLink);
});

پاسخ فوری به این تماس ممکن است هنوز حاوی اطلاعات پرجمعیت conferenceData نباشد. این با یک کد وضعیت در pending در فیلد وضعیت نشان داده می شود. پس از تکمیل اطلاعات کنفرانس، کد وضعیت به success تغییر می کند. فیلد entryPoints حاوی اطلاعاتی است در مورد اینکه کدام URIهای ویدیو و تلفن برای شماره گیری کاربران شما در دسترس است.

اگر می‌خواهید چندین رویداد تقویم را با جزئیات کنفرانس یکسان برنامه‌ریزی کنید، می‌توانید کل conferenceData از یک رویداد به رویداد دیگر کپی کنید.

کپی کردن در شرایط خاص مفید است. به عنوان مثال، فرض کنید در حال توسعه یک برنامه استخدام هستید که رویدادهای جداگانه ای را برای نامزد و مصاحبه کننده تنظیم می کند - می خواهید از هویت مصاحبه کننده محافظت کنید، اما همچنین می خواهید مطمئن شوید که همه شرکت کنندگان به یک تماس کنفرانسی ملحق می شوند.

مهم: هنگام افزودن پشتیبانی کنفرانس به برنامه موجود خود که رویدادها را به صورت محلی ذخیره می‌کند، باید قبل از فعال کردن پشتیبانی از داده‌های کنفرانس (با تنظیم پارامتر درخواست conferenceDataVersion روی 1 برای تغییرات رویداد) همه رویدادها را به طور کامل همگام‌سازی کنید. اگر ابتدا همگام‌سازی را انجام ندهید، ممکن است به‌طور ناخواسته کنفرانس‌های موجود را از رویدادهای کاربران حذف کنید.