สร้างเหตุการณ์

ลองจินตนาการถึงแอปที่ช่วยผู้ใช้ค้นหาเส้นทางเดินป่าที่ดีที่สุด การเพิ่มแผนเดินป่าเป็นกิจกรรมในปฏิทินจะช่วยให้ผู้ใช้ได้รับความช่วยเหลือมากมายในการจัดระเบียบโดยอัตโนมัติ Google ปฏิทินช่วยให้คุณแชร์แผนและช่วยเตือนคุณเกี่ยวกับแผนดังกล่าวเพื่อให้คุณเตรียมตัวได้อย่างไร้กังวล นอกจากนี้ ด้วยการผสานรวมผลิตภัณฑ์ Google อย่างราบรื่น Google Now จะใช้คำสั่ง ping เกี่ยวกับเวลาออกเดินทางและ Google Maps จะนำลูกค้าไปยังจุดนัดพบตรงเวลา

บทความนี้อธิบายวิธีสร้างกิจกรรมในปฏิทินและเพิ่มกิจกรรมดังกล่าวลงในปฏิทินของผู้ใช้

เพิ่มกิจกรรม

หากต้องการสร้างเหตุการณ์ ให้เรียกใช้เมธอด events.insert() โดยระบุพารามิเตอร์ต่อไปนี้เป็นอย่างน้อย

• calendarId คือตัวระบุปฏิทิน ซึ่งอาจเป็นอีเมลของปฏิทินที่จะสร้างกิจกรรมหรือคีย์เวิร์ดพิเศษ 'primary' ที่จะใช้ปฏิทินหลักของผู้ใช้ที่เข้าสู่ระบบ หากไม่ทราบอีเมลของปฏิทินที่ต้องการใช้ คุณสามารถตรวจสอบได้ในการตั้งค่าปฏิทินของ Web UI ของ Google ปฏิทิน (ในส่วน "ที่อยู่ปฏิทิน") หรือจะค้นหาในผลการเรียกใช้ calendarList.list() ก็ได้
• event คือเหตุการณ์ที่จะสร้างพร้อมรายละเอียดที่จำเป็นทั้งหมด เช่น เริ่มต้นและสิ้นสุด ช่องที่ต้องกรอกเพียง 2 ช่องคือ 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 ปฏิทินอยู่เสมอ รวมถึงป้องกันไม่ให้มีการสร้างกิจกรรมซ้ำหากการดำเนินการล้มเหลวในบางจุดหลังจากที่ดำเนินการในแบ็กเอนด์ของปฏิทินเรียบร้อยแล้ว หากไม่ได้ระบุรหัสเหตุการณ์ เซิร์ฟเวอร์จะสร้างรหัสให้คุณ ดูข้อมูลเพิ่มเติมในข้อมูลอ้างอิงรหัสเหตุการณ์

ผู้เข้าร่วม

กิจกรรมที่คุณสร้างจะปรากฏใน Google ปฏิทินหลักทั้งหมดของ

ผู้เข้าร่วมที่คุณรวมไว้กับรหัสกิจกรรมเดียวกัน หากคุณตั้งค่า sendNotifications เป็น true ในคำขอแทรก ผู้เข้าร่วมจะได้รับการแจ้งเตือนทางอีเมลสำหรับกิจกรรมด้วย ดูข้อมูลเพิ่มเติมได้ในคู่มือกิจกรรมที่มีผู้เข้าร่วมหลายคน

ตัวอย่างต่อไปนี้แสดงการสร้างเหตุการณ์และการตั้งค่าข้อมูลเมตา

Go

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

Java

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

JavaScript

// 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);

Python

# 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'))

Ruby

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}"

เพิ่มไฟล์แนบในไดรฟ์ลงในกิจกรรม

คุณสามารถแนบไฟล์ Google ไดรฟ์ เช่น บันทึกการประชุมในเอกสาร งบประมาณในชีต งานนำเสนอในสไลด์ หรือไฟล์ Google ไดรฟ์อื่นๆ ที่เกี่ยวข้องกับกิจกรรมในปฏิทินได้ คุณสามารถเพิ่มไฟล์แนบได้เมื่อสร้างกิจกรรมด้วย events.insert() ขึ้นไปโดยเป็นส่วนหนึ่งของการอัปเดต เช่น events.patch()

การแนบไฟล์ Google ไดรฟ์กับกิจกรรมมี 2 ส่วน ได้แก่

1. รับ URL ของไฟล์ alternateLink, title และ mimeType จาก แหล่งข้อมูลไฟล์ของ Drive API โดยปกติจะใช้เมธอด files.get()
2. สร้างหรืออัปเดตเหตุการณ์ด้วยการตั้งค่าช่อง attachments ในเนื้อหาคําขอ และตั้งค่าพารามิเตอร์ supportsAttachments เป็น true

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีอัปเดตเหตุการณ์ที่มีอยู่เพื่อเพิ่มไฟล์แนบ

Java

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
  ));
}

Python

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 ที่รองรับอยู่ 3 ประเภทตามที่ระบุไว้โดย conferenceData.conferenceSolution.key.type ดังนี้

1. Hangouts สำหรับผู้ใช้ทั่วไป (eventHangout)
2. Hangouts แบบคลาสสิกสำหรับ Google Workspace ผู้ใช้ (เลิกใช้งานแล้ว eventNamedHangout)
3. Google Meet (hangoutsMeet)

คุณสามารถดูประเภทการประชุมที่รองรับสำหรับปฏิทินใดก็ได้ของผู้ใช้โดยดูที่ conferenceProperties.allowedConferenceSolutionTypes ในคอลเล็กชัน calendars และ calendarList นอกจากนี้ คุณยังดูได้ว่าผู้ใช้ต้องการให้มีการสร้าง Hangouts สำหรับกิจกรรมที่สร้างขึ้นใหม่ทั้งหมดหรือไม่โดยดูที่การตั้งค่า autoAddHangouts ในคอลเล็กชัน settings

นอกเหนือจาก type แล้ว conferenceSolution ยังมีช่อง name และ iconUri ที่ใช้แสดงโซลูชันการประชุมได้ดังที่แสดงด้านล่าง

JavaScript

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 แบบสุ่ม ระบบจะสร้างการประชุมแบบไม่พร้อมกัน แต่คุณสามารถตรวจสอบสถานะคำขอได้ทุกเมื่อเพื่อแจ้งให้ผู้ใช้ทราบถึงสิ่งที่เกิดขึ้น

ตัวอย่างเช่น หากต้องการขอสร้างการประชุมสําหรับกิจกรรมที่มีอยู่ ให้ทําดังนี้

JavaScript

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 ในช่องstatus รหัสสถานะจะเปลี่ยนเป็น success หลังจากป้อนข้อมูลการประชุมแล้ว ช่อง entryPoints มีข้อมูลเกี่ยวกับ URI ของวิดีโอและโทรศัพท์ที่ผู้ใช้โทรเข้าได้

หากต้องการกำหนดเวลากิจกรรมในปฏิทินหลายรายการที่มีรายละเอียดการประชุมเดียวกัน คุณสามารถคัดลอก conferenceData ทั้งหมดจากกิจกรรมหนึ่งไปยังอีกกิจกรรมหนึ่งได้

การคัดลอกมีประโยชน์ในบางสถานการณ์ ตัวอย่างเช่น สมมติว่าคุณกำลังพัฒนาแอปพลิเคชันการรับสมัครงานซึ่งตั้งค่าเหตุการณ์แยกต่างหากสำหรับผู้สมัครและผู้สัมภาษณ์ โดยคุณต้องการปกป้องตัวตนของผู้สัมภาษณ์ แต่ก็ต้องการตรวจสอบว่าผู้เข้าร่วมทุกคนเข้าร่วมการประชุมทางโทรศัพท์เดียวกัน

สำคัญ: คุณต้องซิงค์ทั้งหมดกิจกรรมทั้งหมดก่อนที่จะเปิดใช้การรองรับข้อมูลการประชุม (โดยการตั้งค่าพารามิเตอร์คำขอ conferenceDataVersion เป็น 1 สำหรับการแก้ไขกิจกรรม) เมื่อเพิ่มการรองรับการประชุมลงในแอปที่มีอยู่ซึ่งจัดเก็บกิจกรรมไว้ในเครื่อง หากไม่ทำการซิงค์ก่อน คุณอาจนำการประชุมที่มีอยู่ออกจากกิจกรรมของผู้ใช้โดยไม่ตั้งใจ