Loại sự kiện

Trang này giải thích thuộc tính eventType và thông số kỹ thuật của các loại sự kiện có trong API Lịch Google.

Lịch Google cho phép người dùng tạo sự kiện chung, cũng như các sự kiện được thiết kế cho các trường hợp sử dụng cụ thể và có thuộc tính tuỳ chỉnh.

Bạn có thể khám phá loại sự kiện ở những vị trí sau trong API:

Tất cả sự kiện đều được trả về bằng eventType.
eventType cần được đặt khi tạo hoặc cập nhật tài nguyên sự kiện. Nếu bạn không đặt, 'default' hệ thống sẽ sử dụng loại.
eventTypes có thể được chỉ định trong lệnh gọi Events:list để liệt kê các sự kiện thuộc loại cụ thể. Nếu bạn không chỉ định loại nào, thì tất cả các loại sự kiện sẽ được trả về.
eventTypes có thể được chỉ định trong lệnh gọi Events:watch để đăng ký nhận thông tin cập nhật về các sự kiện thuộc loại cụ thể. Nếu bạn không chỉ định loại nào, thì yêu cầu sẽ dẫn đến việc đăng ký tất cả các loại sự kiện.

Sự kiện mặc định

Các sự kiện có loại sự kiện default được tạo và sử dụng làm một trong những tài nguyên chính của API Lịch Google. Chúng hỗ trợ nhiều thuộc tính có thể dùng để tuỳ chỉnh thêm sự kiện.

Hãy xem bài viết Tạo sự kiện để bắt đầu làm việc với các sự kiện trên Lịch Google.

Sinh nhật

Sinh nhật là những sự kiện đặc biệt kéo dài cả ngày và lặp lại hằng năm.

Người dùng có thể tự tạo sự kiện sinh nhật trên Lịch Google. Ngoài ra, thông tin ngày sinh sẽ đồng bộ hoá với Lịch Google khi người dùng thêm một người và thêm ngày sinh của họ cùng các ngày quan trọng khác vào Danh bạ Google. Ngày sinh của người dùng cũng được đồng bộ hoá với Lịch Google từ hồ sơ Tài khoản Google của họ.

API Lịch Google hỗ trợ các phương thức get, instances và list để đọc sự kiện sinh nhật. eventTypes có thể được đặt thành 'birthday' để chỉ liệt kê các sự kiện sinh nhật. Nếu bạn không chỉ định loại nào, thì ngày sinh sẽ được liệt kê cùng với tất cả các loại sự kiện khác.

Trong các đối tượng Event được trả về, hãy kiểm tra trường birthdayProperties để biết thêm thông tin chi tiết về sự kiện đặc biệt này. birthdayProperties có các trường sau:

type: Loại sự kiện đặc biệt này, cho dù đó là sinh nhật, ngày kỷ niệm hay một ngày quan trọng khác.
customTypeName: Nhãn do người dùng chỉ định cho sự kiện đặc biệt này. Trường này được điền nếu type được đặt thành 'custom'.
contact: Tên tài nguyên của danh bạ mà sự kiện đặc biệt này được liên kết (nếu có). Trường này có định dạng 'people/c12345' và có thể dùng để tìm nạp thông tin chi tiết về danh bạ từ People API.

API cho phép tạo sự kiện sinh nhật bằng phương thức insert với các thông số kỹ thuật sau:

eventType được đặt thành 'birthday'.
start và end trường cần xác định một sự kiện cả ngày kéo dài chính xác một ngày.
visibility giá trị trường phải là 'private'.
transparency giá trị trường phải là 'transparent'.
Cần có quy tắc lặp lại hằng năm, nghĩa là trường recurrence phải là 'RRULE:FREQ=YEARLY'. Các sự kiện sinh nhật rơi vào ngày 29 tháng 2 phải có quy tắc lặp lại sau: 'RRULE:FREQ=YEARLY;BYMONTH=2;BYMONTHDAY=-1'.
Có thể có colorId, summary và reminders.
Có thể có birthdayProperties. Nếu được chỉ định, type phải là 'birthday', và cả customTypeName và contact đều phải trống.
Không thể có bất kỳ thuộc tính sự kiện nào khác.

API cho phép cập nhật colorId, summary và reminders của các sự kiện sinh nhật bằng phương thức update và patch. start và end trường cũng có thể được cập nhật để thay đổi ngày diễn ra sự kiện. Trong trường hợp này, các giá trị mới cần xác định một sự kiện kéo dài cả ngày và chính xác một ngày. Bạn không thể cập nhật thông tin chi tiết về thời gian của sự kiện sinh nhật nếu sự kiện đó được liên kết với contact hoặc type của sự kiện là 'self'.

API Lịch Google không cho phép tạo sự kiện sinh nhật có birthdayProperties tuỳ chỉnh hoặc cập nhật các thuộc tính này. Bạn có thể chỉnh sửa các ngày quan trọng bằng People API và các thay đổi sẽ được đồng bộ hoá với Lịch Google. Tương tự, người dùng có thể chỉnh sửa ngày sinh của chính mình trên hồ sơ Tài khoản Google và ngày sinh đó sẽ đồng bộ hoá với Lịch Google.

Các yêu cầu cố gắng tạo hoặc cập nhật ngày sinh theo cách không được hỗ trợ sẽ không thành công. Trong trường hợp này, hãy kiểm tra thông báo lỗi để xác định vấn đề.

API hỗ trợ thao tác import cho các sự kiện sinh nhật; tuy nhiên, sự kiện sẽ được nhập dưới dạng sự kiện mặc định. Nói cách khác, eventType sẽ là 'default'.

API hỗ trợ phương thức watch để đăng ký nhận thông tin thay đổi về các sự kiện sinh nhật trên Lịch Google. eventTypes có thể được đặt thành 'birthday' để đăng ký nhận thông tin cập nhật về các sự kiện sinh nhật. Nếu bạn không chỉ định loại nào, thì tất cả các loại sự kiện, bao gồm cả ngày sinh, sẽ được đăng ký.

Bạn có thể xoá sự kiện sinh nhật bằng phương thức delete của API Lịch Google. Việc xoá sự kiện sinh nhật khỏi Lịch Google không ảnh hưởng đến dữ liệu trên Danh bạ Google hoặc hồ sơ Tài khoản Google.

Bạn không thể thay đổi người tổ chức sự kiện sinh nhật bằng phương thức move hoặc update.

Sự kiện từ Gmail

Các sự kiện được tạo tự động từ Gmail có loại sự kiện 'fromGmail'.

API Lịch Google không cho phép tạo loại sự kiện này bằng phương thức insert.

API cho phép cập nhật các thuộc tính mở rộng colorId, reminders, visibility, transparency, status, attendees, private và shared bằng phương thức update và patch.

API hỗ trợ các phương thức get và list để đọc sự kiện từ Gmail. eventTypes có thể được đặt thành 'fromGmail' để chỉ liệt kê các sự kiện được tạo từ Gmail. Nếu bạn không chỉ định loại nào, thì các sự kiện từ Gmail sẽ được liệt kê cùng với tất cả các loại sự kiện khác.

API hỗ trợ phương thức watch để đăng ký nhận thông tin thay đổi về các sự kiện từ Gmail trên Lịch Google. Nếu bạn không chỉ định loại nào, thì tất cả các loại sự kiện, bao gồm cả 'fromGmail', sẽ được đăng ký.

Bạn có thể xoá sự kiện từ Gmail bằng phương thức delete của API Lịch Google.

Bạn không thể thay đổi người tổ chức sự kiện từ Gmail bằng phương thức move hoặc update.

Thời gian cần tập trung, trạng thái không có mặt tại văn phòng và địa điểm làm việc

Bạn có thể sử dụng API Lịch Google để tạo và quản lý các sự kiện cho biết trạng thái của người dùng Lịch Google.

Các tính năng này chỉ có trên lịch chính và chỉ dành cho một số người dùng Lịch Google. Hãy xem bài viết Quản lý sự kiện thời gian cần tập trung, trạng thái không có mặt tại văn phòng và địa điểm làm việc để tìm hiểu thêm.

Khám phá các loại sự kiện trong Google Apps Script

Google Apps Script là một ngôn ngữ tập lệnh đám mây dựa trên JavaScript cho phép bạn xây dựng các ứng dụng dành cho doanh nghiệp tích hợp với Google Workspace. Các tập lệnh được phát triển trong một trình soạn thảo mã dựa trên trình duyệt, đồng thời được lưu trữ và chạy trên máy chủ của Google. Hãy xem bài viết Hướng dẫn bắt đầu nhanh về Google Apps Script để bắt đầu sử dụng Apps Script gửi yêu cầu đến API Lịch Google.

Hướng dẫn sau đây mô tả cách đọc và quản lý sự kiện bằng API Lịch Google dưới dạng một dịch vụ nâng cao trong Google Apps Script. Để xem danh sách đầy đủ các tài nguyên và phương thức của API Lịch Google, hãy xem tài liệu tham khảo.

Tạo và thiết lập tập lệnh

Tạo tập lệnh bằng cách truy cập vào script.google.com/create.
Trên ngăn bên trái bên cạnh Services (Dịch vụ), hãy nhấp vào biểu tượng Add a service (Thêm dịch vụ) .
Chọn Google Calendar API (API Lịch Google) rồi nhấp vào Add (Thêm).
Sau khi được bật, API sẽ xuất hiện trên ngăn bên trái. Bạn có thể liệt kê các phương thức và lớp có trong API bằng từ khoá Calendar trong trình chỉnh sửa.

(Không bắt buộc) Cập nhật dự án trên đám mây

Mỗi dự án Google Apps Script đều có một dự án liên kết trên Google Cloud. Tập lệnh của bạn có thể sử dụng dự án mặc định mà Google Apps Script tự động tạo. Nếu bạn muốn sử dụng một dự án trên đám mây tuỳ chỉnh của Google, hãy xem bài viết Chuyển sang một dự án trên đám mây tiêu chuẩn khác. Sau khi thiết lập dự án trên Google Cloud, hãy chọn Editor ở bên trái để quay lại trình soạn thảo mã.

Thêm mã vào tập lệnh

Mã mẫu sau đây cho biết cách liệt kê, đọc và tạo sự kiện có các giá trị eventType khác nhau.

Dán nội dung sau vào trình soạn thảo mã.

const CALENDAR_ID = 'CALENDAR_ID' || 'primary';

/** Lists default events. */
function listDefaultEvents() {
  listEvents('default');
}

/** Lists birthday events. */
function listBirthdays() {
  listEvents('birthday');
}

/** Lists events from Gmail. */
function listEventsFromGmail() {
  listEvents('fromGmail');
}

/**
  * Lists events with the given event type. If no type is specified, lists all events.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/list
  */
function listEvents(eventType = undefined) {
  // Query parameters for the list request.
  const optionalArgs = {
    eventTypes: eventType ? [eventType] : undefined,
    singleEvents: true,
    timeMax: '2024-07-30T00:00:00+01:00',
    timeMin: '2024-07-29T00:00:00+01:00',
  }
  try {
    var response = Calendar.Events.list(CALENDAR_ID, optionalArgs);
    response.items.forEach(event => console.log(event));
  } catch (exception) {
    console.log(exception.message);
  }
}

/**
  * Reads the event with the given eventId.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/get
  */
function readEvent() {
  try {
    var response = Calendar.Events.get(CALENDAR_ID, 'EVENT_ID');
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

/** Creates a default event. */
function createDefaultEvent() {
  const event = {
    start: { dateTime: '2024-07-30T10:30:00+01:00'},
    end: { dateTime: '2024-07-30T12:30:00+01:00'},
    description: 'Created from Apps Script.',
    eventType: 'default',
    summary: 'Sample event',
  }
  createEvent(event);
}

/** Creates a birthday event. */
function createBirthday() {
  const event = {
    start: { date: '2024-01-29' },
    end: { date: '2024-01-30' },
    eventType: 'birthday',
    recurrence: ["RRULE:FREQ=YEARLY"],
    summary: "My friend's birthday",
    transparency: "transparent",
    visibility: "private",
  }
  createEvent(event);
}

/**
  * Creates a Calendar event.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/insert
  */
function createEvent(event) {

  try {
    var response = Calendar.Events.insert(event, CALENDAR_ID);
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

Thay thế nội dung sau:

CALENDAR_ID: Địa chỉ email của lịch để truy xuất và tạo sự kiện. Hằng số này ban đầu được đặt thành 'primary', đây là một từ khoá để truy cập vào lịch chính của người dùng đã đăng nhập. Việc thay đổi giá trị này cho phép bạn đọc các sự kiện trên lịch của những người dùng khác mà bạn có quyền truy cập.
EVENT_ID: Mã sự kiện. Bạn có thể gọi Events:list để truy xuất mã sự kiện.

Chạy mã mẫu

Phía trên trình soạn thảo mã, hãy chọn hàm cần chạy trong trình đơn thả xuống rồi nhấp vào Run (Chạy).
Trong lần thực thi đầu tiên, hệ thống sẽ nhắc bạn cấp quyền truy cập. Xem xét và cho phép Apps Script truy cập vào lịch của bạn.
Bạn có thể kiểm tra kết quả thực thi tập lệnh trong Execution Log (Nhật ký thực thi) xuất hiện ở cuối cửa sổ.