Lịch và sự kiện

Hướng dẫn này mô tả về lịch, sự kiện và mối quan hệ giữa chúng.

Lịch

Lịch là một tập hợp các sự kiện liên quan, cùng với siêu dữ liệu bổ sung như nội dung tóm tắt, múi giờ mặc định, vị trí, v.v. Mỗi lịch được xác định bằng một mã nhận dạng, đó là địa chỉ email. Bạn có thể chia sẻ lịch với người khác. Lịch chính thuộc sở hữu của tài khoản người dùng được liên kết, các lịch khác thuộc sở hữu của một chủ sở hữu dữ liệu.

Sự kiện

Sự kiện là một đối tượng được liên kết với một ngày hoặc phạm vi thời gian cụ thể. Sự kiện được xác định bằng một mã nhận dạng duy nhất. Ngoài ngày và giờ bắt đầu và kết thúc, sự kiện còn chứa các dữ liệu khác như nội dung tóm tắt, nội dung mô tả, vị trí, trạng thái, lời nhắc, tệp đính kèm, v.v.

Các loại sự kiện

Lịch Google hỗ trợ các sự kiện diễn ra một lần và lặp lại:

Sự kiện diễn ra một lần đại diện cho một lần xuất hiện duy nhất.
Sự kiện lặp lại xác định nhiều lần xuất hiện.

Sự kiện cũng có thể là sự kiện có thời gian hoặc cả ngày:

Sự kiện có thời gian diễn ra giữa hai thời điểm cụ thể. Sự kiện có thời gian sử dụng các trường start.dateTime và end.dateTime để chỉ định thời điểm diễn ra sự kiện.
Sự kiện cả ngày kéo dài trong cả ngày hoặc một chuỗi ngày liên tiếp. Sự kiện cả ngày sử dụng các trường start.date và end.date để chỉ định thời điểm diễn ra sự kiện. Xin lưu ý rằng trường múi giờ không có ý nghĩa đối với sự kiện cả ngày.

Thời gian bắt đầu và kết thúc của sự kiện phải là thời gian cụ thể hoặc cả ngày. Ví dụ: việc chỉ định start.date và end.dateTime là không hợp lệ.

Người tổ chức

Sự kiện có một người tổ chức duy nhất, đó là lịch chứa bản sao chính của sự kiện. Sự kiện cũng có thể có nhiều người tham dự. Người tham dự thường là lịch chính của người dùng được mời.

Sơ đồ sau đây cho thấy mối quan hệ khái niệm giữa lịch, sự kiện và các thành phần liên quan khác:

Lịch chính và các lịch khác

Lịch chính là một loại lịch đặc biệt được liên kết với một tài khoản người dùng. Lịch này được tạo tự động cho mỗi tài khoản người dùng mới và mã nhận dạng của lịch thường khớp với địa chỉ email chính của người dùng. Miễn là tài khoản tồn tại, người dùng sẽ không bao giờ có thể xoá hoặc "huỷ sở hữu" lịch chính của tài khoản. Tuy nhiên, bạn vẫn có thể chia sẻ lịch này với những người dùng khác.

Ngoài lịch chính, bạn có thể tạo rõ ràng bất kỳ số lượng lịch nào khác. Bạn có thể sửa đổi, xoá và chia sẻ các lịch này với người khác. Các lịch như vậy có một chủ sở hữu dữ liệu duy nhất có đặc quyền cao nhất, bao gồm cả quyền xoá lịch. Không thể hạ cấp quyền truy cập của chủ sở hữu dữ liệu. Ban đầu, chủ sở hữu dữ liệu được xác định là người dùng đã tạo lịch, tuy nhiên, quyền sở hữu dữ liệu có thể được chuyển trong giao diện người dùng của Lịch Google.

Lịch và danh sách lịch

Tập hợp Lịch đại diện cho tất cả các lịch hiện có. Bạn có thể sử dụng tập hợp này để tạo và xoá lịch. Bạn cũng có thể truy xuất hoặc đặt các thuộc tính chung được chia sẻ trên tất cả người dùng có quyền truy cập vào lịch. Ví dụ: tiêu đề và múi giờ mặc định của lịch là các thuộc tính chung.

CalendarList là một tập hợp tất cả các mục nhập lịch mà người dùng đã thêm vào danh sách của họ (hiển thị trong bảng điều khiển bên trái của giao diện người dùng web). Bạn có thể sử dụng tập hợp này để thêm và xoá các lịch hiện có vào/khỏi danh sách của người dùng. Bạn cũng sử dụng tập hợp này để truy xuất và đặt các giá trị của thuộc tính lịch dành riêng cho người dùng, chẳng hạn như lời nhắc mặc định. Một ví dụ khác là màu nền trước, vì mỗi người dùng có thể đặt màu khác nhau cho cùng một lịch.

Bảng sau đây so sánh ý nghĩa của các thao tác cho hai tập hợp:

Hoạt động	Lịch	CalendarList
`insert`	Tạo lịch phụ mới. Lịch này cũng được thêm vào danh sách lịch của người tạo và không thể xoá, trừ phi lịch bị xoá hoặc chuyển.	Chèn một lịch hiện có vào danh sách của người dùng.
`delete`	Xoá lịch phụ.	Xoá lịch khỏi danh sách của người dùng.
`get`	Truy xuất siêu dữ liệu lịch, ví dụ: tiêu đề, múi giờ.	Truy xuất siêu dữ liệu cộng với thông tin tuỳ chỉnh dành riêng cho người dùng chẳng hạn như màu hoặc lời nhắc ghi đè.
`patch`/`update`	Sửa đổi siêu dữ liệu lịch.	Sửa đổi thuộc tính lịch dành riêng cho người dùng.

Sự kiện lặp lại

Một số sự kiện diễn ra nhiều lần theo lịch trình thường xuyên, chẳng hạn như cuộc họp hằng tuần, ngày sinh nhật và ngày lễ. Ngoài việc có thời gian bắt đầu và kết thúc khác nhau, các sự kiện lặp lại này thường giống hệt nhau.

Sự kiện được gọi là lặp lại nếu sự kiện đó lặp lại theo lịch trình đã xác định. Sự kiện diễn ra một lần không lặp lại và chỉ diễn ra một lần.

Quy tắc lặp lại

Lịch trình cho sự kiện định kỳ được xác định trong hai phần:

Các trường bắt đầu và kết thúc (xác định lần xuất hiện đầu tiên, như thể đây chỉ là một sự kiện diễn ra một lần độc lập) và
Trường lặp lại (xác định cách sự kiện sẽ được lặp lại theo thời gian).

Trường lặp lại chứa một mảng các chuỗi đại diện cho một hoặc nhiều RRULE, RDATE hoặc EXDATE thuộc tính như được xác định trong RFC 5545.

Thuộc tính RRULE là quan trọng nhất vì thuộc tính này xác định một quy tắc thông thường để lặp lại sự kiện. Thuộc tính này bao gồm một số thành phần. Một số thành phần trong đó là:

FREQ – Tần suất mà sự kiện sẽ được lặp lại (chẳng hạn như DAILY hoặc WEEKLY). Bắt buộc.
INTERVAL – Hoạt động cùng với FREQ để chỉ định tần suất lặp lại sự kiện. Ví dụ: FREQ=DAILY;INTERVAL=2 có nghĩa là mỗi ngày một lần.
COUNT – Số lần sự kiện này sẽ được lặp lại.

Bạn có thể sử dụng COUNT hoặc UNTIL để chỉ định thời điểm kết thúc sự kiện lặp lại. Không sử dụng cả hai trong cùng một quy tắc.
UNTIL – Ngày hoặc ngày giờ mà sự kiện sẽ được lặp lại (bao gồm cả ngày hoặc ngày giờ đó).
BYDAY – Các ngày trong tuần mà sự kiện sẽ được lặp lại (SU, MO, TU, v.v.). Các thành phần tương tự khác bao gồm BYMONTH, BYYEARDAY và BYHOUR.

Thuộc tính RDATE chỉ định các ngày hoặc ngày giờ bổ sung khi các lần xuất hiện sự kiện sẽ diễn ra. Ví dụ: RDATE;VALUE=DATE:19970101,19970120. Sử dụng thuộc tính này để thêm các lần xuất hiện bổ sung không được RRULE bao gồm.

Thuộc tính EXDATE tương tự như RDATE, nhưng chỉ định các ngày hoặc ngày giờ mà sự kiện không diễn ra. Tức là những lần xuất hiện đó sẽ bị loại trừ. Thuộc tính này phải trỏ đến một thực thể hợp lệ do quy tắc lặp lại tạo ra.

EXDATE và RDATE có thể có múi giờ và phải là ngày (không phải ngày giờ) đối với sự kiện cả ngày.

Mỗi thuộc tính có thể xuất hiện nhiều lần trong trường lặp lại. Sự kiện lặp lại được xác định là sự kết hợp của tất cả các quy tắc RRULE và RDATE, trừ những quy tắc bị loại trừ bởi tất cả các quy tắc EXDATE.

Dưới đây là một số ví dụ về sự kiện lặp lại:

Một sự kiện diễn ra từ 6 giờ sáng đến 7 giờ sáng vào mỗi thứ Ba và thứ Sáu, bắt đầu từ ngày 15 tháng 9 năm 2015 và dừng sau lần xuất hiện thứ năm vào ngày 29 tháng 9:

...
"start": {
 "dateTime": "2015-09-15T06:00:00+02:00",
 "timeZone": "Europe/Zurich"
},
"end": {
 "dateTime": "2015-09-15T07:00:00+02:00",
 "timeZone": "Europe/Zurich"
},
"recurrence": [
 "RRULE:FREQ=WEEKLY;COUNT=5;BYDAY=TU,FR"
],
…

Một sự kiện cả ngày bắt đầu vào ngày 1 tháng 6 năm 2015 và lặp lại 3 ngày một lần trong suốt tháng, ngoại trừ ngày 10 tháng 6 nhưng bao gồm ngày 9 tháng 6 và 11 tháng 6:

...
"start": {
 "date": "2015-06-01"
},
"end": {
 "date": "2015-06-02"
},
"recurrence": [
 "EXDATE;VALUE=DATE:20150610",
 "RDATE;VALUE=DATE:20150609,20150611",
 "RRULE:FREQ=DAILY;UNTIL=20150628;INTERVAL=3"
],
…

Thực thể và trường hợp ngoại lệ

Sự kiện định kỳ bao gồm một số lần xuất hiện: các lần xuất hiện cụ thể của sự kiện vào những thời điểm khác nhau. Các thực thể này hoạt động như chính các sự kiện.

Các sửa đổi đối với sự kiện định kỳ có thể ảnh hưởng đến toàn bộ sự kiện định kỳ (và tất cả các thực thể của sự kiện đó) hoặc chỉ ảnh hưởng đến các thực thể riêng lẻ. Các thực thể khác với sự kiện định kỳ mẹ được gọi là trường hợp ngoại lệ.

Ví dụ: trường hợp ngoại lệ có thể có nội dung tóm tắt khác, thời gian bắt đầu khác hoặc người tham dự bổ sung chỉ được mời tham dự thực thể đó. Bạn cũng có thể huỷ hoàn toàn một thực thể mà không cần xoá sự kiện định kỳ (việc huỷ thực thể được phản ánh trong status sự kiện).

Bạn có thể xem các ví dụ về cách làm việc với sự kiện lặp lại và thực thể thông qua API Lịch Google tại đây.

Múi giờ

Múi giờ chỉ định một khu vực tuân theo giờ chuẩn thống nhất. Trong API Lịch Google, bạn chỉ định múi giờ bằng cách sử dụng mã nhận dạng múi giờ IANA.

Bạn có thể đặt múi giờ cho cả lịch và sự kiện. Các phần sau đây mô tả ảnh hưởng của các chế độ cài đặt này.

Múi giờ của lịch

Múi giờ của lịch còn được gọi là múi giờ mặc định do ảnh hưởng của múi giờ này đối với kết quả truy vấn. Múi giờ của lịch ảnh hưởng đến cách các giá trị thời gian được diễn giải hoặc trình bày bằng các events.get(), events.list() và events.instances() phương thức.

Chuyển đổi múi giờ của kết quả truy vấn: Kết quả của các phương thức get(), list() và instances() được trả về theo múi giờ mà bạn chỉ định trong tham số timeZone. Nếu bạn bỏ qua tham số này, thì tất cả các phương thức này đều sử dụng múi giờ của lịch làm múi giờ mặc định.
Khớp các sự kiện cả ngày với các truy vấn có dấu ngoặc thời gian: Các list() và instances() phương thức cho phép bạn chỉ định bộ lọc thời gian bắt đầu và thời gian kết thúc, trong đó phương thức này trả về các thực thể nằm trong phạm vi đã chỉ định. Múi giờ của lịch được dùng để tính toán thời gian bắt đầu và thời gian kết thúc của các sự kiện cả ngày nhằm xác định xem các sự kiện đó có nằm trong thông số kỹ thuật của bộ lọc hay không.

Múi giờ của sự kiện

Các thực thể sự kiện có thời gian bắt đầu và thời gian kết thúc; thông số kỹ thuật cho các thời gian này có thể bao gồm múi giờ. Bạn có thể chỉ định múi giờ theo nhiều cách; tất cả các cách sau đây đều chỉ định cùng một thời gian:

Thêm độ lệch múi giờ vào trường dateTime, ví dụ: 2017-01-25T09:00:00-0500.
Chỉ định thời gian không có độ lệch, ví dụ: 2017-01-25T09:00:00, để trống trường timeZone (trường này ngầm sử dụng múi giờ mặc định).
Chỉ định thời gian không có độ lệch, ví dụ: 2017-01-25T09:00:00, nhưng sử dụng trường timeZone để chỉ định múi giờ.

Bạn cũng có thể chỉ định thời gian sự kiện theo giờ UTC nếu muốn:

Chỉ định thời gian theo giờ UTC: 2017-01-25T14:00:00Z hoặc sử dụng độ lệch bằng 0 2017-01-25T14:00:00+0000.

Biểu diễn nội bộ của thời gian sự kiện là giống nhau trong tất cả các trường hợp này, nhưng việc đặt trường timeZone sẽ đính kèm múi giờ vào sự kiện, giống như khi bạn đặt múi giờ của sự kiện bằng giao diện người dùng Lịch UI:

Múi giờ của sự kiện định kỳ

Đối với sự kiện lặp lại, bạn phải luôn chỉ định một múi giờ. Bạn cần múi giờ này để mở rộng các lần lặp lại của sự kiện.

Lịch và sự kiện Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Lịch

Sự kiện

Các loại sự kiện

Người tổ chức

Lịch chính và các lịch khác

Lịch và danh sách lịch

Sự kiện lặp lại

Quy tắc lặp lại

Thực thể và trường hợp ngoại lệ

Múi giờ

Múi giờ của lịch

Múi giờ của sự kiện

Múi giờ của sự kiện định kỳ

Lịch và sự kiện