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

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

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

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

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

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

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

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

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

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

مکان
اضافه کردن آدرس به فیلد مکان، قابلیت‌هایی مانند «زمان حرکت» یا نمایش نقشه با مسیرها را فعال می‌کند.
شناسه رویداد
هنگام ایجاد یک رویداد، می‌توانید شناسه رویداد خود را که با الزامات قالب ما مطابقت دارد، ایجاد کنید. این به شما امکان می‌دهد تا موجودیت‌ها را در پایگاه داده محلی خود با رویدادهای تقویم گوگل همگام نگه دارید. همچنین در صورتی که عملیات در مقطعی پس از اجرای موفقیت‌آمیز در باطن تقویم با شکست مواجه شود، از ایجاد رویداد تکراری جلوگیری می‌کند. اگر هیچ شناسه رویدادی ارائه نشود، سرور یکی برای شما ایجاد می‌کند. برای اطلاعات بیشتر به مرجع شناسه رویداد مراجعه کنید.
شرکت‌کنندگان
رویدادی که ایجاد می‌کنید در تمام تقویم‌های اصلی گوگل شرکت‌کنندگانی که با شناسه رویداد یکسان در آن قرار داده‌اید، نمایش داده می‌شود. اگر در درخواست درج خود، sendUpdates روی "all" یا "externalOnly" تنظیم کنید، شرکت‌کنندگان مربوطه یک اعلان ایمیل برای رویداد شما دریافت می‌کنند. برای کسب اطلاعات بیشتر، به رویدادهایی با چندین شرکت‌کننده مراجعه کنید.

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

برو

// Refer to the Go quickstart on how to setup the environment:
// https://developers.google.com/workspace/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:"lpage@example.com"},
    &calendar.EventAttendee{Email:"sbrin@example.com"},
  },
}

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/workspace/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("lpage@example.com"),
    new EventAttendee().setEmail("sbrin@example.com"),
};
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/workspace/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': 'lpage@example.com'},
    {'email': 'sbrin@example.com'}
  ],
  '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);
});

نود جی اس

// Refer to the Node.js quickstart on how to setup the environment:
// https://developers.google.com/workspace/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': 'lpage@example.com'},
    {'email': 'sbrin@example.com'},
  ],
  '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);
});

پی اچ پی

$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' => 'lpage@example.com'),
    array('email' => 'sbrin@example.com'),
  ),
  '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/workspace/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': 'lpage@example.com'},
    {'email': 'sbrin@example.com'},
  ],
  '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: 'lpage@example.com'
    ),
    Google::Apis::CalendarV3::EventAttendee.new(
      email: 'sbrin@example.com'
    )
  ],
  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 به رویدادها

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

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

  1. آدرس اینترنتی (URL)، title ) و mimeType فایل alternateLink را از منبع فایل‌ها (Files) API درایو (Drive API) دریافت کنید، که معمولاً با استفاده از متد 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();
}

پی اچ پی

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()

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

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

فیلد conferenceData می‌تواند برای خواندن، کپی کردن و پاک کردن جزئیات کنفرانس موجود استفاده شود؛ همچنین می‌تواند برای درخواست ایجاد کنفرانس‌های جدید استفاده شود. برای ایجاد و تغییر جزئیات کنفرانس، پارامتر درخواست conferenceDataVersion را روی 1 تنظیم کنید.

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

  1. پاتوق برای مصرف‌کنندگان ( eventHangout )
  2. Hangouts کلاسیک برای کاربران Google Workspace (منسوخ شده؛ eventNamedHangout )
  3. گوگل میت ( 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);

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

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

جاوا اسکریپت

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

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

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

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

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