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

Lịch và sự kiện

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

Lịch

Lịch là một tập hợp các sự kiện có liên quan, cùng với siêu dữ liệu bổ sung như bản 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. Lịch có thể có nhiều chủ sở hữu.

Sự kiện

Sự kiện là một đối tượng liên kết với một ngày hoặc phạm vi thời gian cụ thể. Các sự kiện được xác định bằng mã nhận dạng duy nhất. Ngoài ngày giờ bắt đầu và kết thúc, sự kiện còn chứa các dữ liệu khác như 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ợ sự kiện đơn và lặp lại:

Một sự kiện duy nhất đại diện cho một lần xuất hiện duy nhất.
Sự kiện định kỳ xác định nhiều lần xuất hiện.

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

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

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

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 phần tử 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 này thường khớp với địa chỉ email chính của người dùng. Miễn là tài khoản còn tồn tại, người dùng sẽ không bao giờ xoá được hoặc "bỏ quyền sở hữu" đối với lịch chính của tài khoản. Tuy nhiên, bạn vẫn có thể chia sẻ tệp đó với người dùng khác.

Ngoài lịch chính, bạn có thể tạo bất kỳ số lượng lịch nào khác một cách rõ ràng; bạn có thể sửa đổi, xoá và chia sẻ các lịch này giữa nhiều người dùng.

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ể dùng quyền 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 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 phương thức 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 có thể sử dụng thuộc tính này để truy xuất và đặt giá trị của các 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 phép toán tử cho hai tập hợp:

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

Sự kiện định kỳ

Một số sự kiện diễn ra nhiều lần theo lịch biểu thông thường, chẳng hạn như các cuộc họp hằng tuần, 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 đã định. Sự kiện đơn không định kỳ và chỉ xảy ra một lần.

Quy tắc lặp lại

Lịch biểu cho một 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 độc lập) và
Trường lặp lại (xác định cách lặp lại sự kiện theo thời gian).

Trường định kỳ chứa một mảng các chuỗi đại diện cho một hoặc nhiều thuộc tính RRULE, RDATE hoặc EXDATE 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. Thành phần này bao gồm một số thành phần. Một số trong số đó là:

FREQ – Tần suất lặp lại sự kiện (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ột lần sau mỗi hai ngày.
COUNT – Số lần lặp lại sự kiện này.

Bạn có thể sử dụng hàm COUNT hoặc UNTIL để chỉ định thời điểm kết thúc sự kiện định kỳ. 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ẽ lặp lại cho đến ngày đó (bao gồm cả ngày đó).
BYDAY – Ngày trong tuần mà sự kiện sẽ 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ờ khác mà sự kiện sẽ xảy ra. Ví dụ: RDATE;VALUE=DATE:19970101,19970120. Sử dụng phương thức này để thêm các lần xuất hiện khác không thuộc phạm vi của RRULE.

Thuộc tính EXDATE tương tự như RDATE, nhưng chỉ định ngày hoặc ngày giờ mà sự kiện không xảy ra. Tức là bạn nên loại trừ những lần xuất hiện đó. Tham số này phải trỏ đến một thực thể hợp lệ do quy tắc định kỳ 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 diễn ra cả ngày.

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

Dưới đây là một số ví dụ về sự kiện định kỳ:

Một sự kiện diễn ra từ 6 giờ sáng đến 7 giờ sáng vào thứ Ba và thứ Sáu, bắt đầu từ ngày 15 tháng 9 năm 2015 và dừng lại sau lầ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 kéo dài cả ngày bắt đầu từ ngày 1 tháng 6 năm 2015 và lặp lại sau mỗi 3 ngày trong suốt tháng, ngoại trừ ngày 10 tháng 6 nhưng bao gồm cả 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"
],
…
```

Phiên bản và ngoại lệ

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

Nội dung sửa đổ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 phiên bản của sự kiện đó) hoặc chỉ ảnh hưởng đến từng phiên bản riêng lẻ. Các thực thể khác với sự kiện định kỳ mẹ được gọi là ngoại lệ.

Ví dụ: một trường hợp ngoại lệ có thể có bản tóm tắt, thời gian bắt đầu khác hoặc những người tham dự khác chỉ được mời tham gia phiên đó. 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ỳ (các yêu cầu huỷ thực thể sẽ được phản ánh trong sự kiện status).

Bạn có thể xem ví dụ về cách xử lý các sự kiện và phiên bản định kỳ 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 đồng nhất. Trong API Lịch Google, bạn chỉ định múi giờ bằng cách sử dụng giá trị 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ả tác độ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ờ theo 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 phương thức events.get(), events.list() và events.instances().

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ặc định.
So khớp sự kiện diễn ra cả ngày với các truy vấn có khung thời gian: Các phương thức list() và instances() cho phép bạn chỉ định bộ lọc thời gian bắt đầu và kết thúc, với phương thức 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 thời gian bắt đầu và kết thúc của các sự kiện diễn ra 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à 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 một số cách; tất cả các cách sau đề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 (điều 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 múi giờ UTC: 2017-01-25T14:00:00Z hoặc sử dụng độ lệch bằng 0 2017-01-25T14:00:00+0000.

Cách trình bày nội bộ thời gian sự kiện 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:

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

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