Trang này được dịch bởi Cloud Translation API.

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ư sự kiện được thiết kế cho các trường hợp sử dụng cụ thể và có các thuộc tính tuỳ chỉnh.

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

Tất cả sự kiện đều được trả về bằng eventType.
Bạn cần đặt eventType khi tạo hoặc cập nhật tài nguyên sự kiện. Nếu bạn không đặt, hệ thống sẽ sử dụng loại 'default'.
Bạn có thể chỉ định eventTypes trong lệnh gọi Events:list để liệt kê các sự kiện thuộc cá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ề.
Bạn có thể chỉ định eventTypes 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 một số 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à dùng làm một trong các tài nguyên chính của API Lịch Google. Các sự kiện này hỗ trợ nhiều loại thuộc tính có thể dùng để tuỳ chỉnh thêm sự kiện.

Hãy xem phần 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à 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 về 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 như 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 các sự kiện sinh nhật. Bạn có thể đặt eventTypes 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ì sinh nhật 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, 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. Giá trị này được điền nếu bạn đặt type thành 'custom'.
contact: Tên tài nguyên của người liên hệ được liên kết với sự kiện đặc biệt này (nếu có). Mã này có định dạng 'people/c12345' và có thể được dùng để tìm nạp thông tin liên hệ từ API People.

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'.
Các trường start và end cần xác định một sự kiện kéo dài cả ngày, kéo dài đúng một ngày.
Giá trị trường visibility phải là 'private'.
Giá trị trường transparency phải là 'transparent'.
Cần có chu kỳ lặp lại hằng năm, nghĩa là trường recurrence phải là 'RRULE:FREQ=YEARLY'. Sự kiện sinh nhật 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 lẫn 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 cách sử dụng các phương thức update và patch. Bạn cũng có thể cập nhật các trường start và end để 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, kéo dài đúng 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 một sự kiện sinh nhật nếu sự kiện đó được liên kết với một 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 bằng 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 API People 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 riêng họ trên hồ sơ Tài khoản Google và ngày sinh này 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 này hỗ trợ thao tác import cho các sự kiện sinh nhật; tuy nhiên, sự kiện này 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 này hỗ trợ phương thức watch để đăng ký nhận thông báo về các thay đổi đối với sự kiện sinh nhật trên Lịch Google. Bạn có thể đặt eventTypes thành 'birthday' để đăng ký nhận thông tin cập nhật về sự kiện sinh nhật. Nếu bạn không chỉ định loại nào, 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á các sự kiện sinh nhật bằng phương thức delete của API Lịch Google. Việc xoá một sự kiện sinh nhật khỏi Lịch Google sẽ không ảnh hưởng đến dữ liệu trên Danh bạ Google hoặc hồ sơ Tài khoản Google.

Phương thức move hoặc update không hỗ trợ việc thay đổi người tổ chức sự kiện sinh nhật.

Sự kiện từ Gmail

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 các phương thức update và patch.

API này hỗ trợ các phương thức get và list để đọc sự kiện từ Gmail. Bạn có thể đặt eventTypes 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 này hỗ trợ phương thức watch để đăng ký nhận thông báo về các thay đổi đối với sự kiện từ Gmail trên Lịch Google. Nếu không chỉ định loại nào, 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.

Chúng tôi không hỗ trợ việc thay đổi người tổ chức sự kiện trong 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ể 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.

Những 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ý thời gian tập trung, thời gian nghỉ phép và sự kiện vị trí 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 kinh doanh tích hợp với Google Workspace. Tập lệnh được phát triển trong 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. Xem thêm phần Bắt đầu nhanh với Google Apps Script để bắt đầu sử dụng Apps Script nhằm 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 cách sử dụng API Lịch Google làm 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.
Trong ngăn bên trái, bên cạnh mục Dịch vụ, hãy nhấp vào biểu tượng Thêm dịch vụ .
Chọn Google Calendar API rồi nhấp vào Thêm.
Sau khi 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ó sẵn trong API bằng cách sử dụng từ khoá Calendar (Lịch) trong trình chỉnh sửa.

(Không bắt buộc) Cập nhật dự án trên Google Cloud

Mỗi dự án Google Apps Script đều có một dự án Google Cloud được liên kết. 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 tuỳ chỉnh trên Google Cloud, hãy xem phần Chuyển sang một dự án Cloud chuẩn khác. Sau khi thiết lập dự án Google Cloud, hãy chọn biểu tượng Trình chỉnh sửa ở bên trái để quay lại trình chỉnh sửa 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 với nhiều giá trị eventType.

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/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/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/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. Ban đầu, hằng số này được đặt thành 'primary'. Đây là 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 để 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, ứng dụng sẽ nhắc bạn uỷ quyền truy cập. Xem lại 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ổ.