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

Bạn có thể tìm thấy loại sự kiện ở những nơi 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 chính sách này, 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ề.
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 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 những tài nguyên chính của API Lịch Google. Chúng hỗ trợ nhiều thuộc tính mà bạn có thể dùng để tuỳ chỉnh thêm sự kiện.

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

Ngày sinh nhật là sự kiện đặc biệt kéo dài cả ngày và diễn ra hằng năm.

Người dùng có thể tự tạo sự kiện ngày sinh trên Lịch Google. Ngoài ra, thông tin về ngày sinh nhật 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 nhật cũng như những ngày quan trọng khác của người đó 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, thì ngày sinh nhật sẽ xuất hiện 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 sẽ được điền sẵn nếu bạn đặt type thành 'custom'.
contact: Tên tài nguyên của người liên hệ mà sự kiện đặc biệt này được liên kết (nếu có). Tham số này có định dạng 'people/c12345' và có thể dùng để tìm nạp thông tin liên hệ từ People API.

API này cho phép tạo sự kiện sinh nhật bằng phương thức insert theo các quy cách 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 và diễn ra đú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ó tần suất lặp lại hằng năm, tức là trường recurrence phải là 'RRULE:FREQ=YEARLY'. Sự kiện sinh nhật rơi vào ngày 29 tháng 2 phải có quy tắc định kỳ sau đây: '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', đồng thời cả customTypeName và contact đều phải trống.
Không được có bất kỳ thuộc tính sự kiện nào khác.

API này 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 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 và chính xác một ngày. Bạn không thể cập nhật thông tin 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 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.

Những yêu cầu tìm cách 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 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, thì tất cả các loại sự kiện, kể cả ngày sinh nhật, 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 ngày sinh 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

Sự kiện được tạo tự động từ Gmail có loại sự kiện là '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 này 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ách sử dụ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 cá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ì sự kiện từ Gmail sẽ xuất hiện 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 bạn không chỉ định loại nào, thì tất cả các loại sự kiện, kể cả 'fromGmail', sẽ được đăng ký.

Bạn có thể xoá các 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 cách sử dụ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 Google Calendar API để 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 không làm việc 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ữ kịch bản đám mây dựa trên JavaScript, cho phép bạn tạo các ứng dụng 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 chỉnh sửa 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. Bạn cũng có thể xem Hướng dẫn nhanh về Google Apps Script để bắt đầu sử dụng Apps Script nhằm gửi yêu cầu đến Google Calendar API.

Các 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 một 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 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 đượ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 cách sử dụ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 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 tiêu chuẩn khác. Sau khi thiết lập dự án Google Cloud, hãy chọn 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 các sự kiện có giá trị eventType khác nhau.

Dán nội dung sau vào trình chỉnh sửa 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. Khi thay đổi giá trị này, bạn có thể đọ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ã nhận dạng của 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 chỉnh sửa mã, hãy chọn hàm cần chạy trong trình đơn thả xuống, rồi nhấp vào Chạy.
Trong lần thực thi đầu tiên, hệ thống sẽ nhắc bạn uỷ 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ổ.